Edit on GitHub

Synchronization

There are two requests in our Synchronization API: Ping and Sequence. Ping is a 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

All accounts have a consecutive sequence number called seq, which is a counter that increases when your transaction data changes. When this happens, we will send you a ping, which is a tiny HTTP POST request with the following headers and JSON fields:

HTTP/1.1 headersDescription
X-Signature: 17FUWCstyodDzsCkG5/gU/2VA2vUEcHfvFxGh8RCElo=
Base64 encoded HMAC-SHA2-256 signature of the body signed with your API key.
JSON fieldsDescription
"seq": 200Consecutive sequence number for your shop.
"shopid": 129The shopid associated with this ping.

In addition, we ping you every 5 minutes to ensure that your system is up to date. When you receive a ping, it is important that you verify the authenticity of the request. Afterwards you can look at seq to determine if there are any changes. Explained with pseudocode:

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

You can configure your ping endpoint in our dashboard (here). We recommend that you use Transport Layer Security (TLS), but this is not a requirement.

Sequence Request

A sequence request is a HTTP GET request that you make when you want to pull changes from our servers. The endpoint is https://api.scanpay.dk/v1/seq/$num, where $num is your local version of the sequence number. All requests have to be authenticated with HTTP basic authentication (more info). Successful responses have a 200 status code and a JSON body:

JSON fieldsDescription
"seq": 164The sequence number for the last change in the changes array.
"changes": [
    {
        "type": "transaction",
        …
    }
]
An array with changes after the requested sequence number in chronological order. There are 3 types of changes: transaction, subscriber and charge.

Transaction

In this context, transactions are regular payment transactions.

JSON fieldsDescription
"type": "transaction"The type of the entry.
"id": 2942The scanpay transaction ID.
"orderid": "INV3803"The order ID that you assigned to the transaction when you created the payment link.
"rev": 3A revision number. It starts at 1 and it increments every time the transaction data change.
"acts": [
    {
        "act": "capture",
        "time": 1479384886,
        "total": "100.45 DKK"
    },
    {
        "act": "refund",
        "time": 1479387243,
        "total": "42.78 DKK"
    }
]
A cumulative array of actions made to this transaction. There are 3 types of actions:
  • capture: you captured some or all of the authorized funds.
  • refund: you refunded some/all of the captured funds.
  • void: the transaction was cancelled. This can only happen if nothing has been captured (example).
"totals": {
    "authorized": "123.45 DKK",
    "captured": "100.45 DKK",
    "refunded": "42.78 DKK",
    "left": "23.00 DKK"
}
The relevant values for this transaction.
"time": {
    "created": 1479384780,
    "authorized": 1479384799
}
Unix timestamps.

Subscriber

You will receive this change if you create or renew a subscriber through our subscriptions API.

JSON fieldsDescription
"type": "subscriber"The type of the entry.
"id": 2942The subscriber ID.
"ref": "user301"The reference ID that you assigned to the subscriber when you created it (more details).
"rev": 2A revision number. It starts at 1 and it increments every time the subcriber data change.
"acts": [
    {
        "act": "renew",
        "time": 1479384799
    }
]
A cumulative array of actions made to this subscriber. As of now, there is only one type of action:
  • renew: when the payment details were renewed. See renew subscriber for more details.
"time": {
    "created": 1479384780
}
Unix timestamps.

Charge

You will receive this change if you charge a subscriber through our subscriptions API.

JSON fieldsDescription
"type": "charge"The type of the entry.
"id": 38189The scanpay transaction ID.
"orderid": "c123"The order ID that you assigned to the charge when you created it (more details).
"rev": 7A revision number. It starts at 1 and it increments every time the subcriber data change.
"acts": [
    {
        "act": "capture",
        "time": 1479384886,
        "total": "100.45 DKK"
    },
    {
        "act": "refund",
        "time": 1479387243,
        "total": "42.78 DKK"
    }
]
A cumulative array of actions made to this charge. There are 2 types of actions:
  • capture: you captured some or all of the authorized funds.
  • refund: you refunded some/all of the captured funds.
"subscriber": {
    "id": 19,
    "ref": "301"
}
...
"totals": {
    "authorized": "111.12 DKK",
    "captured": "99.95 DKK",
    "refunded": "1.00 DKK",
    "left": "11.17 DKK"
}
The relevant values for this transaction.
"time": {
    "created": 1479384800,
    "authorized": 1479384801
}
Unix timestamps.