Create Payment Link

POST Create Payment Link

URLs

LIVE: https://api.dnapayments.com/v1/payment-links

TEST: https://test-api.dnapayments.com/v1/payment-links

Creation of a payment link is achieved by sending a HTTP POST request to these URLs. The access_token will be the one received in the Authentication Response.

Please note, there are two types of payment link available, One time and Multiuse. See below for examples.

HTTP Headers

HTTP Header
Field Name	State	Data Type	Description
Content-Type	Mandatory	String	application/json
Authorization	Mandatory	String	Bearer access_token

Request Details

Create Payment Link request
Field Name	State	Data Type	Description
amount	Mandatory	Float	The amount of the payment, expressed as a decimal e.g. 5.00 for £5
currency	Mandatory	String	GBP Pound Sterling
invoiceId	Optional	String	Merchant’s order number. You can pass your own system ID or use an autogenerated unique number to reconcile the payment in your accounting system. In a Multilink scenario, where the merchant sets the root Order ID and DNA systems add the suffix. This must be provided in the invoiceId field of the request. Each processed payment will then have the invoiceId plus a unique suffix.
terminalId	Mandatory	String	Terminal ID for the Merchant. This should match a terminalId that is assigned to the client-id and client-secret used in the Authentication request.
expirationDate	Mandatory	String	The expiration date of the payment Link. ISO 8601 format e.g. 2021-11-30T16:00:00Z When creating a Multiuse link, this field is optional.
customerName	Mandatory	String	The name of the customer.
description	Optional	String	A description of what the customer is paying for. Useful to provide reassurance and consumer confidence as well as aid reconciliation and success rates.
transactionType	Optional	String	AUTH Authorisation only SALE Authorisation and Settlement VERIFICATION Card verification and tokenisation PRE-AUTH Pre-authorisation
merchantCustomData	Optional	String	Custom data that can be provided
periodic	Optional	Object	See the periodic table.
paymentSettings	Optional	Object	See the paymentSettings table.
customerDetails	Optional	Object	See the customerDetails table.
linkOptions	Optional	Object	See the linkOptions table.

periodic

Used when setting up a Recurring/Subscription type payment link.

Request Details> periodic
Field Name	State	Data Type	Description
periodicType	Optional	String	The only supported value at present is ucof
sequenceType	Optional	String	The only supported value at present is initial

paymentSettings

Best Practice Advice

Use the paymentSettings object in the Create Payment Link request to configure webhooks and receive immediate notifications of the payment link outcome.

Request Details> paymentSettings
Field Name	State	Data Type	Description
returnUrl	Optional	String	Your return Url for successful payments
failureReturnUrl	Optional	String	Your return Url for failed transactions
callbackUrl	Optional	String	Your endpoint for successful payments
failureCallbackUrl	Optional	String	Your endpoint for failed transactions

customerDetails

Best Practice Advice

Use the customerDetails object in the Create Payment Link request to prepopulate known information and avoid asking shoppers to re-enter it.

Request Details> customerDetails
Field Name	State	Data Type	Description
email	Optional	String	Set customers Email address
billingAddress	Optional	Object	See the billingDetails table.

billingDetails

Request Details> customerDetails> billingDetails
Field Name	State	Data Type	Description
lastName	Optional	String	Set customers Last Name
address1	Optional	String	Set customers 1st Line address
address2	Optional	String	Set customers 2nd Line address
city	Optional	String	Set customers city
postalcode	Optional	String	Set customers postcode
country	Optional	String	Set customers country

linkOptions

Important to note

The reusable link remains active until its expirationDate is reached. This should still be added in the API request, as otherwise our systems will set the expiration date to T+3 years by default.

Each payment made through the same reusable link creates a separate transaction record.

When using reusable links, the value of "invoiceId" provided by the merchant is used as the base payment reference. For each payment record, a dash (-) and a unique 9-character suffix (e.g., -123ABCXYZ) are automatically appended to this value, ensuring each payment has a unique reference.

Multi-use Link Tip 1

When a multi-use link is created, the API response remains the standard response format; however, it includes additional fields indicating that the link is configured for multi-use. If the merchant has provided webhook URLs (such as callbackUrl or failureCallbackUrl), a payment result notification will be sent for each individual payment using the standard webhook payload. If required, merchants may parse the invoiceId to correlate it with their original reference (for example, by extracting the portion before the delimiter or removing the generated unique suffix).

Multi-use Link Tip 2

When a multi-use link is created, and the amount is set to a value greater than 0, that value will be displayed on the Checkout page as a prefilled amount. The customer may proceed with this amount or adjust it if required. When the amount is set to 0, no prefilled amount will be shown, and the customer will be required to enter the amount on the Checkout page.

