There are two requests in our Synchronization API: Ping and Pull. Ping is a request that you receive from us, both periodically and after certain events. Pull 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 headers	Description
`X-Signature: 17FUWCstyodDzsCkG5/gU/2VA2vUEcHfvFxGh8RCElo=`	Base64 encoded HMAC-SHA2-256 signature of the body signed with your API key.

JSON fields	Description
`"seq": 200`	Consecutive sequence number for your shop.
`"shopid": 129`	The 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:

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 fields	Description
`"seq": 164`	The sequence number for the last change in the changes array.
`{% include "code/sync/changes.html" %}`	An array with changes after the requested sequence number in chronological order. There are 3 types of changes: transaction, subscriber and charge.

Transaction

JSON fields	Description
`"type": "transaction"`	The type of the entry.
`"id": 2942`	The transaction ID.
`"orderid": "INV3803"`	The order ID that you assigned to the transaction when you created the payment link.
`"rev": 3`	A revision number. It starts at `1` and it increments every time the transaction data changes.
`{% include "code/sync/transaction-method.json" %}`	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.
`{% include "code/sync/transaction-acts.json" %}`	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).
`{% include "code/sync/transaction-totals.json" %}`	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.
`{% include "code/sync/transaction-time.json" %}`	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 fields	Description
`"type": "subscriber"`	The type of the entry.
`"id": 19`	The subscriber ID.
`"ref": "user301"`	The reference ID that you assigned to the subscriber when you created it (more details).
`"rev": 2`	A revision number. It starts at `1` and it increments every time the subcriber data changes.
`{% include "code/sync/subscriber-method.json" %}`	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.
`{% include "code/sync/subscriber-acts.json" %}`	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.
`{% include "code/sync/subscriber-time.json" %}`	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 fields	Description
`"type": "charge"`	The type of the entry.
`"id": 3180`	The transaction ID.
`{% include "code/sync/charge-subscriber.json" %}`	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": 2`	A revision number. It starts at `1` and it increments every time the transaction data changes.
`{% include "code/sync/transaction-method.json" %}`	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.
`{% include "code/sync/charge-acts.json" %}`	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).
`{% include "code/sync/charge-totals.json" %}`	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.
`{% include "code/sync/charge-time.json" %}`	Unix timestamps denoting when the charge was commenced and when the authorization succeeded.