Open Banking Guide

In this guide, you’ll learn how to process a transaction with the Bank Payment payment method via direct API integration using our Bank Payment infrastructure. We also provide information on testing Bank Payment, including a checklist for testing key scenarios and steps to use our mock bank for the redirect.

First, we submit a mandatory request to initiate a Bank Payment transaction. It needs to include the transaction’s core parameters so that we have enough information to create the payment with our infrastructure partner, Token, and the customer’s bank. A successful transaction request will return a unique Bank Payment transaction identifier and a redirect URL, which you’ll use to facilitate the customer confirmation of the transaction (Step 2).

The following illustration shows the high-level flow for creating a Bank Payment transaction.

Sample request

Bank Payment conditional fields

The Bank Payment conditional fields (type = C) capture the merchant’s bank details that are required to complete the transaction. These fields are conditional based on the payment types SEPA or FASTERPAYMENTS. However, these fields remain optional. If they remain blank in the request, we will use the bank details in our database. You can still opt to use different details on a request-by-request basis, which will override what is stored in our database. This is only relevant for Direct Settlement. For Managed Settlement, we provide the bank details.

How to build the request hash

1. Hash a string made up of the request values

You can use any of the following algorithms: SHA1, SHA256, SHA384, or SHA512. We highly recommend SHA512. The blueprint of the hash for this request is:

No bank details included in the request:

"Timestamp.merchantid.orderid.amount.currency.sortcode.accountnumber.iban"

The timezone is Europe/Dublin and should be the time the transaction is initiated.

Our initial string for a GBP transaction will be:

"20220118101735.MerchantId.3400dd37-101d-4940-be15-3c963b6109b3.1001.GBP.123456.12345678."

If the payment method type was SEPA, we don’t include the Sort Code and Account Number. So, our EUR string would be:

"20220118101735.MerchantId.3400dd37-101d-4940-be15-3c963b6109b3.1001.GBP...123456789101112"

If the bank details are not sent in the request (managed settlement or using the default details from your configuration), then the sortcode.accountnumber.iban would need to be populated as blank while generating hash to comply with the hash format.

2. Concatenate the hashed string with your Shared Secret with a dot(.) as a separator

After step 1, you'll have a string that you can now concatenate with your Shared Secret. For example: Po8lRRT67a is the Shared Secret in the below example.

"e8aedc5ddc9025f72ee71a6f7a48aaa638a09493354f65efd984ffefbe5420867d121f3b395644300063f349f79293511ac481d02bfb39531e227e2ff70224a7.Po8lRRT67a"

3. Hash the concatenated string

The final string to add to the request header should be a hash of your concatenated string, using the same algorithm as in step 1.

a641a3f6937a809b5fec294160f1a9e451a518835110854c4280150bf69206a4562709e69a3d29b90671d887f78b993cadf973a2d93e33207afdd33d78741399

Sample response

The response to a Transaction Initiation request is either a payment initiation record or a failure message (code and message). If the transaction was successfully initiated, the response returns the order.id that you provided in the request. It also includes the redirect URL and unique Bank Payment transaction identifier generated by us.

{
   "order": {
        "id": "70692f734e06416eb72541d72"
    },
   "ob_trans_id": "lQBGLEiQxzQsw8clv2",
   "status": "PAYMENT_INITIATED",
   "redirect_url": "https://sandbox.globalpay-ecommerce.com/openbanking/process/lQBGLEiQxzQsw8clv2"
}

Response syntax - payment successfully initiated

Response syntax - payment initiation failed

After initiating the Bank Payment transaction, you then redirect the customer to the Bank Selection screen. The customer’s browser will be redirected to Bank Payment solution and then to our infrastructure partner Token.io (Token), who hosts the bank selection user interface (UI).

The following illustration shows the high-level flow for redirecting the customer to select a bank.

Sample redirect code

<script>
   window.location = "https://sandbox.globalpay-ecommerce.com/openbanking/process/lQBGLEiQxzQsw8clv2";
 </script>

Optional parameters for redirect URL

The browser will be redirected back to the Return URL (return_url) you specified in Step 1. The redirection will include the Bank Payment Transaction ID (ob_trans_id) as a URL parameter. At this point, you’ll need to temporarily hold the customer while you query the final status of the transaction.

Sample HTTP POST

https://www.example.com/returnUrl?ob_trans_id=lQBGLEiQxzQsw8clv2

Country

Adding ?country=XX to the web-app URL, where XX equals the two-letter ISO alpha-2 country code, pre-selects the country value in the Bank Selection screen viewed by the customer. For example:

