Incremental Authorisations
Incremental Authorisations
This document outlines the integration process for supporting incremental authorisation flows in merchant-initiated transactions (MIT). It is intended for developers and integrators using the DNA Payments API.
Overview
Incremental authorisations allow additional funds to be authorised and later settled through a settlement (charge) request. This is particularly useful for scenarios like EV charging, fuel stations, hotels, or services billed by usage. The process involves:
Initial pre-authorisation using a MIT (Merchant Initiated Transaction).
One or more incremental authorisations to add funds.
A capture/settlement request to finalise and capture the amount, or a cancel/reversal to release funds back to the customer.
Recurring MIT - Initial Pre-Authorisation
Following the initial customer card registration and marking that transaction as the initial recurring authorisation, all subsequent transactions are typically processed as Merchant Initiated Transactions (MITs). This flow is commonly used for incremental authorisations when the final transaction amount is unknown at the time of the initial authorisation.
In accordance with Visa and Mastercard best practices, the initial customer card registration should not be processed as a pre-authorisation.
It is recommended to perform Account Verification (zero-amount card verification) for this step to avoid potential issuer misinterpretation or incorrect linking of transaction chains.
To be eligible for follow-up incremental authorisations, the MIT must be processed as a pre-authorisation.
For more details on MIT, please refer to the following link:
Example: Initial MIT Pre-AuthorisationPOST https://test-api.dnapayments.com/transaction/operation/recurring
Headers:
Authorisation: Bearer authentication token with 'webapi' scopeRequest Body:
{
"amount": "25",
"transactionType": "PRE-AUTH",
"invoiceId": "MIT-17384893790",
"sequenceType": "recurring",
"periodicType": "ucof",
"parentTransactionId": "11a4da77-4486-1291-9bf3-379702f5405d"
};
| Field Descriptions - MIT Pre-Authorisation Request | |||
|---|---|---|---|
| Field | Status | Type | Description |
| amount | Mandatory | decimal | The pre-authorisation amount. |
| transactionType | Optional | string | Should be set to 'PRE-AUTH'. |
| invoiceId | Mandatory | string | Mandatory. The unique merchant reference for the transaction. |
| sequenceType | Mandatory | string | Should be set to 'recurring'. |
| periodicType | Mandatory | string | Set to 'ucof' for unscheduled credential on file. |
| parentTransactionId | Mandatory | string | The ID of the initial transaction where the cardholder gave their consent for future charges |
Response Body:
{
"amount": "25",
"authCode": "PZ06IW",
"authDateTimeUTC": "2025-05-23T14:04:58.270534644Z",
"avsHouseNumberResult": "Not Set",
"avsPostcodeResult": "Not Set",
"cardExpiryDate": "12/25",
"cscResult": "Not Set",
"currency": "GBP",
"errorCode": "0",
"id": "1f53616d-12be-4aaa-9a0e-34d50861ca57",
"invoiceId": "MIT-17384893790",
"message": "Completed successfully",
"parentTransactionId": "11a4da77-4486-1291-9bf3-379702f5405d ",
"payerAuthenticationResult": "-/-",
"responseCode": "00",
"rrn": "514384057562",
"schemeReferenceData": "136175618084068",
"settled": false,
"success": true,
"transactionType": "PRE-AUTH"
};
Incremental Authorisation
Once a pre-authorisation is in place, you may increase the authorized amount by submitting Incremental Authorisation requests. You can send multiple incremental authorisations if needed.
Request:URL:POST https://test-api.dnapayments.com/v1/transactions/{initial_transaction_id}/increment-authorization
Note: {initial_transaction_id} is the ID of the original pre-authorisation MIT.
| Field Descriptions - Incremental Authorisation Request | |||
|---|---|---|---|
| Field | Status | Type | Description |
| amount | Mandatory | decimal | The pre-authorisation amount. |
| reason | Optional | string | Optional description of the additional amount. |
Example:
Headers:
Authorisation: Bearer authentication token with 'webapi' scopeRequest body:{
"amount": 5,
"reason": "Extra charge"
};
{
{
"amount": 5,
"authCode": "FBL2QO",
"authDateTimeUTC": "2025-05-23T14:06:06.435528482Z",
"id": "14a83656-2375-487c-886b-c46a6e098d0c",
"message": "Approved",
"parentTransactionId": "1f53616d-12be-4aaa-9a0e-34d50861ca57",
"responseCode": "00",
"rrn": "08844768278BF40C",
"schemeReferenceData": "136175618084068",
"settled": false,
"success": true,
"totalAuthorizedAmount": 30,
"authorizationEvents": [
{
"amount": 25,
"authCode": "PZ06IW",
"id": "1f53616d-12be-4aaa-9a0e-34d50861ca57",
"message": "Completed successfully",
"reason": "Initial auth",
"responseCode": "00",
"rrn": "514384057562",
"success": true,
"timestampUTC": "2025-05-23T14:04:58.270535Z",
"type": "initial"
},
{
"amount": 5,
"authCode": "FBL2QO",
"id": "14a83656-2375-487c-886b-c46a6e098d0c",
"message": "Approved",
"reason": "Extra charge",
"responseCode": "00",
"rrn": "08844768278BF40C",
"success": true,
"timestampUTC": "2025-05-23T14:06:06.435528482Z",
"type": "incremental"
}
]
}
};
| Field Descriptions - Top-Level Fields Description | |||
|---|---|---|---|
| Field | Type | Description | |
| amount | decimal | The amount authorised in the most recent requested authorisation event. | |
| authCode | string | The authorisation code returned by the issuer for the most recent authorisation. | |
| authDateTimeUTC | string | The UTC timestamp of the most recent authorisation. | |
| id | string | The unique identifier of the most recent authorisation transaction. | |
| message | string | A human-readable message describing the result of the most recent authorisation. | |
| parentTransactionId | string | The unique identifier of the initial MIT authorisation transaction to which this authorisation is linked. | |
| responseCode | string | A standard response code indicating the result of the authorisation (e.g., “00” = approved). | |
| rrn | string | The Retrieval Reference Number used for tracking the transaction across systems. | |
| schemeReferenceData | string | A reference number issued by the card scheme for tracking purposes. | |
| settled | boolean | Indicates whether the transaction has been settled (captured and cleared). | |
| success | boolean | Indicates whether the most recent authorisation attempt was successful. | |
| totalAuthorisedAmount | decimal | Indicates whether the most recent authorisation attempt was successful. | |
| authorisedEvents | array | A list of all authorisation events (initial, incremental, reversal, split-charge, final-charge). | |
| Fields in authorisationEvents | |||
|---|---|---|---|
| Field | Type | Description | |
| amount | decimal | The amount authorised in this specific event. | |
| authCode | string | The authorisation code issued for this specific event. | |
| id | string | The unique identifier for this specific authorisation event. | |
| message | string | A human-readable message summarizing the result of this authorisation. | |
| reason | string | A short explanation for this event (e.g., “Initial auth”, “Extra charge”) as provided in the request. | |
| responseCode | string | The issuer response code for this event (e.g., “00” = approved). | |
| rrn | string | The Retrieval Reference Number for this event. | |
| success | boolean | Indicates whether this individual event was successful. | |
| timestampUTC | string | The UTC timestamp of this event in ISO 8601 format. | |
| type | string | Type of authorisation event: • initial – Original pre-authorisation • incremental – Additional authorised amount • reversal – Released voided authorisation • split-charge – Partial capture • final-charge – Final capture of funds | |
Reversal of Authorised Amount
A full reversal of previously authorised but not yet captured amounts can be processed using the standard reversal endpoint as part of regular business operations. Documentation is available on the Developer Portal:
https://developer.dnapayments.com/docs/ecommerce/checkout/transaction-management/txn-reversal
Note: If you need to capture an amount less than what was originally authorised, you can use the transaction settlement request described in the next section. This will allow you to perform apartial capture, and the remaining authorised funds will be automatically reversed back to the customer.Authorisation Capture
Once the final amount is known, the authorised funds must be captured. To support partial or staged captures (e.g., for multi-stage service delivery), you can use the optional "intent" parameter in the settlement request:
• "intent": "split" - Use this when performing a partial capture. The transaction remains open for further captures.
• "intent": "final" - Use this for the final capture. It will settle the transaction and automatically reverse any remaining authorised funds.
Important: If the "intent" parameter is not provided, the capture will be treated as final by default.Request POST https://test-api.dnapayments.com/transaction/operation/charge
Authorisation: Bearer authentication token with 'webapi' scope| Fields Descriptions | |||
|---|---|---|---|
| Field | Type | Description | |
| id | string | ID of the initial pre-authorisation MIT transaction. | |
| amount | decimal | Amount to capture. Must be less than or equal to the total authorized amount. | |
| reason | string | Optional. Reason for the charge. | |
| intent | string | Optional. "final" if this is the final charge. "split" if more charges to follow | |
The request and response contain the standard fields as described in the documentation:
https://developer.dnapayments.com/docs/ecommerce/checkout/transaction-management/txn-settlement
In addition, the request includes an extra field "intent", and the response includes "authorisationEvents", both of which are explained earlier in this document.
Example:Request body:POST https://test-api.dnapayments.com/transaction/operation/charge
Authorisation: Bearer access_token
{
"id": "7f53616d-12be-4aaa-9a0e-34d50861ca57",
"amount": 27,
"reason": "Capture",
"intent": "final"
};
{
"amount": 27,
"authCode": "PZ06IW",
"authorizationEvents": [
{
"amount": 25,
"authCode": "PZ06IW",
"id": "1f53616d-12be-4aaa-9a0e-34d50861ca57",
"message": "Completed successfully",
"reason": "Initial auth",
"responseCode": "00",
"rrn": "514384057562",
"success": true,
"timestampUTC": "2025-05-23T14:04:58.270535Z",
"type": "initial"
},
{
"amount": 5,
"authCode": "FBL2QO",
"id": "74a83656-2375-487c-886b-c46a6e098d0c",
"message": "Approved",
"reason": "Extra charge",
"responseCode": "00",
"rrn": "08844768278BF40C",
"success": true,
"timestampUTC": "2025-05-23T14:06:06.435528482Z",
"type": "incremental"
},
{
"amount": 27,
"authCode": "PZ06IW",
"id": "6f490103-de56-4d4e-95ab-ee075cdc2329",
"message": "Approved",
"reason": "Capture",
"responseCode": "00",
"rrn": "D34CD7CA7CE43B4B",
"success": true,
"timestampUTC": "2025-05-23T15:06:38.781475483+01:00",
"type": "final-charge"
}
],
"currency": "GBP",
"errorCode": 0,
"id": "1f53616d-12be-4aaa-9a0e-34d50861ca57",
"invoiceId": "MIT-17384893790",
"message": "Approved",
"payoutAmount": 27,
"responseCode": "00",
"success": true,
"transactionState": "CHARGE"
};