SEQR Invoice Service API
At this point our SEQR Invoice Service API is based on one REST method - which is required to be exposed by invoice issuer.
Issuer is expected to expose a URL which will be called by SEQR Invoice service using HTTP POST with JSON payload about an invoice which has just been paid. The description of JSON request payload is presented in a table below:
|invoiceId||Unique identifier of an invoice in SEQR Invoice service.|
Notification request example:
That invoiceId can be used then to fetch invoice details from SEQR system. It may be fetched from following invoice details URL:
The request should also contain following headers:
|X-Auth-Token||sha256 sum of issuer name concatenated with issuer secret.|
Query param issuer and X-Auth-Token are required for authentication. It is impossible to fetch an invoice from another issuer.
Payload of the response details below. Please notice that the same information is available in a report which can be fetched by an issuer on demand.
Invoice details response example:
|id||unique identifier of an invoice in SEQR Invoice service|
|description||description of an invoice provided by an issuer|
|amount||amount paid, format 123.45 (‘.’ as a decimal separator)|
|currency||3-characters logs currency of an amount, eg. EUR|
|status||status of invoice, at the moment the only possible value is PAID|
|reference||identifier of an invoice provided by an issuer|
|ersReference||identifier of a transaction in SEQR which paid the invoice|
|purchaseTime||datetime when invoice was paid, format: dd.MM.yyyy HH24:MI:ss, eg. 24.06.2015 14:45:57|
|payerMsisdn||MSISDN of payer if issuer requested it|
|payerFirstName||first name of payer if issuer requested delivery address of payer|
|payerLastName||last name of payer if issuer requested delivery address of payer|
|payerStreet||street of payer if issuer requested delivery address of payer|
|payerCity||city of payer if issuer requested delivery address of payer|
|payerZip||ZIP code of payer if issuer requested delivery address of payer|
|payerCountry||country code of payer if issuer requested delivery address of payer|
When notifying issuer about new invoice SEQR Invoice Service requires HTTP 200 response.
In case of problems with connection or issuer’s system malfunction and response other than 200 it will retry several times. First 3 attempts are made right after invoice is paid with about 10 seconds delays. Than retries are scheduled with growing delay length starting from 1 minute, then 3:45, 7:30, 15, 30 minutes and so on (length is two times longer than in previous attempt). It schedules notification 10 times rising delay to 16h in last attempt. This gives around 32h total to deal with any problem regarding notification receiving on issuer’s side.