https://sandbox.globalpay-ecommerce.com/openbanking/process/lQBGLEiQxzQsw8clv2?country=GB 

The above URL pre-selects the United Kingdom as the country. You have the option to save a default country in the initial configuration. This would be the default country, but if you include the country in the request, this will override the configuration.

Language

English is the default language, but adding ?lang=XX to the web-app URL, where XX equals the two-letter ISO 639-1 language code, specifies the language the UI appears in. For example:

https://sandbox.globalpay-ecommerce.com/openbanking/process/lQBGLEiQxzQsw8clv2?lang=DE 

The above URL sets the initial language to German (DE). The user can override this selection by clicking the language button in the top-right corner. Supported languages include English, German, Slovenian, Portuguese, Italian, French, Czech, Polish, Spanish, Hungarian, and Dutch.

After receiving a callback on return_url with the ob_trans_id parameter, you need to call the GET /payments endpoint with ob_trans_id to receive payment status. With this in mind, in the case of asynchronous payment methods, the Return URL should be treated as an interim step.

Your application may choose to hold the customer here for a few moments (for example, 5 seconds) while you call the GET /payment endpoint and wait to check if the Status URL is sent a final update. In the event of the Status URL not receiving the final status update within your determined time limit, you can display a message to the customer informing them that their order will be processed when the final status is received.

The following illustration shows the high-level flow to receive the payment status.

GET /payments endpoint

This endpoint is used to fetch the status of a transaction based on query parameters. This endpoint is also protected with a hash check. See also the More about GET /payments endpoints section below.

Sample request

How to build the request hash for payment initiation / creating a transaction

1. Hash a string made up of the request values

You can use any of the following algorithms: SHA1, SHA256, SHA384, or SHA512. We highly recommend SHA512. The blueprint of the hash for this request is below. Leave unused fields blank.

timestamp.merchantId.accountId.obTransId.startDateAndTimeStamp.endDateAndTimeStamp.returnPii

GET timestamp should be today’s date.

returnPii - Indicates if sensitive information such as destination account number, account sort code, IBAN, and account name, should be returned in the response. If set to TRUE, the data will be returned; if set to FALSE, the data will not be returned.

Below is the initial string for a request that contains timestamp, merchant_id, ob_trans_id, and returnPii. Leave unused fields blank.

20220421155117.realexprepro..WdSec0LZ80yMZzmhYK...true

2. Concatenate the hashed string with your Shared Secret with a dot(.) as a separator.

After step 1, you'll have a string that you can now concatenate with your Shared Secret. For example: secret is the Shared Secret in the below example that uses SHA512.

"2db35465d399cbd50d871ae3f90f04923e2415ef0f7801da4b82a00b29dac3419e81e24df07077c84db65dcbf43996ddd2d9625afabe0869be9dc8a9031aef66.secret"

3. Hash the concatenated string

The final string that we add to the request header should be a hash of your concatenated string, using the same algorithm as in step 1.

5cd8442eda79bb313cd3ef94ccc97e8474a27aad8ecd7fa4d7c5e59c47c89eae5cecae97e90fb3a0d68669a28aaa81d76d018ffe8a8b036f8d6a1f161121d136

If the customer drops out of the journey and redirects back to the payment page, a new payment request and a new hash will need to be created.

Inform the customer

Once you know the final status of the transaction, you can display your standard success or failure message to the customer, confirm their transaction, and complete your payment process. Or, in the case of failure, loop the customer back to try again or try another payment method.

Open Banking transactions are asynchronous, meaning that most transactions have an initial status of “Processing” with a result of “Intermediate” before receiving a “Final” result from the bank (Success/Failure). An Intermediate result might also indicate that the customer is progressing through their payment journey.

The following table describes the various API statuses and results.

In the event that the bank holds the funds for fraud or other checks, the status will remain as PROCESSING until the bank actually moves the funds (the customer will see Submitted on the UI). Once the funds have moved, Token makes a webhook call to us with the obTransId. We retrieve the current payment status from Token. After getting the current status, we will send a message to your Status URL letting you know there is an update.

The status_url is not always notified. If the status is terminal (Success/Decline/Error) when we redirect the customer to your return_url, we will not send a webhook to the status_url. The status_url is only notified when the status changes.

• For GBP/Faster Payments, the maximum wait time to return the final status is 2 hours.
• For EUR / Single Euro Payments Area (SEPA) transfers, the maximum wait time to return the final status is the same day or the next day, depending on the time of the transaction.

