> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sapiom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Sapiom is for platforms whose agent shops for many users. Each user has their own Sapiom user key and saved cards.
> Use the user's key for every call made on that user's behalf. Never use one user's key for another user, and never give the agent the platform key.
> Backends call the REST API at https://api.sapiom.ai/v1. Agents can also call the hosted MCP tools at https://api.sapiom.ai/v1/mcp/pay. Both take the key in an x-api-key header.
> Keys that start with sk_test_ reach the sandbox, a separate environment with its own users and cards, at the same addresses. Use test card numbers only there.
> Never ask a user for a card number, expiry date or CVV in chat. Users enter card details only on Sapiom's hosted pages.
> Check the merchant before buying. Use purchase.type ucp_checkout only when the merchant check returns supported. Otherwise use browser_checkout.
> Follow the nextAction in each transaction result. Action links are secrets. Send each one only to the person `nextAction.actor` names.
> Use one idempotency key per transaction. Resume an unanswered create with the same request and key. If a UCP update or cancellation is uncertain, stop and hand off to a person. If a browser cancellation is uncertain, read the transaction and resend the same cancellation, with the same key, only if it is not closed. Never start a new transaction to escape an uncertain outcome.
> For a ucp_checkout purchase, report an order as placed only when order.outcome is confirmed; if it is unknown, stop and hand off to a person. A browser_checkout purchase has no order confirmation (order is null): confirm the order on the merchant's page.

# Webhooks

We notify you if the purchase needs something.&#x20;

<ol>
  <li>
    1

    Receive
    Sapiom sends an event to your receiver.
  </li>

  <li>
    2

    Verify
    Check the signature on the request.
  </li>

  <li>
    3

    Store and respond
    Save the event, then reply within 10 seconds.
  </li>

  <li>
    4

    Read the transaction
    Follow its next action.
  </li>
</ol>

Create one webhook (HTTPS receiver) for your platform. This covers all of your users and checkout types.

## Register your receiver

Use an API key from **Create key** in the dashboard's [API keys](https://app.sapiom.ai/dashboard/api-keys); it has the `org.write` permission this needs. A platform key from **Create platform key** doesn't.  Store `signingSecret` server-side only.

```bash theme={null}
curl -X PUT "https://api.sapiom.ai/v1/organizations/$ORGANIZATION_ID/payment-webhook" \
  -H "x-api-key: $SAPIOM_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.example/webhooks/sapiom"}'

# The response has "url" and "signingSecret" ("whsec_..."). Keep the secret in your backend.
```

## Verify the signature

Sapiom signs each request with the Standard Webhooks headers. Verify them with your signing secret:

```typescript verify-webhook.ts theme={null}
import { Webhook } from "standardwebhooks"; // npm install standardwebhooks

// Pass the raw request body. verify() throws if the signature or timestamp is wrong.
export function verifyPaymentWebhook(rawBody: Buffer, h: Record<string, string>, secret: string) {
  return new Webhook(secret).verify(rawBody.toString("utf8"), {
    "webhook-id": h["webhook-id"], "webhook-timestamp": h["webhook-timestamp"], "webhook-signature": h["webhook-signature"],
  });
}
```

## Events

Sapiom sends three events:

* `transaction.action_required` (`action`: `human_approval` or `security_code`)
* `transaction.payment_ready`
* `transaction.closed` (`status` `denied` or `cancelled`, `reason`)

Each event names its transaction. Read the purchase after each one:

```json theme={null}
{
  "version": 1, "id": "<event-id>", "type": "transaction.action_required",
  "organizationId": "<organization-id>", "tenantId": "<user-id>",
  "transactionId": "<transaction-id>", "occurredAt": "2026-11-12T14:30:00.000Z",
  "data": { "action": "security_code", "actionId": "<security-code-request-id>" }
}
```

## Retries and duplicates

Sapiom retries after about a minute, backing off to six hours. A retry has the same event `id`, so ignore ids you've already seen.

## Read, replace or remove the receiver

Replacing the URL keeps the signing secret. To read the receiver:

```bash theme={null}
curl "https://api.sapiom.ai/v1/organizations/$ORGANIZATION_ID/payment-webhook" \
  -H "x-api-key: $SAPIOM_ORG_KEY"
```

To replace it, send the same `PUT` as above with the new URL. To remove it:

```bash theme={null}
curl -X DELETE "https://api.sapiom.ai/v1/organizations/$ORGANIZATION_ID/payment-webhook" \
  -H "x-api-key: $SAPIOM_ORG_KEY"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.