Implementation notes
The reference says what each request does. These notes say how to put the requests together so that nothing is lost, nothing happens twice, and nothing breaks under load: the problems we see most often in integrations, and their fixes.
| Note | What it covers |
|---|---|
| Synchronizing with seq | Matching our objects to yours, applying changes by revision, running one synchronization at a time, and what seq guarantees. |
| Receiving pings | Checking the signature, answering fast, and what to do when pings stop. |
| Orders and payment links | One link per order, the success page that proves nothing, payments for less than the order, and links that must not be paid. |
| Retries and idempotency | Requests that time out, keys that make retries safe, and the index that stops two acts from the same state. |
| Charging subscribers | The schedule, failed charges and when to retry them, and getting a new card. |
| Websites and apps | Sending the payer to the payment window and back, and why not in a frame or a WebView. |
| Moving from v1 to v2 | The URLs and keys, the stricter requests, the clearer errors, and the requests that are new. |
| Before going live | A checklist of all of the above. |
The notes hold for every version of the API. Where the versions differ, a paragraph that starts "In v1," or "In v2," says how. The notes assume the reference, and link to it. Where a rule comes from outside the API, such as how long an authorization lasts, they link to the knowledge base.