Authorize a transaction from a UCP checkout

A transaction ties one merchant checkout to one of the buyer’s saved cards. Your agent sends the checkout, Sapiom opens it with the merchant and checks it against your rules, and each result says what to do next. Before you start:

Your agent is connected with the buyer’s key.
The buyer has a card that is ready to pay. See Vault a card.
sapiom_check_transaction_compatibility returns supported for the merchant.
Your browser worker is ready to finish checkout.

Where each step runs

Step	Runs in	Uses
Request, read, update or cancel the transaction	Your agent	MCP tools, buyer key
Send approval links to the buyer	Your agent or app	Links from `nextAction`
Fill and submit checkout	Your browser worker	Browser Pay, buyer key
Refresh a checkout when asked	Your backend	REST, buyer key

Your backend stores each buyer’s key and passes it to the agent and the browser worker for that buyer’s session.

Request the transaction

{
  "name": "sapiom_request_transaction",
  "arguments": {
    "idempotencyKey": "order-7f3a",
    "merchantOrigin": "https://shop.example",
    "checkout": {
      "currency": "USD",
      "line_items": [
        { "id": "line-1", "item": { "id": "merchant-product-id" }, "quantity": 1 }
      ],
      "buyer": { "email": "jane@example.com" }
    },
    "paymentMethodId": "00000000-0000-4000-8000-000000000001"
  }
}

checkout is a UCP checkout request. item.id is the merchant’s product ID; the line id is your own label.
paymentMethodId is the id of the buyer’s chosen card.
idempotencyKey is your own unique ID for this transaction. See below.

The result includes a transactionId. Save it: every later step uses it. All arguments are in the MCP tools reference. Calling Sapiom from your backend instead? See Use REST instead.

Keep the same idempotency key

The key identifies this transaction. If a request times out or you lose the response, send the identical request with the same key to pick it back up. Don’t switch to a new key to get past an uncertain result: that can buy twice.

Follow nextAction

Every result has a nextAction object. Its type says what to do. Act on it, then read the transaction with sapiom_get_transaction to get the next one.

`type`	What to do	Fields to use
`buyer_security_code`	Send the link to the buyer. They approve the transaction by re-entering their CVV.	`url`, `expiresAt`
`payment_ready`	Pass `continueUrl` and the `transactionId` to your browser worker. See Pay in your browser.	`continueUrl`
`payment_submitted`	The card was sent to the merchant’s payment processor, which ends Sapiom’s part. Stop polling, and never pay again for this transaction.
`wait`	Wait, then read again.	`retryAfterSeconds`
`resend_request`	Send the original request again with the same key.	`retry.afterSeconds`
`update_checkout`, `revise`	The checkout needs a change. Fix it with `sapiom_update_transaction`.	`messages`, `reasons`
`merchant_escalation`	The merchant needs the buyer. Send them the link and messages.	`url`, `messages`
`complete_payment_method_setup`	Only when you passed `setupLinkId`: the buyer is still adding their card. Wait, then send the same request with the same key.	`retry.afterSeconds`
`allowance_verification`	Send the link to the buyer.	`url`, `expiresAt`
`approval`	An approval rule on your account applies. Send the link to the approver if there is one.	`url`, `expiresAt`
`reconcile_checkout`	Your backend refreshes the checkout. See Confirm the order.	`restRoute`
`blocked`, `closed`, `none`	Stop and tell the buyer why.	`reason`, `messages`

Change or cancel a transaction

Change: sapiom_update_transaction replaces the whole checkout. Send transactionId, the latest version, a new stable idempotencyKey for this change, and the full checkout. Changing items or the total can mean the buyer approves again.
Cancel: sapiom_cancel_transaction with transactionId and an idempotencyKey. It cannot stop a checkout that is already completing, and it does not refund an order.

Use REST instead

Your backend can run the same transaction with the buyer’s key.

Create a transaction. estimate is your expected total and is optional. Omit paymentCardId to use the buyer’s default card.

curl -X POST https://api.sapiom.ai/v1/transactions \
  -H "x-api-key: $SAPIOM_BUYER_KEY" \
  -H "x-idempotency-key: order-7f3a" \
  -H "Content-Type: application/json" \
  -d '{
    "requestFacts": {
      "source": "ucp-checkout",
      "version": "v1",
      "sdk": {},
      "request": {
        "merchantOrigin": "https://shop.example",
        "estimate": { "amount": "248.00", "currency": "USD" }
      }
    },
    "funding": { "source": "external_card", "paymentCardId": "00000000-0000-4000-8000-000000000001" }
  }'

Open the checkout with POST /v1/transactions/{id}/ucp/checkout, sending the UCP line_items and buyer. If you sent shipping when you created the transaction, leave out buyer.
Read nextAction.action in each response. While it’s update, replace the checkout with PUT on the same path.

Both checkout calls take an Idempotency-Key header. REST names some actions differently from the MCP tools:

REST `nextAction.action`	MCP `nextAction.type`
`update`	`update_checkout`
`requires_action`	`buyer_security_code`, `approval`, `allowance_verification` or `merchant_escalation`, by `kind`
`hand_off`	`payment_ready`
`submitted`	`payment_submitted`
`refresh`	`reconcile_checkout`
`done`	`none`

wait, revise, blocked and closed have the same names.

Get started

Buyers

Cards

Transactions

Governance

Security

Early access

Authorize a transaction from a UCP checkout

Where each step runs

Request the transaction

Keep the same idempotency key

Follow nextAction

Change or cancel a transaction

Use REST instead

​Where each step runs

​Request the transaction

​Keep the same idempotency key

​Follow nextAction

​Change or cancel a transaction

​Use REST instead

Where each step runs

Request the transaction

Keep the same idempotency key

Follow nextAction

Change or cancel a transaction

Use REST instead