For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Open Banking - Guide

Learn how to let customers pay using their bank account

In this guide, you’ll learn how to process a transaction with the Bank Payment payment method via direct API integration or Hosted Fields using our Open Banking infrastructure.

For more information about Open Banking, see our Overview.

Prerequisites

Before starting the steps in this guide, you must do the following:

Step 1: Initiate the payment

First, we submit a mandatory request to initiate an Open Banking transaction. It needs to include the transaction’s core parameters so that we have enough information to create the payment with our technology partner and the customer’s bank.

A successful transaction request will return a unique transaction identifier TRN_ID and a redirect URL, which you’ll use to facilitate the customer confirmation of the transaction Step 2.

At a high level, initiating an Open Banking transaction works like this:

Diagram flow between the customer, merchant, and our API to initiate an Open Banking transaction

The first step is to create a transaction using the Initiate call. This will specify the amount, currency, and data elements needed to process an Open Banking transaction.

Where the payment.scheme is FASTER PAYMENTS, the available payment_method fields (the destination bank account fields) will be:

payment_method.bank_transfer.account_number
payment_method.bank_transfer.bank.code
payment_method.bank_transfer.bank.name

Where the payment.scheme is SEPA, the available payment.destination fields will be:

payment_method.bank_transfer.iban
name

Sample request

Request syntax

Name	Format	Type	Description
channel	string	M	Describes whether the transaction was processed in a customer present (CP) or customer not present (CNP) scenario. Must always be CNP for Open Banking.
type	string	M	Describes whether the transaction is a SALE or REFUND. SALE indicates the movement of funds (or attempt to) from payer to merchant. REFUND indicates the movement of funds (or attempt to) from merchant to payer.
reference	string	O	Information that some banks may record and display on the account of the customer or merchant.
payment_method
name	string	M	Name of the payer.
bank_transfer
account_number	string	C	Number of the destination account where the funds will be transferred to. Optional for Direct Settlement transactions (if not saved during boarding with us) and if the method type is FASTERPAYMENTS.
bank.code	string	C	Sort code of the destination account. Optional for Direct Settlement transactions (if not saved during boarding with us) and if the method type is FASTERPAYMENTS.
iban	string	C	International Bank Account Number (IBAN) of the destination account. Optional for Direct Settlement transactions (if not saved during boarding with us ) and if the method type is SEPA.
remittance_reference
type	string	M	Type of remittance reference. Allowed values: TEXT
value	string	M	If type is TEXT: a description for the transaction. Most banks will record and display this reference on the customer’s account. For Direct Settlement, it will also show on the customer’s bank statement when the funds are received. If type is PAN: allows the cardholder’s Primary Account Number (PAN) to be securely passed depending on the merchant use case.
bank
name	string	M	Name of the merchant. Underscore character [ _ ] not permitted. Spaces are allowed, and acceptable special characters are -. ,'’‘`()*&@/.

Step 2: Redirect the customer

Once the transaction is initiated, the customer must be redirected to the Open Banking checkout flow using the URL returned in the Initiate response to facilitate authorization and authentication. To do this, use a simple JavaScript redirect or HTTP GET (302 redirect).

At a high level, redirecting the customer works like this:

Diagram flow between the customer, merchant, and our API to redirect the customer

In our example, we redirect the customer to the URL returned in the Initiate response using JavaScript.

<script>
window.location = "https://apis.sandbox.globalpay.com/ucp/postback/transactions/TRN_IDhttps://apis.globalpay.com/ucp/postback/transactions/TRN_CJtYAlPtbhbikIfcZCNTy3CVCBwfUK_sdgpoh123456/redirect/eyJtbWEiOm51bGwsIm1pZCI6Ik1FUl80M2Q1YzdiOThmZTQ0ZDhjODBkOTE1YzY0MjJlODNlZSIsInhnIjoiMjAyMS0wMy0yMiJ9";
</script>

Step 3: Handle the redirect and check the status

Once the customer completes the transaction with the Open Banking provider, they are redirected back to your app or website based on transaction success/failure using the Return URL specified in the Initiate request.

The unique transaction identifier is also returned as part of the parameters in the URL. You should use this to check the status of the payment (see Step 4).

