Create Order

Overview

In this section, we cover:

  1. POST createOrder - confirm the bank and other transaction specific details.
  2. 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

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

HTTP Header
Field NameStateData TypeDescription
Content-TypeMandatoryStringapplication/json
Content-TypeMandatoryStringBearer access_token

And the createOrder payload as shown here:

POST createOrder
Field NameData TypeStateDescription
bankIdStringMandatoryUnique identification String
amountDecimalMandatoryTotal amount of the order a GBP account will be proThis value must match t the request will be reject
currencyStringMandatoryCurrency of the transactioThis value must match t the request will be reject
invoiceIdStringMandatoryOrder/invoice/transaction/ for this transaction.This value must match t the request will be reject
descriptionStringOptionalMessage from host website to consumer, displayed on the payment form and merchant portal.
accountIdStringOptionalBuyer’s account reference for the store processing the transaction.
emailStringOptionalEmail address provided by consumer as main contact address.
localeStringOptionalConsumer language - used by DNA Payments Checkout to build the payment form eng
terminalIdStringMandatoryProvided 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.
paymentMethodStringMandatoryPayment method ecospend
transactionTypeStringMandatorySALE
returnUrlStringMandatoryAddress where the consumer is to be returned following a successful payment.
callbackUrlStringMandatoryConfirms where DNA Payments is to send the payment/refund notification (payment/refund result callback) in the event of a successful result.
failureCallbackUrlStringOptionalConfirms where DNA Payments is to send the payment/refund notification (payment/refund result callback) in the event of an unsuccessful result.
billingAddressObjectMandatoryAn object containing several mandatory and optional billing address fields.
See billingAddress for more details.

billingAddress

billingAddress
Field NameData TypeStateDescription
firstNameStringMandatoryFirst 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.
lastNameStringOptionalLast name of addressee.
streetAddress1StringMandatoryAddress Line 1 consumer resides in.
postalCodeStringOptionalPost code for consumer’s given address.
cityStringMandatoryCity consumer resides in.
countryStringMandatoryCountry consumer resides in. ISO 3166-1 (2 or 3 Char.)

Response

If successful, this method returns a 200 OK Response.

createOrder Response
Field NameData TypeDescription
accountIdStringUnique reference for the store processing the transaction, as passed in the request.
amountDecimalTotal amount of the order including decimal places where applicable. ‘Whole’ amounts (e.g. “1”) on a GBP
account represents £1.00.
authDateTimeUtcStringDate and time of when the transaction was authorised with the acquirer.
bankUrlStringA 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.
currencyStringCurrency of the transaction GBP
errorCodeIntegerProvides additional detail should an error have occurred with the transaction.
idStringUnique transaction ID. This ID should be stored as it is required for later transaction actions.
invoiceIdStringOrder/invoice/transaction/basket number generated by the host website, as passed in the request.
messageStringMessage confirming the processing result of the request.
paymentMethodStringPayment method ecospend
rrnStringUnique reference allocated by Ecospend.
statusStringEcospend payment status.
successBooleanConfirms whether the transaction has been successful.

Example Request and Response

{
"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"
}
}

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.