Create Order

Overview

In this section, we cover:

3. POST createOrder - confirm the bank and other transaction specific details.
4. Display consent page - a mandatory step fo Open Banking. Can be optionally combined with step 2 - Offer Bank List.

There are additional steps in the payer process which are completed securely outside of your website. This reduces your PCI compliance liability and provides peace of mind for the buyer.

POST createOrder

Request

URL

Test URL: https://test-api.dnapayments.com/payments/alternative/createOrder

Production URL: https://api.dnapayments.com/payments/alternative/createOrder

The request is completed by a POST to the above URL's with these headers:

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

And the createOrder payload as shown here:

POST createOrder
Field Name	Data Type	State	Description
bankId	String	Mandatory	Unique identification String
amount	Decimal	Mandatory	Total amount of the order a GBP account will be proThis value must match t the request will be reject
currency	String	Mandatory	Currency of the transactioThis value must match t the request will be reject
invoiceId	String	Mandatory	Order/invoice/transaction/ for this transaction.This value must match t the request will be reject
description	String	Optional	Message from host website to consumer, displayed on the payment form and merchant portal.
accountId	String	Optional	Buyer’s account reference for the store processing the transaction.
email	String	Optional	Email address provided by consumer as main contact address.
locale	String	Optional	Consumer language - used by DNA Payments Checkout to build the payment form eng
terminalId	String	Mandatory	Provided to the integrator following the successful creation of a merchant account. This value must match the value provided during authorisation if unique tokens are used or the request will be rejected.
paymentMethod	String	Mandatory	Payment method ecospend
transactionType	String	Mandatory	SALE
returnUrl	String	Mandatory	Address where the consumer is to be returned following a successful payment.
callbackUrl	String	Mandatory	Confirms where DNA Payments is to send the payment/refund notification (payment/refund result callback) in the event of a successful result.
failureCallbackUrl	String	Optional	Confirms where DNA Payments is to send the payment/refund notification (payment/refund result callback) in the event of an unsuccessful result.
billingAddress	Object	Mandatory	An object containing several mandatory and optional billing address fields. See billingAddress for more details.

billingAddress

billingAddress
Field Name	Data Type	State	Description
firstName	String	Mandatory	First name of the addressee. If the Merchant does not hold the title and last name separately, the full name is provided here and title, last name and middle names are left bank.
lastName	String	Optional	Last name of addressee.
streetAddress1	String	Mandatory	Address Line 1 consumer resides in.
postalCode	String	Optional	Post code for consumer’s given address.
city	String	Mandatory	City consumer resides in.
country	String	Mandatory	Country consumer resides in. ISO 3166-1 (2 or 3 Char.)

Response

If successful, this method returns a 200 OK Response.

createOrder Response
Field Name	Data Type	Description
accountId	String	Unique reference for the store processing the transaction, as passed in the request.
amount	Decimal	Total amount of the order including decimal places where applicable. ‘Whole’ amounts (e.g. “1”) on a GBP account represents £1.00.
authDateTimeUtc	String	Date and time of when the transaction was authorised with the acquirer.
bankUrl	String	A unique and one time use only URL of the debtor's banking system. You will need to redirect a merchant to this link in order the payment to proceed.
currency	String	Currency of the transaction GBP
errorCode	Integer	Provides additional detail should an error have occurred with the transaction.
id	String	Unique transaction ID. This ID should be stored as it is required for later transaction actions.
invoiceId	String	Order/invoice/transaction/basket number generated by the host website, as passed in the request.
message	String	Message confirming the processing result of the request.
paymentMethod	String	Payment method ecospend
rrn	String	Unique reference allocated by Ecospend.
status	String	Ecospend payment status.
success	Boolean	Confirms whether the transaction has been successful.

Example Request and Response

Request

{
    "bankId": "obie-coutts-sandbox",
    "amount": 25,
    "currency": "GBP",
    "invoiceId": "1631161931",
    "description": "Car Service",
    "accountId": "uuid000001",
    "email": "example@merchant.com",
    "locale": "eng",
    "terminalId": "z553ffcc-7df4-44b1-887b-la4108af9c94",
    "paymentMethod": "ecospend",
    "transactionType": "SALE",
    "returnUrl": "https://test.com",
    "callbackUrl": "https://test.com",
    "failureCallbackUrl": "https://test.com",
    "billingAddress": {
        "firstName": "John",
        "lastName": "Doe",
        "streetAddress1": "Fulham Rd",
        "postalCode": "SW6 1HS",
        "city": "London",
        "country": "GB"
    }
}

Response

{
    "accountId": "uuid000001",
    "amount": 25,
    "authDateTimeUtc": "2021-09-09T04:32:26.381179864Z",
    "bankUrl": "https://api.coutts.useinfinite.io/authorize?response_type=code%20id_token&client_id=CPtWqIqSCNqnGWNjnDzPG-9bnBVnvBUO3OKExwDBA8=&scope=openid%20payments&redirect_uri=https://redirect.ecospend.com/redirect/ TRUNCATED",
    "currency": "GBP",
    "errorCode": 0,
    "id": "9de52ca0-19ed-4467-8cdc-2c11a715d7da",
    "invoiceId": "1631161931484",
    "message": "Order successfully created",
    "paymentMethod": "ecospend",
    "rrn": "0107108d-326d-49f4-8420-21abf8e2dc5c",
    "status": "AwaitingAuthorization",
    "success": true
}

Display Consent Page

You are required to display a consent page to the payer before redirecting them to their chosen bank's URL. Ecospend document the mandatory requirements here and they also provide a link to the OBIE Customer Experience Guidelines (OBIE CEG) which provide some best practice around this required step.

tip

Once you have received the payer's consent, you can move on to redirecting them to the Payment Page.