Settlement Function

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

`GET` Settlements - Request

URL

https://test-api.dnapayments.com/v3/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. 2024-06-14]

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. 2024-06-14]

page

Optional

String

Page number required.

Default=1

size

Optional

String

Number of records to return.

Default=50, Maximum=1000

searchBy

Optional

String

Confirms which date is being used in the query.

processed-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 processed-date is used.

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

transactionId

Optional

String

Transaction ID.

`GET` Request Example

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

Postman GET request
GET https://test-api.dnapayments.com/v3/partners/settlements?from=2024-06-18&to=2024-06-19&merchantId=6a3848c5-1c2c-4903-b621-879db6277402&page=1&size=100&searchBy=processed-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.processedDate

String

Date that the settlement process was started.

data.settlementDate

Nullable String

Date that the transaction was settled.

data.merchantId

String

Unique ID for the merchant, allocated by DNA Payments.

data.merchantName

String

Name of the merchant who has processed the transaction.

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

Confirmation of operation performed.

See operation for all operations.

data.transactionId

Nullable String

Unique transaction ID. Null for non-transactional fees.

data.transactionDate

String

Date/time when the transaction was processed.

data.transactionType

String

Initial transaction type processed.

See transactionType for all transaction types.

data.merchantReference

Nullable 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

Nullable String

Capture method for the transaction.

See captureMethod for all capture methods.

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": [
      {
         "processedDate": "2024-06-19",
         "settlementDate": "2024-06-20",
         "merchantId": "6a3848c5-1c2c-4903-b621-879db6277402",
         "merchantName": "Test Merchant",
         "amount": 0,
         "acquirerFee": -0.03,
         "amountToMerchant": -0.03,
         "currency": "GBP",
         "operation": "advice",
         "transactionId": null,
         "transactionDate": "2024-06-19T00:00:00Z",
         "transactionType": "declined-txn",
         "merchantReference": null,
         "cardScheme": "visa",
         "cardType": "debit",
         "isEuropeanCard": null,
         "isCorporateCard": false,
         "cardMask": null,
         "captureMethod": null,
         "issuerCountry": null,
         "merchantCustomData": null
      },
      {
         "processedDate": "2024-06-19",
         "settlementDate": "2024-06-20",
         "merchantId": "6a3848c5-1c2c-4903-b621-879db6277402",
         "merchantName": "Test Merchant",
         "amount": 3.6,
         "acquirerFee": -0.03972,
         "amountToMerchant": 3.56028,
         "currency": "GBP",
         "operation": "advice",
         "transactionId": "M138811RC46A",
         "transactionDate": "2024-06-19T21:59:55Z",
         "transactionType": "retail",
         "merchantReference": "M138811RC46A",
         "cardScheme": "visa",
         "cardType": "debit",
         "isEuropeanCard": true,
         "isCorporateCard": false,
         "cardMask": "475130...4321",
         "captureMethod": "pos-contactless",
         "issuerCountry": "GBR",
         "merchantCustomData": null
      },
      {
         "processedDate": "2024-06-18",
         "settlementDate": "2024-06-21",
         "merchantId": "6a3848c5-1c2c-4903-b621-879db6277402",
         "merchantName": "Test Merchant",
         "amount": 72.99,
         "acquirerFee": -2.263431,
         "amountToMerchant": 70.726569,
         "currency": "GBP",
         "operation": "advice",
         "transactionId": "3bc9ae58-9528-24a1-9336-c5cc5cf8d1c2",
         "transactionDate": "2024-06-18T17:48:54Z",
         "transactionType": "retail",
         "merchantReference": "114422",
         "cardScheme": null,
         "cardType": null,
         "isEuropeanCard": null,
         "isCorporateCard": null,
         "cardMask": null,
         "captureMethod": "ecom-klarna",
         "issuerCountry": null,
         "merchantCustomData": null
      }
   ]
}

`operation`

The below table provides a list of operations along with their descriptions.

