Integration checklist

Use this checklist when you build or review an integration that buys with Sapiom. Each item links to the page that explains it.

Store for each purchase

Value	Why
Transaction `id`	Every later step uses it.
Your `Idempotency-Key`	To resume an unanswered create with the identical request. See Keep the same idempotency key.
Last `version`	To wait for the next change with `since`.
Last `nextAction`	Your agent acts on it. Do not keep a separate payment state that can disagree with it.

Get the approval when your browser worker is ready

The placeholder card works for about one hour after the buyer approves. Start the browser worker first. Then send the buyer the approval link. See Get the placeholder card.

Compare the right values

Compare	With	Do not compare
The origin of the page that has the card form	`merchant.origin`	`continueUrl` with `merchant.origin`. The host of `continueUrl` can be different.
The total on the page, as the page shows it	The total that the buyer approved	Minor units from MCP `totals` with the page text. Convert them first.

Know if the card was sent

Only the transaction tells you if the card was sent. Read it after any failure.

The transaction reads	The card was sent?	Do this
`payment_ready`	No	Pay with this transaction. If the browser session ended, start a new one. See If the browser session ends before you submit.
`wait`	Follow `reason`	Read again after `retryAfterSeconds`.
`blocked` with `reason: payment_ended`	No	Cancel the transaction. Create a new transaction if the buyer still wants it.
`payment_submitted`	Possibly	Do not pay again. Confirm the order.
`none`, with `order.outcome: confirmed`	Yes	The UCP order is complete. Show the order confirmation.
`closed`	See `message`	Follow `message`.

Do not mark a purchase as sent in your own records before the transaction reads payment_submitted or order.outcome: confirmed. A read shows the current state only. A UCP order can be confirmed before your agent sees payment_submitted. A failure before your worker submits the form does not send the card. Do not record it as uncertain.

Fill the card with code

Fill the card fields with your browser driver. Keep placeholder values out of your AI model’s prompt and out of logs. See Fill the card fields.

Recover

Situation	Do this
The create request got no answer	Send the identical request with the same key.
The browser session ended before the card form was submitted	Read the transaction and follow the table above.
The placeholder expired	The transaction reads `blocked` with `reason: payment_ended`. Cancel it and create a new one.
A UCP purchase reads `payment_submitted`, and the order is not confirmed	Do not buy again. Refresh the checkout and read the transaction. See Show the order confirmation. If the order does not confirm, tell the buyer to check with the merchant.
A browser purchase reads `payment_submitted`	Do not buy again. The merchant’s page is the only confirmation. Tell the buyer what the page showed.

All other cases are in Recover without buying twice.

Test before you go live

Make the purchases in Sandbox with the test card. Test these failures too:

Stop the browser session after the approval and before you submit. Your agent must read payment_ready and pay in a new session.
Wait more than one hour after the approval. Your agent must read payment_ended, cancel, and create a new transaction.

Get started

Buyers

Cards

Transactions

Governance

Security

Early access

Integration checklist

Store for each purchase

Get the approval when your browser worker is ready

Compare the right values

Know if the card was sent

Fill the card with code

Recover

Test before you go live

​Store for each purchase

​Get the approval when your browser worker is ready

​Compare the right values

​Know if the card was sent

​Fill the card with code

​Recover

​Test before you go live

Store for each purchase

Get the approval when your browser worker is ready

Compare the right values

Know if the card was sent

Fill the card with code

Recover

Test before you go live