Skip to main content

Integration Options: Where the Check Runs

A control only works if the agent can't go around it. The safest options are enforced outside the agent, by your payment provider or by the service that holds your payment credentials. None of them asks you to share payment credentials with Auditail.

OptionWhere it's enforcedYour setupAuditail holdsBlocks?
A. Card authorizations (Stripe Issuing)The card network: Stripe asks Auditail before approving each card paymentPaste one URL into StripeStripe's webhook signing secret onlyYes
B. Provider approval webhook (Airwallex, Modern Treasury)The provider's own approval stepTurn on an approval rule, add a webhookThe provider's webhook signing secret onlyThe provider's reviewer does, with Auditail's verdict in hand
C. One-line check (checkReceipt())Your payout serviceOne line where you execute payoutsNothingYes, if the agent can't reach the provider directly
D. guard() in the agent (quickstart)The agent's own processOne call per toolNothingOnly if the agent cooperates
If your agent holds the payment API key, only A and B protect you

With options C and D, an agent (or whoever has tricked it) that has your Stripe, bank or Airwallex key can call the provider directly and skip Auditail. Keep payment keys out of the agent's environment, or use A or B, which the provider enforces.


A. Stripe Issuing: real-time card authorizations​

Give each agent its own Stripe Issuing virtual card. For every purchase, Stripe sends Auditail an authorization request, and Auditail approves or declines it from your policy, limits and kill switch, inside Stripe's 2-second window.

1. Create the connection (approver token). Use your Stripe webhook signing secret (whsec_...) for this endpoint:

curl -X POST https://api.auditail.io/v1/connections -H "Authorization: Bearer $AUDITAIL_APPROVER_TOKEN" \
-H "content-type: application/json" \
-d '{"provider": "stripe_issuing", "signingSecret": "whsec_...", "label": "Agent cards", "action": "card_payment"}'
# {"id":"pc_...","url":"https://api.auditail.io/hooks/pc_...","mode":"enforcing", ...}

2. In the Stripe Dashboard (Issuing settings), set the real-time authorization webhook to that url. Set the timeout fallback to decline, so a card payment is declined if Stripe can't reach Auditail.

3. Tell Auditail which agent owns each card by setting card metadata auditail_agent_id (for example procurement-agent). Cards without it are recorded as card:<card id>.

4. Write the policy for card_payment:

{ "defaultAction": "deny", "actions": { "card_payment": {
"deny": [{ "field": "merchant.categoryCode", "op": "in", "value": ["7995"], "reason": "gambling merchants are blocked" }],
"firstTime": [{ "field": "merchant.networkId", "onFirst": "deny", "known": ["1234567890", "0987654321"],
"reason": "new merchants must be added to the policy by finance first" }],
"limits": [{ "name": "daily-usd", "window": "24h", "sum": "amount", "max": 2000, "onExceed": "deny",
"when": [{ "field": "currency", "op": "==", "value": "USD" }] }] } } }

The policy sees this payload. Amounts are converted from Stripe's minor units, so $49.99 is 49.99:

{ "amount": 49.99, "amountMinor": 4999, "currency": "USD",
"merchant": { "name": "STRIPE", "category": "computer_software_stores", "categoryCode": "5734", "country": "US", "city": "SAN FRANCISCO", "networkId": "1234567890" },
"card": { "id": "ic_...", "last4": "4242" }, "cardholderId": "ich_...", "authorizationId": "iauth_...", "method": "online", "wallet": null }

How it behaves:

  • Approved only when the policy allows it. Usage counts toward limits, and the decision goes into the audit log with auditail_decision_id in the Stripe authorization's metadata.
  • Anything that would need a human is declined. Nobody can approve within 2 seconds. Use deny rules and limits for cards.
  • Fails closed. If Auditail can't decide within 1.5 seconds, or hits an error, it declines. Bursts of simultaneous decisions on one account slow down (see throughput), so many simultaneous card payments on one account can be declined this way. With Stripe's fallback set to decline, a network failure declines too.
  • Kill switch and shadow mode work as for every other action. In shadow mode every authorization is approved, and you can see what would have been declined.
  • Every request's signature is checked (Stripe-Signature, 5-minute tolerance, rolled secrets supported). Retries of the same event get the same answer.

B. Airwallex: transfers waiting for approval​

