Skip to main content

Settlement Function

The Partners Settlement API allows to query settlements of your merchants.

GET Settlements - Request

The Settlement request is completed via a GET request to the test URL shown above, and should contain the below header data. The access_token will be the one received in the Authentication Response. The URL contains several filters which can be applied to narrow the results returned.

HTTP Header
Field NameStateData TypeDescription
AuthorizationMandatoryStringBearer access_token
GET Settlement Request
Field NameStateData TypeDescription
fromMandatoryStringStart date for transactions. Transactions are available for 365 days and a maximum of 30 days can be specified.

Format: YYYY-MM-DD [e.g. 2022-04-20]
toMandatoryStringEnd date for transactions. Transactions are available for 365 days and a maximum of 30 days can be specified.

Format: YYYY-MM-DD [e.g. 2022-04-20]
merchantIdOptionalStringUnique id for the merchant, allocated by DNA Payments and returned in GET Merchants within the Reporting API.

This field allows for a maximum of 10 ids to be submitted, each separated by a comma.

Specifying the id will only return transactions for this merchant
pageOptionalStringPage number required.

sizeOptionalStringNumber of records to return.

Default=50, Maximum=5000
searchByOptionalStringConfirms which date is being used in the query.
banking-dateSearch using the date we start the settlement process.
settlement-dateSearch using the date that the partner/merchant receives their funds.
If this is not supplied, then settlement-date is used.
transactionIdOptionalStringTransaction ID.

GET Request Example

This example request is for all settlements between 18.05.22 and 20.05.22, for one merchant. The request is asking for the first page of results comprising of 100 records, and is searching by the banking-date.

Postman GET request

Content-Type: application/json
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

GET Settlements - Response

If the request is successful, the method will return a 200 response code, and the body will contain the following fields:

GET Settlements Response
Field NameData TypeDescription
totalCountIntegerTotal count of records for the requested time period.
The remainder of the fields in the response are an Array of data Objects. The number of Objects will be either the totalCount, or the limits imposed by the page and size fields in the Request Parameters.
data.bankingDateStringDate that the settlement process was started.
data.settlementDateNullable StringDate that the transaction was settled.
data.merchantNameStringName of the merchant who has processed the transaction.
data.merchantIdStringUnique ID for the merchant, allocated by DNA Payments.
data.amountDecimalOriginal requested transaction amount.
data.acquirerFeeDecimalAcquiring fee charged for the processing of the transaction.
data.amountToMerchantDecimalAmount settled to the merchant.
data.currencyStringCurrency of the transaction e.g. GBP
data.operationStringData directly supplied by the acquiring platform. Confirmation of operation performed.
adviceStandard transaction
reversalRefund/reversal transaction
adjustmentPartial reversal/refund
data.transactionIdStringUnique transaction ID.
data.transactionDateStringDate/time when the transaction was processed.
data.transactionTypeStringInitial transaction type processed.
uniqueDesignates transactions completed under specific Merchant Category Code’s that have special processing requirements.
data.merchantReferenceStringUnique order number allocated by the merchant.
data.cardSchemeNullable StringCard scheme used in the transaction.
data.cardTypeNullable StringConfirmation of the card type used in the transaction.
creditCredit card
debitDebit card
data.isEuropeanCardNullable BooleanConfirms whether the card used for the transaction is issued in Europe (including the UK).
trueCard used is issued in Europe
falseCard used was not issued in Europe
data.isCorporateCardNullable BooleanConfirms whether the card used for the transaction is a Corporate card.
trueCard used is a corporate card
falseCard used is a personal card
data.cardMaskNullable StringMasked PAN for the payment card used in the transaction, contains the first six and last four digits.
data.captureMethodStringDescription of the capture method for the transaction.
ecom-paybybankappPay by Bank App
ecom-openbankingOpen Banking
motoMail Order/Telephone Order (MOTO)
posCardholder Present
pos-contactlessCardholder Present (Contactless)
storedStored Token
data.issuerCountryNullable StringCountry in which the payment card was issued. If this cannot be determined the field will be null.

Format: ISO 3166-1 alpha-3
data.merchantCustomDataNullable StringCustom data provided by the integrated solution for the transaction.
Refund Handling

When a Sale transaction has been fully or partially refunded the transactionType will remain as retail, but the operation field will be updated to be either reversal or adjustment depending on whether a full or partial refund was performed.

A separate entry, for the full/partial refund transaction, will also be present in the Settlement API

GET Example Response

"totalCount": 3,
"data": [
"bankingDate": "2022-05-20",
"settlementDate": "2022-05-23",
"merchantId": "6a3848c5-1c2c-4903-b621-879db6277402",
"merchantName": "Test Merchant",
"amount": 10,
"acquirerFee": -0.0485,
"amountToMerchant": 9.9515,
"currency": "GBP",
"operation": "advice",
"transactionId": "49da58b0-cc2c-4270-b924-2f821da4313e",
"transactionDate": "2022-05-22T23:50:31Z",
"transactionType": "retail",
"merchantReference": "6a526607-52aa-47a3-80d3-3db5098544a3",
"cardScheme": "visa",
"cardType": "debit",
"isEuropeanCard": true,
"isCorporateCard": false,
"cardMask": "492181...7421",
"captureMethod": "ecom",
"issuerCountry": "GBR",
"merchantCustomData": "2230|111|10.00|"
"bankingDate": "2022-05-18",
"settlementDate": "2022-05-23",
"merchantId": "6a3848c5-1c2c-4903-b621-879db6277402",
"merchantName": "Test Merchant",
"amount": 0.01,
"acquirerFee": -0.0001,
"amountToMerchant": 0.0099,
"currency": "GBP",
"operation": "advice",
"transactionId": "M138811RC46A",
"transactionDate": "2022-05-18T14:56:18Z",
"transactionType": "retail",
"merchantReference": "M138811RC46A",
"cardScheme": "visa",
"cardType": "debit",
"isEuropeanCard": true,
"isCorporateCard": false,
"cardMask": "475130...4321",
"captureMethod": "pos-contactless",
"issuerCountry": "GBR",
"merchantCustomData": null
"bankingDate": "2022-05-20",
"settlementDate": null,
"merchantId": "6a3848c5-1c2c-4903-b621-879db6277402",
"merchantName": "Test Merchant",
"amount": 150,
"acquirerFee": -4.34,
"amountToMerchant": 145.66,
"currency": "GBP",
"operation": "advice",
"transactionId": "3bc9ae58-9528-24a1-9336-c5cc5cf8d1c2",
"transactionDate": "2022-05-22T22:16:00Z",
"transactionType": "retail",
"merchantReference": "691251_220522_231504",
"cardScheme": null,
"cardType": null,
"isEuropeanCard": null,
"isCorporateCard": null,
"cardMask": null,
"captureMethod": "ecom-klarna",
"issuerCountry": null,
"merchantCustomData": null

transactionType + operation

The combination of transactionType and operation are used to determine the transaction processed. The below table provides details around the various combinations.

retailadviceStandard sale transaction.
retailreversalFully refunded transaction.
retailadjustmentPartially refunded transaction.
creditadviceRefund transaction (full or partial).
creditreversalReversal of refund, extremely rare.
creditadjustmentPartial reversal of refund, extremely rare.
uniqueadviceStandard sale transaction.
uniquereversalFully refunded transaction.
uniqueadjustmentPartially refunded transaction.