The ID that is passed as a URL parameter is the TRN_ID and should be used to check the status of the transaction (see example below).

Sample Return URL parameters

https://www.example.com/return?X-GP-Signature=399af8063773573040b3d1e76ccf313ed40491e61b3fe768390d7a1da925506c3908405f17be8fb82b978ab4790f76cdeb7b292b48dce716903c36eab57580a9&id=TRN_U5cRgH1nfubpsDSlrM67iz8hNj7cF9_sdgpoh123456&payer_reference=asdgpoh123456&action_type=REDIRECT_FROM&action_id=ACT_J8pXg8cjUuOltUHovOAGpqUooy7XZD

Checking the signature

For information on how to validate a webhook notification message and its sender, see Validating Webhook Notifications.

The Return URL contains a signature made up of the key transaction fields. This includes the Transaction ID (TRN_ID), Payer Reference, Action Type, and Action ID. Your application must construct and check the signature to ensure the response wasn’t tampered with.

To construct the signature, take the string containing the above fields from the Return URL, excluding the signature itself.

id=TRN_U5cRgH1nfubpsDSlrM67iz8hNj7cF9_sdgpoh123456&payer_reference=asdgpoh123456&action_type=REDIRECT_FROM&action_id=ACT_J8pXg8cjUuOltUHovOAGpqUooy7XZD

Concatenate your app key to the end of this string.

id=TRN_U5cRgH1nfubpsDSlrM67iz8hNj7cF9_sdgpoh123456&payer_reference=asdgpoh123456&action_type=REDIRECT_FROM&action_id=ACT_J8pXg8cjUuOltUHovOAGpqUooy7XZD.app_key

The signature should be a Sha512 hash of the concatenated string. For example:

399af8063773573040b3d1e76ccf313ed40491e61b3fe768390d7a1da925506c3908405f17be8fb82b978ab4790f76cdeb7b292b48dce716903c36eab57580a9

Step 4: Get transaction status

In this step, we get the transaction details and receive the webhook notification. As mentioned previously, the TRN_ID field should be used to check the status of the transaction.

At a high level, getting the transaction status works like this:

Diagram flow between the customer, merchant, and our API to get the transaction status.

Sample request

The following sample is for the GET request.

Step 5: Refund a Transaction

Once a transaction is captured and the funds are deducted from the customer’s account, you can refund the full or partial amount back to them. When using Open Banking, refunds can only be used if you are using Managed Settlement as your settlement option.

To initiate a refund, you must use the TRN\_ID ( TRN\_U5cRgH1nfubpsDSlrM67iz8hNj7cF9\_sdgpoh ) from the initial transaction. A refund can be full or partial (up to 100% of the initial transaction amount). Refund transactions appear as “BANK PAYMENT REFUND” on the customer’s bank account statement. Refund transactions will generate a new TRN\_ID ( TRN\_k0ljUGPtITG0dN4gfAh4Qh86hRYMtj\_sdgpoh ).

Request

curl --location --request POST  'https://{{url}}/ucp/transactions/{{trn_id}}/refund' \
--header 'Accept: application/json' \
--header 'x-gp-version: 2021-03-22' \
--header 'Authorization: Bearer pJ2An7thGclc8UUVZSntPRmsAUrR' 
--header 'Content-Type: application/json' \

Response

{
  "id": "TRN_k0ljUGPtITG0dN4gfAh4Qh86hRYMtj_sdgpoh",
  "time_created": "2024-10-03T10:33:52.003Z",
  "type": "REFUND",
  "status": "CAPTURED",
  "amount": "1999",
  "currency": "GBP",
  "country": "GB",
  "reference": "sdgpoh",
  "payment_method": {
    "message": "INITIATION_PROCESSING",
    "apm": {
      "provider": "open_banking"
    },
    "bank_transfer": {
      "bank": {}
    }
  },
  "action": {
    "id": "ACT_k0ljUGPtITG0dN4gfAh4Qh86hRYMtj",
    "type": "REFUND",
    "time_created": "2024-10-03T10:33:52.003Z",
    "result_code": "SUCCESS",
    "app_id": "T6og1tbECpHFeO104qUM383oq5bOJ12r",
    "app_name": "Postman_Collection_Test"
  }
}