It’s possible to get this notification before the customer returns to the return_url. If this happens, you should proceed to do a GET to retrieve the status. A customer could have exited the browser at this stage of the journey, which could result in no update on the return_url (or they might return at a later time). Some merchants set up optional polling as an additional check to ensure that they have the latest status. We have this polling in place with the banks to ensure we retrieve the latest status from them.

You will receive a notification on the status URL (status_url in payment initiation request). It will include the Bank Payment Transaction ID (ob_trans_id) as a URL parameter.

Sample notification

https://www.example.com/notificationUrl?ob_trans_id=vBpD6WcCjZEVdr1F94

After getting a notification about a status change, you can query the API (GET /payments) to get the latest status of the transaction (see Step 3).

Sample request

The GET /payments endpoint could also be used for querying payment reports based on the parameters below. The required fields are merchantId and either ob_trans_id or startDateTime and endDateTime; if absent, a BAD-REQUEST response (400) is returned. Other fields, such as accountId or transactionState are used to add more filters to the result list. If the ob_trans_id is present, do not include the account_id, as this will result in an error.

If you send ob_trans_id, you will get back a list of one transaction. You could also pass in other optional fields as search query parameters to fetch a list of transactions meeting that search criteria. As an example, you could pass in startDateTime and endDateTime to fetch a list of transactions within a date range.

GET request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C)—dependent on another field or regional requirement.

Response syntax - GET call successfully executed

Response syntax - payment initiation failed

Customer cancel

If a customer drops out of the journey, you need to be able to return them to the payment flow. For example, the customer can click Cancel in the Bank Selection pages. This will redirect them to your response_url. Typically, you would want to show them their payment options again.

The status you receive in these situations is Payment_Not_Complete (result - 01).

Refunds are only applicable for merchants using Managed Settlement. Refunds can be initiated in the RealControl portal or via direct API integration, as shown in this section.

To initiate a refund, you must use OrderId and ob_trans_id from the initial transaction. A refund can be full or partial (up to 100% of the initial transaction amount). The merchant sets the description. Refund transactions appear as “BANK PAYMNT REFUND” on the customer’s bank account statement.

Refund transactions will generate a new ob_trans_id.

Sample request

{
    "merchant_id": "merchant x",
    "account_id": "account y",
    "request_timestamp": "20220425170039",
    "order": {
      "id": "486d636dcfc04f47a4869a336",
      "ob_trans_id": "WHV5Pit9U6TaOPod7E",
      "amount": "100",
      "description": "test refund"
    }
}

Sample response

{
    "order": {
        "currency": "GBP",
        "amount": 100,
        "id": "486d636dcfc04f47a4869a336"
    },
    "ob_trans_id": "7OekQpSR8tErZWHQn7",
    "status": "SUCCESS"
}

Refund request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field or regional requirement.

GET /refunds request

Most refunds give a SUCCESS response, but in some cases, it returns as INITIATION_PROCESSING. This is similar to a sale in which you're awaiting confirmation from the bank. If this happens, we recommend that you send a GET request to the below endpoint to retrieve the status of the transaction. Most transactions that start as INITIATION_PROCESSING are updated within 2 minutes. However, if the status doesn’t change after 2 minutes, poll the endpoint until you receive a successful response.

This endpoint can also be used to retrieve a list of refunds based on search criteria. It accepts search criteria as query parameters. The Request Syntax table below contains fields that can be used for a search. You must use obTransId or OrderId, or the startDatetime and endDateTime for the query.

Sample request

curl --location 'https://api.sandbox.globalpay-ecommerce.com/openbanking/refunds?merchantId=openbanking&accountId=TestAccount&timestamp=20230823112408&startDateTime=20221001000000&endDateTime=20221031000000' \
--header 'Authorization: SHA1 eabe1bb14697a78b7765ae7769f1c428c674973b'

//For production, remove “sandbox” from the endpoint.

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field or regional requirement.

The refund GET works based on passing the obTransId only and gives the status of a specific refund. The orderId is needed to get status of all the refund transactions (if you have many partial refunds), while obTransId can be provided to get status of specific refund transaction.

Sample response

