Edit

Synchronization

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

Ping request

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 an 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 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 changes.
"method": {
    "type": "card",
    "id": "BPb9x2aAXzx6KDB5ZnSKIFJVPD8jS…",
    "card": {
        "brand": "dankort",
        "last4": 4279
    }
}
  • type: The method type can be either "card", "mobilepay" or "applepay"
  • id: A per-shop opaque hash of the payment device.
  • card: A subobject, named for the internal method used to process the payment, contains identifiable information about the payment method to help with customer identification. Currently only "card" is supported. No subobject is guaranteed to be there and more will be added in the future as they become necessary.
    • brand: "amex", "dankort", "diners", "discover", "jcb", "maestro", "mastercard", "unionpay", "visa"
    • last4: the last 4 digits of the card number.
"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 sum totals of all actions performed on this transaction.
  • authorized: how much was originally authorized. This can differ from how much you attempted to authorize.
  • captured: how much has been captured so far.
  • refunded: how much has been refunded so far.
  • left: how much is still left to capture.
"time": {
    "created": 1479384780,
    "authorized": 1479384799
}
Unix timestamps denoting when the payment link was created and when the authorization succeeded.

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": 19The 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 changes.
"method": {
    "type": "card",
    "id": "BPb/9x2aAXzx6KDB5ZnSKIFJVPD8jS…",
    "card": {
        "brand": "visadankort",
        "last4": 1234,
        "exp": 1719784799
    }
}
A human-interpretable breakdown of the payment method where type represents the method used:
  • card: a credit card transaction.
  • mobilepay: a Mobilepay transaction.
and id is a per-shop opaque ID assigned to the payment device (eg. credit card number). A subobject, named for the internal method used to process the payment, contains identifiable information about the payment method to help with customer identification. Currently only "card" is supported. No subobject is guaranteed to be there and more will be added in the future as they become necessary. The card brand can be one of the following:
  • amex: American Express.
  • dankort: a pure Dankort.
  • diners: Diners Club card.
  • discover: Discover Network card.
  • forbrugsforening: Forbrugsforeningen's Dankort.
  • jcb: JCB card.
  • maestro: Maestro card.
  • mastercard: Mastercard.
  • paypal: a PayPal branded Discover Network credit card.
  • unionpay: China UnionPay card.
  • visa: Visa.
  • visadankort: a Visa/Dankort cobranded card.
last4 is the last 4 digits of the card number. exp is a UNIX timestamp of the card's latest possible expiration time.
"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. Charges are fundamentally the same as transactions with some extra information about the subcriber.

JSON fieldsDescription
"type": "charge"The type of the entry.
"id": 3180The transaction ID.
"subscriber": {
    "id": 19,
    "ref": "user301"
}
Identifiers for the subscriber that this charge pertains to. This is the same subscriber ID and reference as you received in the subscriber entry.
"orderid": "DEC2019-1274"The order ID that you assigned to the transaction when you charged the subscriber.
"rev": 2A revision number. It starts at 1 and it increments every time the transaction data changes.
"method": {
    "type": "card",
    "id": "BPb9x2aAXzx6KDB5ZnSKIFJVPD8jS…",
    "card": {
        "brand": "dankort",
        "last4": 4279
    }
}
A human-interpretable breakdown of the payment method where type represents the method used:
  • card: a credit card transaction.
  • mobilepay: a Mobilepay transaction.
and id is a per-shop opaque ID assigned to the payment device (eg. credit card number). A subobject, named for the internal method used to process the payment, contains identifiable information about the payment method to help with customer identification. Currently only "card" is supported. No subobject is guaranteed to be there and more will be added in the future as they become necessary. The card brand can be one of the following:
  • amex: American Express.
  • dankort: a pure Dankort.
  • diners: Diners Club card.
  • discover: Discover Network card.
  • forbrugsforening: Forbrugsforeningen's Dankort.
  • jcb: JCB card.
  • maestro: Maestro card.
  • mastercard: Mastercard.
  • paypal: a PayPal branded Discover Network credit card.
  • unionpay: China UnionPay card.
  • visa: Visa.
  • visadankort: a Visa/Dankort cobranded card.
last4 is the last 4 digits of the card number.
"acts": [
    {
        "act": "capture",
        "time": 1479384803,
        "total": "99.95 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": "111.12 DKK",
    "captured": "99.95 DKK",
    "refunded": "0 DKK",
    "left": "11.17 DKK"
}
The sum totals of all actions performed on this transaction.
  • authorized: how much was originally authorized. This can differ from how much you attempted to authorize.
  • captured: how much has been captured so far.
  • refunded: how much has been refunded so far.
  • left: how much is still left to capture.
"time": {
    "created": 1479384800,
    "authorized": 1479384801
}
Unix timestamps denoting when the charge was commenced and when the authorization succeeded.