Airwallex can send transfers created through its API into its approval workflow. Auditail checks each one while it waits and tells your reviewers its verdict. Airwallex's approval step does the blocking: approval happens only in Airwallex's web app, so Auditail advises and keeps the evidence.

  1. Create the connection with "provider": "airwallex" and the webhook secret for that notification URL.
  2. In Airwallex, Developer > Webhooks, add the returned url for payout.transfer.in_approval, payout.transfer.scheduled, payout.transfer.approval_rejected, payout.transfer.approval_recalled and payout.transfer.cancelled.
  3. In Transfers > Transfer approvals, answer Yes to Require API-initiated transfers to go through the same approval workflow, and make sure the agent's credentials aren't one of the approvers.
  4. Set a notification webhook in Auditail. Reviewers get a message like "Airwallex transfer P250709-K61UKW4 (300 EUR to Acme GmbH) is waiting for approval. Auditail: DO NOT APPROVE. Denied: limit "daily-eur" would be exceeded (1,200 of 1,000 in 24h)."

What Auditail records:

  • provider.review: the verdict (OK to approve, needs a careful human check or DO NOT APPROVE) and why.
  • The outcome as your policy action (default bank_transfer): approved, rejected or cancelled in Airwallex. Approved transfers count toward limits and make the beneficiary "known" for firstTime rules.
  • Overrides: a transfer approved in Airwallex after Auditail said DO NOT APPROVE is flagged (matchedRule: "provider:override"), and your notification webhook gets a provider.override alert.

The policy sees amount, currency, sourceCurrency, method, reason, reference, and beneficiary.{id, name, country, accountLast4}. Full account numbers are never stored: beneficiary.id is Airwallex's beneficiary id, or a short hash of the bank details.

B. Modern Treasury: payment orders waiting for approval​

Modern Treasury's approval rules hold payment orders in needs_approval until a reviewer approves them in the dashboard. Auditail adds its verdict and the evidence, the same way as for Airwallex.

  1. Create the connection with "provider": "modern_treasury" and your webhook key.
  2. Add the returned url as a webhook in Modern Treasury (Developers > Webhooks).
  3. Create payment orders from the agent with the async create endpoint. Modern Treasury only sends a webhook at creation for async-created orders, and that's when Auditail can give its verdict. For orders created synchronously, Auditail still records the approval and marks it unreviewed.

Amounts are converted from minor units (amount: 123100 USD becomes 1231). beneficiary.id is the receiving account id. Set metadata.auditail_agent_id on the payment order to name the agent.

What B can't do, plainly: Auditail can't approve or reject in Airwallex or Modern Treasury, because neither provider's API allows approval. If a reviewer ignores the verdict, the payment goes ahead, and the override is recorded and reported.

Act-only agent keys​

The agent's key only needs to act. Ask us to make it act-only: it can request decisions and approvals, pull the kill switch and send events, but it can't read the audit log, exports, reports, policy or connections. People and services read with approver tokens. The SDKs work unchanged with an act-only key. During the beta we set this for you; new keys can be issued act-only from the start.

C. One-line check in your payout service​

If your agent asks your own service to pay, and that service holds the payment key, check the receipt there:

const check = await auditail.checkReceipt(receipt, { action: 'create_payout', payload });
if (!check.ok) return res.status(403).json({ error: check.reason }); // missing, invalid, expired or already used
await stripe.payouts.create(...);
check = auditail.check_receipt(receipt, action="create_payout", payload=payload) # pip install "auditail[verify]"
if not check["ok"]:
raise PermissionError(check["reason"])

checkReceipt() verifies the signature, your account, the action, the exact payload and the expiry, then redeems the receipt so it can't be used twice. Use a credential for the payout service that isn't the agent's key, for example its own approver token.

REST​

EndpointCredentialPurpose
POST /v1/connectionsApprover{ provider, signingSecret, label?, action?, stripeVersion? } → { id, url, mode, next }
GET /v1/connectionsEitherList connections (signing secrets are never returned)
DELETE /v1/connections/{id}ApproverDisable a connection
POST /hooks/{id}The provider's signatureCalled by the provider, not by you

Connecting and disconnecting are recorded in the audit log (provider.connected, provider.disconnected).

Status​

These integrations follow each provider's published documentation (November 2026), and we tested them with requests signed exactly as documented. They haven't yet run against each provider's live sandbox, so treat them as beta and tell us what you see.