Request Details> linkOptions
Field Name	State	Data Type	Description
mode	Optional	String	ONE_OFF_FIXED One-time payment link with a fixed-amount. This is the default behaviour when this element is not present in the request REUSABLE_FIXED Reusable payment link with a fixed amount REUSABLE_VARIABLE Reusable payment link where the payer can enter their own amount
minAmount	Optional	String	Minimum allowed amount. Only used when selected mode is REUSABLE_VARIABLE, ignored otherwise
maxAmount	Optional	String	Maximum allowed amount. Only used when selected mode is REUSABLE_VARIABLE, ignored otherwise

Create Payment Link Response

If the request is successful, you will receive a 200 OK response code, and the following response fields.

Field name	Type	Description
id	String	Payment link ID, the unique reference for this payment link assigned by the DNA Platform.
amount	Float	The amount of the payment, as a decmal.
currency	String	Currency e.g. GBP.
invoiceId	String	The InvoiceId supplied in the Request, if applicable.
terminalId	String	The terminal ID supplied in the request.
customerName	String	The Customer name.
description	String	The description as supplied in the request.
createdDate	String	The date that the Payment Link was created.
expirationDate	String	The date that the Payment Link will expire.
viewedDate	String	The date that the Payment Link was viewed. Null if not applicable.
attemptedDate	String	The date that the Payment Link was attempted. Null if not applicable.
paidDate	String	The date that the Payment Link was viewed. Null if not applicable.
cancelledDate	String	The date that the Payment Link was viewed. Null if not applicable.
status	String	Payment link status. See Statuses for more details.
url	String	Full payment link URL

Example Request and Response - Static Link

Request

POST https://test-api.dnapayments.com/v1/payment-links
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
Content-Length: 232
{
    "amount": 1,
    "currency": "GBP",
    "invoiceId": "PL-1605200674803",
    "terminalId": "4511a14f-61a3-4449-a1c1-7a314ee2374c",
    "expirationDate": "2020-11-13T17:04:50.493Z",
    "customerName": "Dave",
    "description": "For a coffee"
}

Response

{
    "id": "69lXLdv9w",
    "amount": 1,
    "currency": "GBP",
    "invoiceId": "PL-1605200674803",
    "terminalId": "4511a14f-61a3-4449-a1c1-7a314ee2374c",
    "customerName": "Dave",
    "description": "For a coffee",
    "createdDate": "2020-11-12T17:05:31.113206697Z",
    "expirationDate": "2020-11-13T17:04:50.493Z",
    "viewedDate": null,
    "attemptedDate": null,
    "paidDate": null,
    "cancelledDate": null,
    "status": "active",
    "url": "https://test-pay.dnapayments.com/checkout/?r=69lXLdv9w"
}

Example Request and Response - Multi-use Link

Request

POST https://test-api.dnapayments.com/v1/payment-links
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
Content-Length: 232
{
  "amount": 5,
  "currency": "GBP",
  "invoiceId": "SUMMERFEST25",
  "description": "Order description",
  "terminalId": "2347a31f-61a3-4449-a1c1-7a314ee5644c",
  "expirationDate": "2027-11-30T12:20:29.776Z",
  "paymentSettings": {
    "returnUrl": "https://return.url",
    "failureReturnUrl": "https://failure-return.url",
    "callbackUrl": "https://webhook.url",
    "failureCallbackUrl": "https://failure-webhook.url"
  },
  "customerDetails": {
    "billingAddress": {
      "firstName": "User",
      "lastName": "User",
      "addressLine1": "Street 123",
      "postalCode": "IL5 456",
      "city": "London",
      "country": "GB"
    },
    "email": "demo@dnapayments.com"
  },
  "transactionType": "SALE",
  "merchantCustomData": "Custom field 3",
  "linkOptions": {
    "mode": "REUSABLE_VARIABLE",
    "minAmount": 4,
    "maxAmount": 7
  }
}

Response

{
    "id": "69lXLdv9w",
    "amount": 1,
    "currency": "GBP",
    "invoiceId": "PL-1605200674803",
    "terminalId": "4511a14f-61a3-4449-a1c1-7a314ee2374c",
    "customerName": "Dave",
    "description": "For a coffee",
    "createdDate": "2020-11-12T17:05:31.113206697Z",
    "expirationDate": "2020-11-13T17:04:50.493Z",
    "viewedDate": null,
    "attemptedDate": null,
    "paidDate": null,
    "cancelledDate": null,
    "status": "active",
    "url": "https://test-pay.dnapayments.com/checkout/?r=69lXLdv9w",
    "linkOptions": {
    "mode": "REUSABLE_VARIABLE",
    "minAmount": 4,
    "maxAmount": 7
  }
}