Edit on GitHub

Synchronization

The Synchronization API will keep your system up-to-date. The API is built around a consecutive sequence number called seq, which is a shop-specific counter that increments when you get a new authorization, capture, refund or void. When this happens you will receive a Ping.

Pings

Pings are tiny HTTP requests that you receive both periodically (every 5 minutes) and when your seq changes, e.g. when you receive a new transaction. Pings are HTTP requests that you receive from us on port 80 (HTTP) or 443 (HTTPS). You choose the ping URL in our dashboard. When this happens, we will send you a ping 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. You need to verify this signature, read how.
JSON fieldsDescription
"seq": 389Consecutive sequence number for your shop. This will increment with every new transaction, capture and refund.
"shopid": 129The shopid associated with this ping.

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 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.

The response body is limited to 32 kB.

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.

Footnotes

  • [1] Events that trigger a ping request: authorization, capture and refund.