Docs » Synchronization Edit on GitHub


There are two requests in our Synchronization API: Ping and Sequence. Ping is a tiny request that you receive from us, both periodically and after certain events. Sequence is a request that you make when you want to pull changes.

Ping Service

You can configure as many endpoints as you like. We recommend that you use TLS, but this is not a requirement. Pings are HTTP POST requests with the following headers and JSON fields:

HTTP/1.1 headersDescription
Base64 encoded HMAC-SHA2-256 signature of the body signed with your API key. Read more.
JSON fieldsDescription
Global seq counter for your shop. This will increment with every new transaction, capture and refund.
The shopid associated with this ping.

We will ping you every time your global seq increases and every 5 minutes (periodic pings). You will have to store a local seq counter and use this to determine if your system is synchronized. If this is not the case then you should pull the changes with a Sequence Request. Explained with pseudocode:

if Base64(HMAC-SHA2-256(body, apikey))  headers['X-Signature'] then
    log 'Warning: Invalid ping signature!'
ping := jsondecode(body)
if ping.seq > localseq then
    // Pull changes with a sequence request...

Sequence Request

To get changes send a HTTP GET request to$localseq, where $localseq is your locally stored seq counter. Your request will need to have the following header:

HTTP/1.1 headersDescription
HTTP Basic authentication. Read more.


All successful responses have a 200 HTTP status code and a JSON object with the following fields:

JSON fieldsDescription
The seq of the last change in this response. This is your new localseq, but not necessarily your global seq counter.
An array with zero or more changes since the requested seq, but not necessarily all changes.
  • id: Transaction id.
  • rev: Transaction revision number representing the number of changes made to this transaction. Rev will start at 1 and increment with actions (e.g. capture/refund) and other changes to this transaction.
  • orderid: The orderid that you assigned when you created the payment link (here).
  • time: Unix timestamps.
  • acts: Cumulative array of actions in this transaction.
  • totals: The relevant values for this transaction.
  • error: An error message. You should skip the change if this happens.

Now you will have to loop through the response and apply the changes to your database. It's important that you do this transactionally, and/or handle race conditions. Explained with pseudocode:

data := jsondecode(GET + localseq)
for trn in data.changes do
    if trn.error is set then
        log trn.error // Contact us if this happens

    trnid, email := MySQL(
        SELECT trnid, email FROM orders
            WHERE trnid = '' OR orderid = 'trn.orderid' FOR UPDATE;
        UPDATE orders SET trnid = '', rev = 'trn.rev', ...
            WHERE (trnid = '' OR orderid = 'trn.orderid') AND rev < 'trn.rev';

    if trnid = 0 then
        sendmail(email, "Order confirmation ...")

MySQL(UPDATE globals SET seq = 'data.seq' WHERE seq < 'data.seq')