Step 6: Get Refund Status

Refunds are usually successful and are given CAPTURED as the status in the response. Sometimes PENDING is returned indicating that the bank is carrying out some additional checks before refunding the funds. If this happens, we recommend that you send a Get transaction status request using the trn\_id generated in the response as outlined in step 4 above.

Request

curl --location --request GET 'https://{{url}}/ucp/transactions/TRN_k0ljUGPtITG0dN4gfAh4Qh86hRYMtj_sdgpoh’ \
--header 'Accept: application/json' \
--header 'x-gp-version: 2021-03-22' \
--header 'Authorization: Bearer pJ2An7thGclc8UUVZSntPRmsAUrR' 
--header 'Content-Type: application/json' \

Response

{
    "id": "TRN_qkDsyzid0HciYULvwLuSB6AAIomxqz_99977641",
    "time_created": "2025-03-28T11:24:19.982Z",
    "time_last_updated": "2025-03-28T11:24:19.982Z",
    "status": "CAPTURED",
    "type": "REFUND",
    "merchant_id": "MER_c5d37eaf0e3841e083c232b2318af55c",
    "merchant_name": "Sandbox_Merchant_4",
    "account_id": "TRA_55cf70132893425c9e950b7254ca0a64",
    "account_name": "transaction_processing_ob",
    "channel": "CNP",
    "amount": "",
    "merchant_amount": "",
    "partner_amount": "",
    "gratuity_amount": "",
    "surcharge_amount": "",
    "surcharge_type": "",
    "currency": "GBP",
    "reference": "99977641",
    "description": "",
    "order_reference": "",
    "order": {
        "reference": ""
    },
    "time_created_reference": "",
    "batch_id": "",
    "initiator": "",
    "country": "GB",
    "language": "",
    "ip_address": "165.225.199.17",
    "site_reference": "",
    "payment_method": {
        "result": "",
        "message": "INITIATION_FAILED",
        "entry_mode": "ECOM",
        "name": "Jane Doe",
        "redirect_url": "https://apis.sandbox.globalpay.com/ucp/postback/transactions/TRN_W7P6Laro8zZDcWEfoL4wAazsN8q2rf_99977641/redirect/eyJtbWEiOm51bGwsIm1pZCI6Ik1FUl9jNWQzN2VhZjBlMzg0MWUwODNjMjMyYjIzMThhZjU1YyIsInhnIjoiMjAyMS0wMy0yMiJ9",
        "apm": {
            "provider": "open_banking",
            "countries": [
                "GB"
            ]
        },
        "bank_transfer": {
            "remittance_reference": {
                "type": "TEXT",
                "value": "Nike Bounce Shoes"
            }
        }
    },
    "installment": {
        "id": "",
        "program": "",
        "terms": {
            "id": "",
            "time_unit": "",
            "time_unit_number": "",
            "interest_rate": "",
            "first_amount": "",
            "subsequent_amount": "",
            "last_amount": "",
            "total_amount": "",
            "reference": "",
            "mode": "",
            "total_time_unit_count": "",
            "time_unit_amount": "",
            "currency": "",
            "description": "",
            "expiration_date": "",
            "expiration_interest_rate": "",
            "terms_and_conditions_url": ""
        },
        "mode": "",
        "count": "",
        "grace_period_count": ""
    },
    "action_create_id": "ACT_qkDsyzid0HciYULvwLuSB6AAIomxqz",
    "parent_resource_id": "TRN_W7P6Laro8zZDcWEfoL4wAazsN8q2rf_99977641",
    "system": {
        "mid": "123456789",
        "tid": "0149210014212599819744106286698950319218",
        "name": "ecomtest1"
    },
    "action": {
        "id": "ACT_akm3Mb8ud6S6voi2K7a1ZHRJ1gfFTx",
        "type": "TRANSACTION_SINGLE",
        "time_created": "2024-10-03T11:24:35.730Z",
        "result_code": "SUCCESS",
        "app_id": "T6og1tbECpHFeO104qUM383oq5bOJ12r",
        "app_name": "Postman_Collection_Test"
    }
}

Testing Open Banking

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

Open Banking - Guide | Global Payments