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 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] | ||||
to | 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.
| ||||
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
.
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.
| ||||||||||||||||||
data.transactionId | String | Unique transaction ID. | ||||||||||||||||||
data.transactionDate | String | Date/time when the transaction was processed. | ||||||||||||||||||
data.transactionType | String | Initial transaction type processed.
| ||||||||||||||||||
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.
| ||||||||||||||||||
data.isEuropeanCard | Nullable Boolean | Confirms whether the card used for the transaction is issued in Europe (including the UK).
| ||||||||||||||||||
data.isCorporateCard | Nullable Boolean | Confirms whether the card used for the transaction is a Corporate 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.
| ||||||||||||||||||
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
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. |