OpenBanking API

Start developing your OpenBanking integration via api using the api resources and guide steps below.

OpenBanking Model

The Open Banking utilizes asynchronous flow for server to server bla bla. The primary steps are as follows for integrating:

1. Send a payment request Send a payment request to the endpoint to do something
2. Redirect Customer Guide the customer to the payment page to complete the transaction.
3. Retrieve the payment status Verify the payment status and notify the customer.

Send a Payment Request

The first step is to send a server-to-server initial payment request with all required properties. Refer to the API Reference for additional properties to include. The result of the payment request will include a redirect object which will be used to redirect the customer.

"id": "",
"paymentType": "DB",
"paymentBrand": "ACI_INSTANTPAY",
"amount": "10.00",
"currency": "GBP",
"descriptor": "Open Banking Test channel",
"result": {
  "code": "000.200.000",
  "description": "transaction pending"
},
"resultDetails": {
  "ExtendedDescription": "Request created, operation in progress.",
  "ConnectorTxID2": "",
  "AcquirerResponse": "PENDING"
},
"bankAccount": {
  "country": "GB"
},
"redirect": {
  "url": "https://web-app.sandbox.token.io/app/request-token/rq:*****************",
  "method": "GET",
  "parameters": []
},
"buildNumber": "",
"timestamp": "",
"ndc": ""

Redirect the customer

The next step is to redirect the account holder to the Token platform to perform a payment. To do this, parse the redirect object from the payment request response in the previous step, which contains a URL and a method. For this connection it will be consistently a GET request and no additional parameters will need to be passed. A successful redirect will show the Token Platform for customer.

Get Payment Status

Once the payment has been processed, the customer is redirected to your shopperResultUrl along with a GET parameter resourcePath. To get the status of the payment, you should make a GET request to the baseUrl + resourcePath, including your authentication parameters.

"type": "PAYMENT",
"payload": {
  "id": "",
  "ndc": "",
  "risk": {
    "score": ""
  },
  "amount": "10.00",
  "result": {
    "code": "000.100.112",
    "description": "Request successfully processed in 'Merchant in Connector Test Mode'",
    "randomField1184162296": "Please allow for new unexpected fields to be added"
  },
  "source": "OPP",
  "shortId": "",
  "currency": "GBP",
  "redirect": {
    "url": "",
    "parameters": []
  },
  "timestamp": "",
  "descriptor": "",
  "bankAccount": {
    "country": "GB"
  },
  "channelName": "Open Banking Test channel",
  "paymentType": "DB",
  "paymentBrand": "ACI_INSTANTPAY",
  "paymentMethod": "DD",
  "resultDetails": {
    "ConnectorTxID1": "",
    "ConnectorTxID2": "",
    "AcquirerResponse": "SUCCESS",
    "ExtendedDescription": "Operation completed successfully.",
    "Transfer Transaction Id": ""
  },
  "authentication": {
    "entityId": "8ac7a4ca88fd9b770188fdb188910016"
  },
  "customParameters": {
    "ACI_INSTANTPAY.COUNTRY": "GB"
  },
  "merchantAccountId": "",
  "presentationAmount": "10.00",
  "presentationCurrency": "GBP"
}

Handling Pending Payment Status

Depending on the issuing bank, the time taken to send the final approval confirmation to the gateway can vary. This means that the customer might be redirected to the payment completion page before the final status of the payment has been determined. In such cases, you will receive a new pending status from the payment response API.

Response indicating additional time is needed for approval:

• Transaction Pending (00)

• (000.200.001)Transaction pending for acquirer, consumer not present

If this response is received, you will need to wait for the final confirmation before considering the payment as finalized. To obtain the final status, you have two options:

1. Periodically call the payment response API until the payment status is updated.
2. Integrate webhooks into your system. With this method, you will receive a webhook notification once the issuing bank sends the confirmation.

Please note that this delay is unavoidable and is related to the banking systems.

Recommended Approach

We do not recommend keeping the customer on the page while waiting for the payment response. In our systems, we advise the customer to wait for a confirmation email.

Example Frontend Message:

Your order is being processed. We're finalizing your payment with the bank. You'll get a confirmation email once approved, so no need to resubmit your payment.

Time before final response