Settlement Function

The Partners Reporting API allows for the querying of all transactions processed by 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
Content-TypeMandatoryStringapplication/json
Content-TypeMandatoryStringBearer access_token
GET Settlements Request
Field NameStateData TypeDescription
fromMandatoryStringStart date for transactions. Transactions are available for 365 days and a maximum of 30 days can be specified.

ISO 8601 Format [e.g. 2021-01-25T15:29:56Z]
toMandatoryStringEnd date for transactions. Transactions are available for 365 days and a maximum of 30 days can be specified.

ISO 8601 Format [e.g. 2021-01-25T15:29:56Z]
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.

Default=1
sizeOptionalStringNumber of records to return.

Default=50, Maximum=5000
searchByOptionalStringConfirms which date is being used in the query.
banking-dateSearch using the created date field
settlement-dateSearch using the processed date field
If this is not supplied, then settlement-date is used.

GET Request Example

The Request is for all transactions in the specific 24-hour period, for one merchant where the transaction status is “refunded”. The request is also asking for the first page of results comprising of 10 records.

Postman GET request
GET https://test-api.dnapayments.com/v1/partners/transactions?from=2021-01-24T15:29:56Z&to2021-01-25T15:29:56Z&merchantId=2864dd92-343a-4ce7-b1f9-9742e3c7f07d&page=1&size=10&searchBy=settlement-date
HTTP/1.1
Content-Type: application/json
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Host: 192.168.0.75:8080
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 Transactions Response
Field NameData TypeDescription
totalCountIntegerTotal count of records for the requested time period.
data.settlementDateStringDate 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.acquirerFeeNullable DecimalAcquiring fee charged for the processing of the transaction.
data.amountToMerchantNullable DecimalAmount settled to the merchant.
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.
retailSale
creditRefund/cancellation
data.cardSchemeStringCard scheme used in the transaction.
data.cardTypeStringConfirmation of the card type used in the transaction.
creditCredit card
debitDebit card
data.isEuropeanCardBooleanConfirms 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.isCorporateCardBooleanConfirms whether the card used for the transaction is a Corporate card.
trueCard used is a corporate card
falseCard used is a personal card
data.cardMaskStringMasked 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.
ecomeCommerce
motoMail Order/Telephone Order (MOTO)
posCardholder Present
pos-contactlessCardholder Present (Contactless)
data.issuerCountryStringCountry in which the payment card was issued. If this cannot be determined the field will be null.

Format: ISO 3166-1 alpha-3
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": 38,
"data":
[
{
"settlementDate": "2021-04-05",
"merchantId": "a6f6b795-6d0d-472f-a06c-3fdfb857eba2",
"merchantName": "Fulham FC",
"amount": 46.89,
"acquirerFee": -0.18,
"amountToMerchant": 46.71,
"currency": "GBP",
"operation": "advice",
"transactionId": "L0928104QG2C",
"transactionDate": "2021-04-02T22:29:45Z",
"transactionType": "retail",
"cardScheme": "mastercard",
"cardType": "credit",
"isEuropeanCard": true,
"isCorporateCard": false,
"cardMask": "541333...0102",
"captureMethod": "ecom",
"issuerCountry": "GBR"
},
{
"settlementDate": "2021-04-05",
"merchantId": "a6f6b795-6d0d-472f-a06c-3fdfb857eba2",
"merchantName": "Fulham FC",
"amount": -30,
"acquirerFee": 0,
"amountToMerchant": -30,
"currency": "GBP",
"operation": "advice",
"transactionId": "L0928104QG0E",
"transactionDate": "2021-04-02T22:25:36Z",
"transactionType": "credit",
"cardScheme": "mastercard",
"cardType": "credit",
"isEuropeanCard": false,
"isCorporateCard": false,
"cardMask": "522499...9909",
"captureMethod": "moto",
"issuerCountry": "GBR"
},
{
"settlementDate": "2020-07-03",
"merchantId": "a6f6b795-6d0d-472f-a06c-3fdfb857eba2",
"merchantName": "Fulham FC",
"amount": 24,
"acquirerFee": -0.46,
"amountToMerchant": 23.54,
"currency": "GBP",
"operation": "advice",
"transactionId": "0238386e511249a593a70b1dc6d401f7",
"transactionDate": "2021-03-26T16:14:19Z",
"transactionType": "retail",
"cardScheme": "visa",
"cardType": "credit",
"isEuropeanCard": true,
"isCorporateCard": true,
"cardMask": "448407...0000",
"captureMethod": "pos",
"issuerCountry": "BRA"
}
]
}

transactionType + operation

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

transactionTypeoperationDescription
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.