{
    "page_number": 1,
    "record_count": 2,
    "max_page_size": 100,
    "total_number_of_records": 2,
    "refunds": [
        {
            "order_id": "989af86aa17d41ab92d608c44",
            "amount": "19",
            "currency": "GBP",
            "payment_type": "FASTERPAYMENTS",
            "created_on": "2022-10-17T11:09:15.1433333",
            "ob_trans_id": "lv2hOzOrtWLuJ4Vph1",
            "status": "SUCCESS",
            "merchant_id": "openbankingprodmgm",
            "account_id": "GPAPIManaged",
            "token_member_id": "m:26QwR7pYiMj7dmYdrpAYZyRg4LPk:5zKtXEAq",
            "token_transfer_id": "b4557601:FduuWJHpi2"
        },
        {
            "order_id": "51eeaa2433dd434faf8add7d2",
            "amount": "19",
            "currency": "GBP",
            "payment_type": "FASTERPAYMENTS",
            "created_on": "2022-10-17T11:52:01.2933333",
            "ob_trans_id": "NwRSZiXEyajngYhr8f",
            "status": "SUCCESS",
            "merchant_id": "openbankingprodmgm",
            "account_id": "GPAPIManaged",
            "token_member_id": "m:26QwR7pYiMj7dmYdrpAYZyRg4LPk:5zKtXEAq",
            "token_transfer_id": "b4557601:oC0Ux1wPEs"
        }
    ]
}

Response syntax - GET call successfully executed

Refund statuses

The following table describes the various refund statuses.

App-to-app redirection

If you offer Bank Payment on a mobile app, it’s important to seamlessly redirect from your app to the customer’s banking app, and then back to your app. To help with this, see the following developer documentation:

• Apple: Allowing apps and websites to link to your content
• Android: Handling Android App Links
• Token: App-to-App integration

How to build the request hash for GET /refunds

1. Hash a string made up of the request values

You can use any of the following algorithms: SHA1, SHA256, SHA384, or SHA512. We highly recommend SHA512. The blueprint of the hash for this request is (leave unused fields blank):

timestamp.merchantId.accountId.obTransId.orderId.startDateTime.endDateTime

For example:

20230817164543.realexprepro.openBankingHSBC..be4a8cd227954e289a5ea5b3d..

2. Concatenate the hashed string with your Shared Secret with a dot(.) as a separator

After step 1, you'll have a string that you now concatenate with your Shared Secret. For example: secret is the shared secret in the below example.

"f8632615a7640e31b72eb44dbbd9646605c5e7dc.secret"

3. Hash the concatenated string

The final string that we add to the request header should be a hash, using the same algorithm as step 1, of your concatenated string.

febc2a2dafeba4227caed8ab2a4c7a64451a954c

Final Authorization header:

SHA1 febc2a2dafeba4227caed8ab2a4c7a64451a954c

Our Bank Payment solution is available for testing in our Sandbox environment for registered users of this developer portal. For Bank Payment, we provide "test banks" instead of test cards. Each one provides a different outcome. For a table of test banks and login information, see the Bank Payment section of our Test Cards article.

Key test checklist - API

A number of key testing scenarios should be used to test Bank Payment. Each one should be done in both Production and Sandbox:

• Payment initiation request, creating a transaction, and ensuring the account is set up
• Hash working as expected
• GET latest status
• GET hash
• Completing a Successful end-to-end transaction
• Retrieving the latest status of the transaction (if the transaction flows through the status Processing)
• Customer cancels (from the Bank Selection page and from the bank). Also, if the customer exits the Confirmation page via the browser, resulting in no initial return/response_url)
• Declines and errors, testing each outcome
• Handling the customer back to your page from the customer’s bank
• App-to-app redirection

How to use our mock bank for redirects

For testing Bank Payment, we provide the fictitious bank for redirects. For a list of various amounts that correspond to different test scenarios, see our test cards for Bank Payment.

To use our mock bank, follow the steps below:

1. Select the payment amount defined for the expected scenario. For example, if you select 104 GBP in the payment initiation call, you will receive FAILURE_PERMISSION_DENIED as a final status.
   
   1. The amount would be £104, not £1.04.
   2. This works for GBP and EUR.
2. For the redirect, select the applicable mock bank as shown below. Type “mock” in the search box to find them quickly.
   Note: The "Mock One-Step Redirect Bank" option moves funds instantly without redirecting the customer.
   
   
3. Accept consent and get redirected back to the merchant. The mock bank does not have a front-end or bank UI.
4. The UI will reflect the “Transitions through X” in the table in Test Cards. For example: PROCESSING in the back end will show as Submitted on the customer’s UI.

Our Postman collection for Bank Payment is available for downloading as a JSON file. You can use this collection to test transactions via the XML API.

The zip file below contains the following files:

• open-banking.postman_22Jul2024.json.zip

To download the collection (.zip file), click the button below: