Guides
  1. BackOffice API

Reconciliation Module

The Reconciliation Module can be used to retrieve a details list of all transactions, funds and fees of a settlement.
During each "Payout Run" (aka "Run") all transactions that are eligible for payout are gathered and the documents mentioned below are generated.
Each document will have an internal document-id consisting of <prefix>YYM.<merchant-id>.<payout-run-id>.

To retrieve reconciliation details you can provide the document-id in the API URL, or add payout_run_id=<payout-run-id> in the GET/POST request URL or body.

  • Statement all consumer payments, refunds and chargebacks (ID: SYYM.123456.123456789)
  • Invoice all fees and costs (ID: CYYM.123456.123456789)
  • Settlement Balance of Statement total minus Invoice total to be paid to or by the merchant (ID: RYYM123456.123456789)
📘

Note

  • By default there will be a payout run each Monday, and optionally an additional run on Thursday if the balance is >= € 2.500,00. Other intervals are possible on request.
  • Reconciliation details can be included in an e-mail when a run is completed; this can be configured under Settings in the Merchant Back-Office.

Retrieve

Entry point: /rest/v1/reconciliation[/](<document-id> | <date-expression>)[/raw]

REST request elements

Field nameType LengthDescription
[request]containerGeneral container for this resource. (XML only)

Optional request URL fields

Field nameType LengthDescription
document-idstring 10+Document id of a statement, invoice or settlement to retrieve the reconciliation details for.
date-expressionstringDate specification (YYYY-MM-DD) or English date expression supported by PHP's strtotime.

📘 You can specify last to retrieve the last available settlement data.

Body request fields

Field nameType LengthDescription
payout_run_idnumericPayout run-id to retrieve the reconciliation details for.
formatstringmt940 or csv to specify the output format (default csv)
rawbooleanadd /raw to the API URL, or supply a non empty value (raw=1) in GET/POST to retrieve raw results for the given format. This will produce a JSON array containing all values.

REST response elements (raw=0)

List of reconciliation details when raw=0.

Field nameType LengthDescription
[reconciliation]containerGeneral container for this resource.
idstring 10+reconciliation document ID (will always be the RYYM123456.123456789 version).
merchant_idnumericmerchant ID.
bank_accountnumericbank account used for the settlement (usually 0).
visiblenumeric1 when settlement is visible in the merchant backoffice (after approval).
nn_idstring 10+reconciliation document ID (same as id).
datedatedocument creation date.
currency_idstring 3settlement document currency.
amountnumeric 10,2settlement amount in cents.
payout_datedatescheduled settlement payout date.
payment_datedatesettlement payment date (after bank confirmation). null when unpaid.
batch_idnumericinternal payout batch ID.
payout_run_idnumericinternal payout run ID.
namestringname of the included CSV file.
datatextReconciliation data in format as given in the API request.

📘 MT940/CSV will follow the format and options as given in the Merchant Back-Office settings.

REST response elements (raw=1 & format=csv)

List of reconciliation details when raw=1&format=csv.

Field nameType LengthDescription
[reconciliation]containerGeneral container for this resource.
[transactions]arrayArray with CSV lines formatted according to Settings in the Back-Office. The first entry will always contain the list of fields.
See examples for each format below.
totalnumerictotal number of transactions in the CSV.

REST response elements (raw=1 & format=mt940)

List of reconciliation details when raw=1&format=mt940.

Field nameType LengthDescription
[reconciliation]containerGeneral container for this resource.
[transactions]arrayJSON array with MT940 details (key => value) according to Settings in the Back-Office.

📘 The result will be a multi-dimensional array where the 1st key will be the settlement currency.

See examples for each format below.
totalsarrayArray with totals for each settlement currency.
totalnumerictotal number of transactions in transactions.

CSV Export Formats

The Reconciliation Module can produce several different CSV formats depending on the required information. Default settings can be modified using the Settings option of the Merchant Back-Office.

You can also provide the format=FORMAT to the API call (in capitals).

format=DEFAULT | DEFAULT-V2

📘

Note

  • Due to legacy these formats are exactly the same.
  • There is also DEFAULT-V3 which will use the description specified for custom payouts as type_description when available.
  • Additional fields country and account_country will be added depending on account settings.

Example 10 lines in Response['data']['transactions']:

transaction_id,transaction_time,sitename,type_id,type_description,name,payout_amount,firstname,lastname,account_name,account_number,account_code,merchant_ref,description,invoice_date,invoice_number,statement_date,statement_number,settlement_date,settlement_number
T23ADXS80418,2023-10-10 07:25:08,Generic Test Site,1,Processed payments,Creditcard,4027.00,John,Doe,,,,80418,bobtest12148,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80418,2023-10-10 07:25:08,Generic Test Site,2,Transaction costs,Creditcard,-29.00,John,Doe,,,,80418,bobtest12148,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80418,2023-10-10 07:25:08,Generic Test Site,2,Transaction costs,Creditcard,-117.00,John,Doe,,,,80418,bobtest12148,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80484,2023-10-10 12:42:07,Generic Test Site,1,Processed payments,Creditcard,3465.00,Jane,Doe,,,,80484,demo21160,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80484,2023-10-10 12:42:07,Generic Test Site,2,Transaction costs,Creditcard,-100.00,Jane,Doe,,,,80484,demo21160,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039

format=LINQ5

Example 10 lines in Response['data']['transactions']:

transaction_id,transaction_time,sitename,name,currency,payout_amount,transaction_costs_currency,transaction_costs,reserve,distributing_amount,distributing_costs,firstname,lastname,account_name,account_number,account_code,merchant_ref,description,invoice_date,invoice_number,statement_date,statement_number,settlement_date,settlement_number
T23ADXS80418,2023-10-10 07:25:08,Generic Test Site,Creditcard,EUR,4027.00,EUR,-142,,0,0,John,Doe,,,,80418,bobtest12148,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80484,2023-10-10 12:42:07,Generic Test Site,Creditcard,EUR,3465.00,EUR,-121,,0,0,Jane,Doe,,,,80484,demo21160,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80518,2023-10-10 15:54:07,Generic Test Site,Creditcard,EUR,125.00,EUR,-5,,0,0,P.,de Clown,,,,80518,Test Prestashop15217,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80590,2023-10-10 19:46:08,Generic Test Site,Creditcard,EUR,2040.00,EUR,-71,,0,0,C.,Hanky,,,,80590,Smart buying18366,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80624,2023-10-10 21:32:08,Generic Test Site,Creditcard,EUR,646.00,EUR,-35,,0,0,R.E.,Dundant,,,,80624,Test26064,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039

format=MULTI-CURRENCY

Example 10 lines in Response['data']['transactions']:

transaction_id,transaction_time,sitename,type_id,type_description,name,currency,payout_amount,reserve,firstname,lastname,account_name,account_number,account_code,merchant_ref,description,invoice_date,invoice_number,statement_date,statement_number,settlement_date,settlement_number
T23ADXS80418,2023-10-10 07:25:08,Generic Test Site,1,Processed payments,Creditcard,EUR,4027.00,,John,Doe,,,,80418,bobtest12148,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80418,2023-10-10 07:25:08,Generic Test Site,2,Transaction costs,Creditcard,EUR,-29.00,,John,Doe,,,,80418,bobtest12148,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80418,2023-10-10 07:25:08,Generic Test Site,2,Transaction costs,Creditcard,EUR,-117.00,,John,Doe,,,,80418,bobtest12148,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80484,2023-10-10 12:42:07,Generic Test Site,1,Processed payments,Creditcard,EUR,3465.00,,Jane,Doe,,,,80484,demo21160,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039
T23ADXS80484,2023-10-10 12:42:07,Generic Test Site,2,Transaction costs,Creditcard,EUR,-29.00,,Jane,Doe,,,,80484,demo21160,2023-10-18,C23A.1001.3039,2023-10-18,S23A.1001.3039,2023-10-18,R23A.1001.3039

MT940 Export Format

You can also provide the format=mt940 to receive an MT940 export.

format=mt940

{
    "success": true,
    "data": {
        "id": "R23A.1001.3039",
        "merchant_id": "1001",
        "bank_account": "0",
        "nn_id": "R23A.1001.3039",
        "date": "2023-10-18",
        "currency_id": "EUR",
        "amount": "18345.00",
        "payout_date": "2023-10-20 05:00:00",
        "payment_date": null,
        "batch_id": null,
        "payout_run_id": "3039",
        "name": "Settlement R23A.1001.3039.txt",
        "type": "txt",
        "data": "(MT940 text data; see below)"
    }
}

Example snippet of Response['data']:

