Confirm the order and recovery - Sapiom Pay

After checkout submits, keep reading the transaction until order.outcome is final. Only confirmed means the buyer has an order.

Read the transaction

{
  "name": "sapiom_get_transaction",
  "arguments": {
    "transactionId": "00000000-0000-4000-8000-000000000003",
    "since": "<last version you saw>",
    "waitSeconds": 20
  }
}

waitSeconds (0 to 22) holds the call open until something changes. since is the version from your last read. Reading never pays and never contacts the merchant.

`order.outcome`	Meaning	What to do
`confirmed`	The merchant completed the checkout.	Tell the buyer their order is placed.
`not_confirmed`	No order yet.	Follow `nextAction`.
`unknown`	The order may or may not exist.	Keep this transaction and follow `nextAction`. Never buy again.

Refresh the checkout

When nextAction.type is reconcile_checkout, Sapiom needs a fresh look at the merchant’s checkout. Your backend calls the refresh route with the buyer’s key, then your agent reads the transaction again:

curl --request POST \
  "https://api.sapiom.ai/v1/transactions/$TRANSACTION_ID/ucp/checkout/refresh" \
  -H "x-api-key: $SAPIOM_BUYER_KEY"

Recover without buying twice

Situation	Do this
A request timed out, or `nextAction.type` is `resend_request`	Send the same request with the same key.
You have a `transactionId` but the outcome is uncertain	Keep reading and refreshing that transaction. Never start another.
`idempotency_conflict`	That key belongs to a different request. Check the original merchant, checkout and card.
An error before the merchant opened checkout	Follow the error’s `nextStep`. Some fixes need a corrected request and a new key.
Browser Pay reported `refused`, `failed` or `relayed_unfulfilled`	Keep reading and refreshing the same transaction.
An update or cancel timed out	Stop. Your team reconciles it with the merchant, using the original key.

Error formats and codes are in Errors.