Payment Request

Overview

Once you have authenticated, you are able to send further requests in to the API. You will need to:

1. GET Banks - use the API to return a list of banks available at this time.
2. Offer Bank List - provide the bank list to the Payer and allow them to choose their bank.
3. POST createOrder - confirm the bank and other transaction specific details.
4. Display consent page - a mandatory step fo Open Banking. Can be combined with step 2.
5. Redirect the payer - send the Payer to the provided bankURL.
6. Display successful outcome - following a successful payment, ensure the payer is advised.

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.

GET Banks

Request

URL

Test URL: https://test-api.dnapayments.com/v1/ecospend/banks

Production URL: https://api.dnapayments.com/v1/ecospend/banks

The request is completed via a GET request to the test URL shown above, and should contain the below header data. The access_token will be the one received in the Authentication Response.

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

Example

GET https://test-api.dnapayments.com/v1/ecospend/banks
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

Response

If the request is successful, the method will return a 200 response code. All your merchants will be returned as an array containing the following fields:

GET Banks
Field Name	Data Type	Description
data	Array	An array of objects for each bank available. See the data array for more information.
meta	Object	Meta data for the entire response. See the meta Object for more details.

data Array

data Array
Field Name	Data Type	Description
bank_id	String	The unique bank ID, derived from the EcoSpend system.
name	String	The name of the bank.
friendly_name	String	The friendly name of the bank.
is_sandbox	String	Indicates if the record returned is in a sandbox (test) bank environment.
logo	String	The logo URL of the bank.
icon	String	The icon url of the bank.
standard	String	Which open banking standard is implemented by the bank. Available options are: obie stet berlingroup
country_iso_code	String	The country code that the bank operates in.
division	String	The division of the bank e.g. Available options are: personal business corporate
group	String	The group where applicable of the bank e.g Barclays.
order	String	The preference of the bank. Can be amended to show a given bank before another.
service_status	Boolean	Indicates if the bank's services are online currently.
refund_supported	Boolean	Indicates if the bank's services are online currently.
abilities	Object	The operations supported by the specific bank. See the abilities Object for more information

abilities Object

meta Object
Field Name	Data Type	Description
domestic_payment	Boolean	true if the bank supports Domestic Payments.
domestic_scheduled_payment	Boolean	true if the bank supports Domestic Scheduked Payments.
domestic_standing_order	Boolean	true if the bank supports Domestic Standing Orders.
domestic_standing_order_installment	Boolean	true if the bank supports Domestic Standing Order Installments.
domestic_standing_order_yearly_period	Boolean	true if the bank supports yearly intervals for Domestic Standing Order Payments.
international_payment	Boolean	true if the bank supports International Payments.
international_scheduled_payment	Boolean	true if the bank supports International Scheduled Payments.
international_standing_order	Boolean	true if the bank supports International Standing Orders.
bulk_payments	Boolean	true if the bank supports Bulk Payments.

meta Object

meta Object
Field Name	Data Type	Description
total_count	Integer	The total number of Banks returned.
total_pages	Integer	The total number of pages.
current_page	Integer	Current page.

Example

{
  "data": [
    {
      "bank_id": "obie-coutts-sandbox",
      "name": "Barclays Personal",
      "friendly_name": "Coutts Online Banking Test",
      "is_sandbox": true,
      "logo": "https://{uri}",
      "icon": "https://{uri}",
      "standard": "obie",
      "country_iso_code": "GB",
      "division": "Personal",
      "group": "CMA9",
      "order": 0,
      "service_status": true,
      "refund_supported": false,
      "abilities": {
        "domestic_payment": true,
        "domestic_scheduled_payment": true,
        "domestic_standing_order": true,
        "domestic_standing_order_installment": true,
        "domestic_standing_order_yearly_period": true,
        "international_payment": true,
        "international_scheduled_payment": true,
        "international_standing_order": true,
        "bulk_payments": true
      }
    }
  ],
  "meta": {
    "total_count": 0,
    "total_pages": 0,
    "current_page": 0
  }
}

tip

Regardless of the various abilities offered by the Banks, the DNA Open Banking API supports domestic_payment only.

Offer Bank List

Having identified the banks, you should present these to the Payer within your own solution. We recommend using the supplied icon and logo URL's to provide payer confidence.

Once the bank has been selected by the Payer, you are ready to initiate the payment request.

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.

Redirect to Payment Page

After a user consents to continue to their bank, you should redirect the payer to the bankUrl provided as a part of the createOrder Response.

After that, the process continues on between the payer and their online banking system. Despite slight differences between banks, in principle, the payer logs in to their bank's system, sees the payment details and then authorises or cancels the payment. They, of course, can abandon without completing the process.

After completing the authorization process at their bank, the payer will be redirected to Ecospend's redirect URL. In the meantime, Ecospend Gateway will retrieve the status of the payment from the bank. Then Ecospend will send the payer to us. Finally, we return the payer to your returnUrl and we will send a Callback response to your callbackUrl, as per the below specification:

Callback Response

tip

It is us who will send this POST to your callbackUrl, so it is presented as a response. If this POST fails however, we will not be able to retry it and you should utilise our Transaction Management API to determine the outcome of the transaction.

You can do this in response to receiving the redirected payer, if you have not received the callback Response in a timely manner.

callback POST
Field Name	Data Type	Description
signature	string	Signature generated for the callback.
id	string	Unique transaction ID. This ID should be stored as it is required for later transaction actions.
paymentMethod	string	Payment method ecospend
rrn	string	Unique reference allocated by Ecospend.
amount	decimal	Refund amount.
currency	string	Currency of the transaction GBP
invoiceId	string	Order/invoice/transaction/basket number generated by the host website, as passed in the request.
accountId	string	Unique reference for the store processing the transaction, as passed in the request.
authDateTimeUtc	string	Date and time of when the transaction was authorised with the acquirer.
errorCode	integer	Provides additional detail should an error have occurred with the transaction.
success	boolean	Confirms whether the transaction has been successful.
transactionState	string	The current state of the transaction.
status	string	Ecospend payment status

Example Response

{
    "signature": "yDlqMP0vM/grI/VCFwM/q5lMBwBDKTr/hTjPze0Ca3Y=",
    "id": "374873d1-f69e-44bd-a637-5b5b28734021",
    "paymentMethod": "ecospend",
    "rrn": "5dc9e424-f878-4114-bc18-3b5e414ac41f",
    "amount": 3,
    "currency": "GBP",
    "invoiceId": "1631891547494",
    "accountId": "uuid000001",
    "authDateTimeUtc": "2021-09-17T15:12:37.016969534Z",
    "errorCode": 0,
    "success": true,
    "transactionState": "CHARGE",
    "status": "Completed"
}

Display Successful Outcome