0000 01CURONL2AXXXX00001
0000 01CURONL2AXXXX00001
940 00
:20:CURO
:25:NL44RABO0123456789EUR
:28C:00001
:60F:C231101EUR0,00
:61:231010C40,27N001NONREF
:86:Processed payments Creditcard
:86:80418
:86:T23ADXS80418 2023-10-10 07:25:08 Generic Test Site
:86:Joe H. Doe//
:61:231010D1,17N002NONREF
:86:Transaction costs Creditcard
:86:80418
:86:T23ADXS80418 2023-10-10 07:25:08 Generic Test Site
:86:Joe H. Doe//
:61:231010D0,29N002NONREF
:86:Transaction costs Creditcard
:86:80418
:86:T23ADXS80418 2023-10-10 07:25:08 Generic Test Site
:86:Joe H. Doe//
:61:231010C34,65N001NONREF
:86:Processed payments Creditcard
:86:80484
:86:T23ADXS80484 2023-10-10 12:42:07 Generic Test Site
:86:J. Doe//
:61:231010D1,00N002NONREF
:86:Transaction costs Creditcard
:86:80484
:86:T23ADXS80484 2023-10-10 12:42:07 Generic Test Site
:86:J. Doe//
:61:231010D0,29N002NONREF
:86:Transaction costs Creditcard
:86:80484
:86:T23ADXS80484 2023-10-10 12:42:07 Generic Test Site
:86:J. Doe//
:61:231010C1,25N001NONREF
:86:Processed payments Creditcard
:86:80518
:86:T23ADXS80518 2023-10-10 15:54:07 Generic Test Site
:86:P. de Clown//
:61:231010D0,04N002NONREF
:86:Transaction costs Creditcard
:86:80518
:86:T23ADXS80518 2023-10-10 15:54:07 Generic Test Site
:86:P. de Clown//
:61:231010D0,29N002NONREF
:86:Transaction costs Creditcard
:86:80518
:86:T23ADXS80518 2023-10-10 15:54:07 Generic Test Site
:86:P. de Clown//
...(truncated)...
:62F:C231018EUR206,74
-XXX

format=mt940&raw=1

{
"success": true,
"data": {
"transactions": {
    "EUR": [
        {
            "transaction_id": "T23ADXS80418",
            "transaction_time": "2023-10-10 07:25:08",
            "description": "bobtest12148",
            "info": "ppmdemo 14003",
            "sitename": "Generic Test Site",
            "type_id": "1",
            "type_description": "Processed payments",
            "name": "Creditcard",
            "payout_amount": "4027.00",
            "currency_id": "EUR",
            "invoice_date": "2023-10-17",
            "firstname": "John",
            "lastname": "Doe",
            "merchant_ref": "80418",
            "consumer_name": "Joe H. Doe",
            "consumer_iban": "",
            "consumer_bic": null
        },
        {
            "transaction_id": "T23ADXS80418",
            "transaction_time": "2023-10-10 07:25:08",
            "description": "bobtest12148",
            "info": "ppmdemo 14003",
            "sitename": "Generic Test Site",
            "type_id": "2",
            "type_description": "Transaction costs",
            "name": "Creditcard",
            "payout_amount": "-29.00",
            "currency_id": "EUR",
            "invoice_date": "2023-10-17",
            "firstname": "John",
            "lastname": "Doe",
            "merchant_ref": "80418",
            "consumer_name": "Joe H. Doe",
            "consumer_iban": "",
            "consumer_bic": null
        },
        {
            "transaction_id": "T23ADXS80418",
            "transaction_time": "2023-10-10 07:25:08",
            "description": "bobtest12148",
            "info": "ppmdemo 14003",
            "sitename": "Generic Test Site",
            "type_id": "2",
            "type_description": "Transaction costs",
            "name": "Creditcard",
            "payout_amount": "-117.00",
            "currency_id": "EUR",
            "invoice_date": "2023-10-17",
            "firstname": "John",
            "lastname": "Doe",
            "merchant_ref": "80418",
            "consumer_name": "Joe H. Doe",
            "consumer_iban": "",
            "consumer_bic": null
        },
        {
            "transaction_id": "T23ADXS80484",
            "transaction_time": "2023-10-10 12:42:07",
            "description": "demo21160",
            "info": "ppmdemo 6754",
            "sitename": "Generic Test Site",
            "type_id": "1",
            "type_description": "Processed payments",
            "name": "Creditcard",
            "payout_amount": "3465.00",
            "currency_id": "EUR",
            "invoice_date": "2023-10-17",
            "firstname": "Jane",
            "lastname": "Doe",
            "merchant_ref": "80484",
            "consumer_name": "J. Doe",
            "consumer_iban": "",
            "consumer_bic": null
        },
        {
            "transaction_id": "T23ADXS80484",
            "transaction_time": "2023-10-10 12:42:07",
            "description": "demo21160",
            "info": "ppmdemo 6754",
            "sitename": "Generic Test Site",
            "type_id": "2",
            "type_description": "Transaction costs",
            "name": "Creditcard",
            "payout_amount": "-100.00",
            "currency_id": "EUR",
            "invoice_date": "2023-10-17",
            "firstname": "Jane",
            "lastname": "Doe",
            "merchant_ref": "80484",
            "consumer_name": "J. Doe",
            "consumer_iban": "",
            "consumer_bic": null
        },
        ...(truncated)...
    ]
}
}

Updated 2 months ago

Did this page help you?