Settlement Function

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

`GET` Settlements - Request

URL

https://test-api.dnapayments.com/v1/partners/settlements

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 Name	State	Data Type	Description
Content-Type	Mandatory	String	application/json
Authorization	Mandatory	String	Bearer access_token

GET Settlement Request

Field Name

State

Data Type

Description

from

Mandatory

String

Start 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]

Mandatory

String

End 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]

merchantId

Optional

String

Unique 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

page

Optional

String

Page number required.

Default=1

size

Optional

String

Number of records to return.

Default=50, Maximum=5000

searchBy

Optional

String

Confirms which date is being used in the query.

banking-date	Search using the date we start the settlement process.
settlement-date	Search using the date that the partner/merchant receives their funds.

If this is not supplied, then settlement-date is used.

transactionId

Optional

String

Transaction 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

GET https://test-api.dnapayments.com/v1/partners/settlements?from=2022-05-18&to=2022-05-20&merchantId=6a3848c5-1c2c-4903-b621-879db6277402&page=1&size=100&searchBy=banking-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 Settlements Response

Field Name

Data Type

Description

totalCount

Integer

Total 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.bankingDate

String

Date that the settlement process was started.

data.settlementDate

Nullable String

Date that the transaction was settled.

data.merchantName

String

Name of the merchant who has processed the transaction.

data.merchantId

String

Unique ID for the merchant, allocated by DNA Payments.

data.amount

Decimal

Original requested transaction amount.

data.acquirerFee

Decimal

Acquiring fee charged for the processing of the transaction.

data.amountToMerchant

Decimal

Amount settled to the merchant.

data.currency

String

Currency of the transaction e.g. GBP

data.operation

String

Data directly supplied by the acquiring platform. Confirmation of operation performed.

advice	Standard transaction
reversal	Refund/reversal transaction
adjustment	Partial reversal/refund

data.transactionId

String

Unique transaction ID.

data.transactionDate

String

Date/time when the transaction was processed.

data.transactionType

String

Initial transaction type processed.

retail	Sale
credit	Refund/cancellation
unique	Designates transactions completed under specific Merchant Category Code’s that have special processing requirements.

data.merchantReference

String

Unique order number allocated by the merchant.

data.cardScheme

Nullable String

Card scheme used in the transaction.

data.cardType

Nullable String

Confirmation of the card type used in the transaction.

credit	Credit card
debit	Debit card

data.isEuropeanCard

Nullable Boolean

Confirms whether the card used for the transaction is issued in Europe (including the UK).

true	Card used is issued in Europe
false	Card used was not issued in Europe

data.isCorporateCard

Nullable Boolean

Confirms whether the card used for the transaction is a Corporate card.

true	Card used is a corporate card
false	Card used is a personal card

data.cardMask

Nullable String

Masked PAN for the payment card used in the transaction, contains the first six and last four digits.

data.captureMethod

String

Description of the capture method for the transaction.

ecom	eCommerce
ecom-paybybankapp	Pay by Bank App
ecom-openbanking	Open Banking
ecom-klarna	Klarna
moto	Mail Order/Telephone Order (MOTO)
recurring	Recurring
pos	Cardholder Present
pos-contactless	Cardholder Present (Contactless)
stored	Stored Token

data.issuerCountry

Nullable String

Country in which the payment card was issued. If this cannot be determined the field will be null.

Format: ISO 3166-1 alpha-3

data.merchantCustomData

Nullable String

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

transactionType	operation	Description
retail	advice	Standard sale transaction.
retail	reversal	Fully refunded transaction.
retail	adjustment	Partially refunded transaction.
credit	advice	Refund transaction (full or partial).
credit	reversal	Reversal of refund, extremely rare.
credit	adjustment	Partial reversal of refund, extremely rare.
unique	advice	Standard sale transaction.
unique	reversal	Fully refunded transaction.
unique	adjustment	Partially refunded transaction.

GET Settlements - Request#

URL

GET Request Example#

GET Settlements - Response#

Refund Handling

GET Example Response#

transactionType + operation#

`GET` Settlements - Request

`GET` Request Example

`GET` Settlements - Response

`GET` Example Response

`transactionType` + `operation`