Skip to main content

Webhook Details

The Webhook functionality allows you to receive a POST from DNA Payments with the details for that transaction enclosed as JSON content. The HTTPS URL you provide in the Start Transaction request must conform to the following criteria:

AttributeCriteria
UrlHTTPS address as supplied in the Webhook URL
AuthenticationAnonymous
Supported Media Typesapplication/json
HTTP MethodPOST
Supports FilteringNo
Request TypeTransaction Information

With the following Request Header Information:

KeyValue
Acceptapplication/json
Content-Typeapplication/json; charset=utf-8
Content-Digest
Signature-Input
Signature

All messages are sent as UTF 8 encoded JSON messages and will not contain any field that is ‘null’.

Header Fields​

All header fields conform to the RFC 8941 Structured Values for HTTP standard. Whilst the standard supports various header fields, the key ones that are of interest for the webhook handling are:

FieldHeader NameRFC 8941 Data TypeDescription
Content DigestContent-DigestDictionaryThis contains a single entry that represents the hash of the message.  The key of the field identifies the hash algorithm, and the value is the hash of the message. DNA Payments will support returning the hash as a SHA-256 hash using PKCS#1 padding.
Content LengthContent-LengthLongThis is the length of the message content.
Content TypeContent-TypeListThis is the content type and any associated parameters.
Signature InputSignature-InputDictionaryThis provides the details of what fields make up a given signature.  The key indicates the signature identifier.  The value contains the list of fields and any associated parameters. The signature identifier that is to be processed will be identified as ‘sig1’.
SignatureSignatureDictionaryThis provides the signature details.  The key indicates the signature identifier.  The value contains the signature. The signature identifier that is to be processed will be identified as ‘sig1’.
note

Details of how to validate the signature we supply can be found in the Signature Verification section.

Webhook Response Payload​

The Webhook Response is a JSON payload, in the same format as a GET /transaction Response. Please refer to the table in the API Messages > GET transaction section for more information.

Webhook Payload Example​

Webhook payloads are only sent when the transactionStatus field is Complete. Below are three example payloads, showing a successful, cancelled and declined payment attempt.

{
    "uti": "1d027a88-5821-4442-bb4a-14123fc3fac9",
    "transType": "SALE",
    "transApproved": true,
    "transPartiallyApproved": false,
    "transCancelled": false,
    "amountTrans": 150,
    "amountGratuity": 0,
    "amountCashback": 0,
    "cvmSignatureRequired": false,
    "cvmPinVerified": false,
    "transCurrencyCode": "GBP",
    "terminalId": "31297280",
    "merchantId": "12345678",
    "softwareVersion": "1.00.50-11136",
    "receiptNumber": "36",
    "retrievalReferenceNumber": "000036170001",
    "paymentId": "39013/85/10042023153038152",
    "responseCode": "00",
    "stan": "85",
    "authorisationCode": "123ABC",
    "merchantTokenId": "koAu92lmmn7Vt1gybo5mqaA3fIci0vmRQvpfnwpDegsfMQ==",
    "cardPan": "************0102",
    "cardStartDate": "0401",
    "cardScheme": "MasterCard",
    "cardPanSequenceNumber": "001",
    "cardType": "CTLS",
    "emvAid": "A0000000041010",
    "emvTsi": "0000",
    "emvTvr": "0000008001",
    "emvCryptogram": "6AFC0FCCAFAEE14D",
    "emvCryptogramType": "ARQC",
    "reference": "Test3",
    "merchantName": "Test",
    "transDateTime": "2023-04-10T15:30:00Z",
    "createdDateTime": "2023-04-10T15:30:15.0462675Z",
    "merchantStoreId": 14759,
    "status": "Complete"
}