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.
| Option | Where it's enforced | Your setup | Auditail holds | Blocks? |
|---|---|---|---|---|
| A. Card authorizations (Stripe Issuing) | The card network: Stripe asks Auditail before approving each card payment | Paste one URL into Stripe | Stripe's webhook signing secret only | Yes |
| B. Provider approval webhook (Airwallex, Modern Treasury) | The provider's own approval step | Turn on an approval rule, add a webhook | The provider's webhook signing secret only | The provider's reviewer does, with Auditail's verdict in hand |
C. One-line check (checkReceipt()) | Your payout service | One line where you execute payouts | Nothing | Yes, if the agent can't reach the provider directly |
D. guard() in the agent (quickstart) | The agent's own process | One call per tool | Nothing | Only if the agent cooperates |
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_idin the Stripe authorization's metadata. - Anything that would need a human is declined. Nobody can approve within 2 seconds. Use
denyrules 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.
- Create the connection with
"provider": "airwallex"and the webhook secret for that notification URL. - In Airwallex, Developer > Webhooks, add the returned
urlforpayout.transfer.in_approval,payout.transfer.scheduled,payout.transfer.approval_rejected,payout.transfer.approval_recalledandpayout.transfer.cancelled. - 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.
- 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" forfirstTimerules. - Overrides: a transfer approved in Airwallex after Auditail said DO NOT APPROVE is flagged (
matchedRule: "provider:override"), and your notification webhook gets aprovider.overridealert.
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.
- Create the connection with
"provider": "modern_treasury"and your webhook key. - Add the returned
urlas a webhook in Modern Treasury (Developers > Webhooks). - 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
| Endpoint | Credential | Purpose |
|---|---|---|
POST /v1/connections | Approver | { provider, signingSecret, label?, action?, stripeVersion? } → { id, url, mode, next } |
GET /v1/connections | Either | List connections (signing secrets are never returned) |
DELETE /v1/connections/{id} | Approver | Disable a connection |
POST /hooks/{id} | The provider's signature | Called 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.