Integration checklist

Run it in the sandbox with a sandbox key — see Sandbox for the amounts that force each outcome. Each item names its rule from Integration rules.

Access and requests

• Payin and payout calls use the keys of their own shops; sandbox keys only on the sandbox host. (R1, R2)
• merchant_reference is generated once and saved before the create; a retry resends the same body. (R4, R6)
• A capture or void retried after a timeout is the same call; the payin is re-read, not captured twice. (R5)
• Amounts are strings with at most two decimals. (R7)

Outcome — run each in the sandbox

• Success: amount with any cents not listed in the sandbox table reaches completed. (R8)
• Decline: .51–.56 end failed; the code is handled by status_details.code, not retried. (R9)
• Payer step: next_action is shown to the payer; .58 ends failed after the step. (R10)
• Hold: an authorized payin is captured or voided. (R11)
• An unknown status, code or event type does not break the integration. (R13)

Errors

• Code branches on error.code, retries only 429 and 500; 429 waits Retry-After. (R14)

Webhooks

• Each shop's events are verified with that shop's secret: signature, timestamp window, two signatures. (R15)
• The handler persists the event and answers 2xx within 30 seconds; a worker processes it. (R16)
• A repeated event id is ignored; an event that failed processing is retried, not lost. (R17)
• Goods are released only on a verified webhook or a read with the shop's key; a late non-final event does not override a final status. (R18)

Reconciliation

• A scheduled sync with order=updated_asc and an overlapping window reconciles against your own ledger. (R19)