operation	Description
advice	This operation type notifies that a specific transaction type has completed. See transactionType table for details.
reversal	This operation type notifies that a reversal of the specific transaction type has occurred. See transactionType table for details.
adjustment	This operation type notifies that a specific transaction type was adjusted, e.g., its amount was amended. See transactionType table for details.
request	This operation type notifies that a request for a specific transaction type has occurred. See transactionType table for details.
part-advice	This operation type notifies that a specific transaction type was partially completed. See transactionType table for details.

`transactionType`

The below table provides a list of transaction types along with their descriptions.

transactionType	Description
retail	Standard sale transaction
credit	Full of partial refund of a standard sale transaction
retail-apm	Standard sale transaction via Alternative Payment Method, ie Open Banking, Klarna, AliPay+ etc
credit-apm	Full or partial Refund of a standard sale transaction made via Alternative Payment Method, ie Open Banking, Klarna, AliPay+ etc
unique	Standard sale transaction (Casinos only)
declined-txn	Declined Transaction. Authorisation Fee, Gateway Fee can incur according to the merchant's contract
minimum-monthly-service-charge	Minimum Monthly Service Fee charged on a monthly basis according the merchant's contract
pci-fee	PCI fee charged according to the merchant's contract
merchant-monthly-fee	Recurring fee charged on a monthly basis according the merchant's contract
moto-fee	Fee associated with MOTO (Mail Order, Telephone Order) transaction according to the merchant's contract
zash-app-fee	Zash EPOS fee charged on a monthly basis according the merchant's contract
airtime-service-fee	Airtime service fee charged on a monthly basis according the merchant's contract
settlement-fee	Settlement fee charged per settlement occurance
settlement-fee-trans	Settlement fee charged per settlement occurance
one-off-terminal-cost	One-off terminal purchase fee
one-off-terminal-setup-fee	One-off terminal installation fee
monthly-rent-fee	POS terminal rental fee charged on a monthly basis according the merchant's contract
faster-funding-monthly-fee	Next Day Settlement fee charged on a monthly basis according the merchant's contract
monthly-gateway-fee	Gateway Fee charged on a monthly basis according the merchant's contract
axept-services-subscription-fees	axept Subscription fee charged on a monthly basis according the merchant's contract
one-off-charge	One Off Charge
one-off-charge-w-vat	One Off Charge, inc VAT
retail-cbk	Chargeback withheld
credit-cbk	Chargeback withheld previously returned
retail-2prs	Chargeback is defended, funds sent back to the merchant
unique-2prs	Chargeback is defended, funds sent back to the merchant (Casinos only)
unique-cbk	Chargeback received and charged from the merchant. (Casinos only)
retail-collaboration/rdr	The final chargeback process stage
adjustment-due-to-manual-payment	One-off adjustment following internal procedures and protocols
account-replenishment	Funds received from the merchant
negative-balance-to-dd-invoice	Funds to be charged via Direct Debit
credit-notif	Funds credited to the merchant
fee-collection-out	One-off fees adjustments with payment schemes and issuing banks
fee-collection-inc	One-off fees adjustments with payment schemes and issuing banks
fee-collection-cbk-out	One-off fees adjustments with payment schemes and issuing banks
funds-disb-out	One-off adjustments with payment schemes and issuing banks
funds-disb-inc	One-off adjustments with payment schemes and issuing banks
debit-account	One-off debit adjustment
credit-account	One-off credit adjustment
fees-adjustment	Refund of the fees charged
hold-settlement	Settlement withheld due to internal procedures and protocols
release-funds	Funds withheld released
transfer-to-security-deposit	Funds transferred to the Security Deposit

`captureMethod`

The below table provides a list of capture methods along with their descriptions.

captureMethod	Description
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
pos-openbanking	Open Banking (POS)
pos-alipay	Alipay (POS)

GET Settlements - Request​

GET Request Example​

GET Settlements - Response​

GET Example Response​

operation​

transactionType​

captureMethod​

`GET` Settlements - Request

`GET` Request Example

`GET` Settlements - Response

`GET` Example Response

`operation`

`transactionType`

`captureMethod`