NAV
shell java ruby python

Introduction

Open Banking is an initiative regulated by the FCA and their European equivalents and designed to bring more competition and innovation to financial services. Enabled by European PSD2 regulation and driven by governments across the EU to open up the financial services sector, Open Banking creates a new, frictionless way to pay. Under the framework, UK and EU banks have created open interfaces ( APIs ) into previously locked customer accounts and payment systems. GlobalCharge has refined and reduced the complexity of accessing the Open Banking network thorugh a single API integration. This document details the 2 simple integration steps required to integrate with our system empowering online merchants to offer Open Banking as a new payment mechanism to end users.

Diagram:

alt text

alt text

Initiate In-Payment

STEP 1 Request:

Example will be provided soon
Example will be provided soon
# With shell, use below curl example
curl -i -X GET 'https://stg-ob.globalcharge.com/bi/ext/initiate?merchantId=12345&countryCode=GB&merchantTransactionReference=ABC123&pricePoint=1&executionType=IMMEDIATE&executionDate=2021-04-29&productName=ExampleProductName&hash=7GABCDEABCDEF3BABCDEF3E'

curl -i -X POST -H "Content-Type: application/json" -d '{ "merchantId":"12345", "countryCode":"GB", "merchantTransactionReference":"ABC123", "pricePoint":"1", "executionType"-:"IMMEDIATE", "executionDate":"2021-04-29", "productName":"ExampleProductName", "hash":"7GABCDEABCDEF3BABCDEF3E"}' 'https://stg-ob.globalcharge.com/bi/ext/initiate'
Example will be provided soon

Be sure to replace all the dummy values.

API PATH: /bi/ext/initiate

METHOD: GET POST

Connect to our Open Banking billing system through a single API endpoint allowing end users to make payments. You can initiate a transaction by calling our endpoint using a GET or POST method. When using a POST call to this API you will receive an HTTP response code 200 with a response body containing the redirection url where the end user needs to be redirected. If you perform a GET call from a browser on this API all the redirections will happen automatically.

Request Parameter:

Parameter Mandatory Type Demo Value Description
merchantId true Number 1234 Unique identifier for a merchant configured at GlobalCharge's side.
countryCode true String GB ISO country code from where the payment originated. We accept Only alpha-2 ISO code, ISO COUNTRY CODE LIST
merchantTransactionReference true String A23DSS A unique, alphanumeric maximum 32 char length transaction identifier generated at merchant's side (returned back in notifications)
merchantUserId true String U23DSS Unique alphanumeric identifier generated by the merchant to identify a user. This could be an email, a hashed value, or any other unique reference used by the merchant to track users.
pricePoint true Double 1.00 Amount to be charged. The value to be charged is set to a maximum of 2 decimal places.
executionType true String IMMEDIATE Possible values: IMMEDIATE, PERIODIC, SCHEDULED
productName true String Digital coin Content/Product title to be displayed to the End User on purchase and payment screens.
executionDate true Date 2021-04-25 Format YYYY-MM-DD. This field is mandatory with a valid date (present/future) in the request in all scenarios. The value of this field is not used when the execution type is 'IMMEDIATE'.
uicReturn false String http://merchants-landing-page.com URL where the user is redirected after the bank process is completed. Can be dynamic or a pre-configured static URL.
uicCancel false String http://merchants-cancel-page.com URL where the user is redirected if they cancel the payment process. If not provided, uicReturn will be used as the fallback.
uicNotification false String http://merchants-server-not.com Either pass a dynamic URL to receive FSN callback, or use a static URL(supplied as part of account configuration setup).
passthrough false String abcdefgh123 Custom parameter that will be included in the notification callback.
hash true String A23DSS Hash - Unique hash. Details to generate this hash will be provided in a seperate Technical Requirements doc.

GET Response:

CODE Description
302 Request was accepted. User will be redirected automatically if request was initiated from a standard browser.
400 Bad request, Parameters are missing or invalid. Contact ob@globalcharge.com

POST Response:

STEP 1 Response(POST):

{
  "accepted": true,
  "message": "One-time redirect url generated",
  "redirectPath": "https://stg-ob.globalcharge.com/bi/ext/redirect_to_***/eyJhbGciOiJIUzI1NiJ**y*****Im8Wy",
  "data": null
}
CODE Description
200 Request was accepted. Redirect end-user to generated redirect path.
400 Bad request, Parameters are missing or invalid. Contact ob@globalcharge.com

UI control back

STEP 2 Return UI Control:

Example will be provided soon
Example will be provided soon
# With shell, use below curl example
curl -i -X GET 'https://your-site-domain.com/return_control?merchantTransactionReference=ABC123&gc_ref=WSGDF2535'
Example will be provided soon

When the user's bank page journey is completed, GC will use the 'uicReturn/uicCancel' to hand UI control back to you. Please note the 'uicReturn/uicCancel' parameter value will overwrite the static configured URL in the account configuration. We will append some transaction references to help you identify this control call back on your side - see table below. Notice the example URL pattern contained in sample section on the right.

Request Parameter

Parameter Mandatory Type Demo Value Description
merchantTransactionReference true String A23DSS This was passed by you with /bi/ext/initiate API
transactionId true String DKHDK66 GlobalCharge transaction reference.

Notifications

STEP 3 FSN Pattern: ruby Example will be provided soon

Example will be provided soon
# With shell, use below curl example
curl -i -X POST -H "Content-Type: application/json" -d '{ "status":"status", "transactionId":"WEB8433RQPCIMQLCBP", "merchantTransactionReference":"string", "countryCode":"GB", "pricePoint":1 }' 'http://your-notification-end-point.com/receive_notification'
Example will be provided soon

STEP 3 PSN Pattern: ruby Example will be provided soon

Example will be provided soon
# With shell, use below curl example
curl -i -X POST -H "Content-Type: application/json" -d '{ "status":"status", "transactionId":"WEB8433RQPCIMQLCBP", "merchantTransactionReference":"string", "countryCode":"GB", "pricePoint":1 }' 'http://your-notification-end-point.com/receive_notification'
Example will be provided soon

We will generate 2 types of notifications

  1. Progress update status notification (PSN) - In Payments Only
  2. Final status notification (FSN)

The PSN informs you of the real-time status of the transaction. The PSN can be used for analysis purposes to track a user's journey. The FSN is the final and last transaction status update. Your content delivery decision should be based on the status of the FSN. These notifications will be server to server, sent to your end point (configured during set up) using an HTTP POST call. We expect a '200' HTTP response code receipt confirmation, if this is not received we will resend the notification according to our retry policy.

Parameters

Parameter Mandatory Type Demo Value Description
status true ENUM BILLED Status of a transaction. Possible values are BILLED, NOT_PROCEEDED, FAILED, PENDING, SETTLED- See Appendix.
merchantTransactionReference true String A23DSS Passed by you with /bi/ext/initiate API.
transactionId true String DKHDK66 GlobalCharge transaction reference.
countryCode true String GB ISO country code from where the payment originated.
pricePoint true String 1.00 Billed value.
hash true String A23DSS Unique hash. Details will be provided through external communication with our tech team.

Initiate Out-Payment

STEP 1 Request:

Example will be provided soon
Example will be provided soon
# With shell, use below curl example

curl --location 'https://ob.globalcharge.com/ext/payout' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "merchantId": 12345, "countryCode": "DE", "merchantTransactionReference": "TXN123456789", "pricePoint": 300, "executionType": "PAYOUT", "executionDate": "2025-02-10", "hash": "1d787700f6701edd56d3d1c3f1d35698fbed0fa725f657a0f1b077a1e5c0c5db8fa71e6068fbd2f60134b176fb268579bfe48556114a32d70fbd6820e18f96db", "uicNotification": "notification.com", "accountId":"I12345", "merchantUserId": "user_001", "creditor": { "name": "John Doe", "addressLines": "Adress", "accountNumber": "12345678", "city": "Berlin", "postCode": "10001", "bankClearingSystemId": "KK00000", "bankName": "Bank" } }'

Be sure to replace all the dummy values.

API PATH: /ext/payout

METHOD: POST

Connect to our Open Banking payout system through a single API endpoint, allowing you to send funds directly to end users. You can initiate a payout transaction by calling our endpoint using either a POST method. When using a POST call, you will receive an HTTP 200 response followed by a notification if request was accepted.

Authentication

All requests must include Basic Authentication header: Authorization: Basic base64(username:password)

Request Parameter:

Parameter Mandatory Type Demo Value Description
merchantId true Number 1234 Unique identifier for a merchant configured at GlobalCharge's side.
countryCode true String GB ISO country code where the payout is sent. (Determines the currency of the transfer - local currency) We accept Only alpha-2 ISO code, ISO COUNTRY CODE LIST
merchantTransactionReference true String A23DSS A unique, alphanumeric maximum 32 char length transaction identifier generated at merchant's side (returned back in notifications)
merchantUserId true String U23DSS Unique alphanumeric identifier generated by the merchant to identify a user. This could be an email, a hashed value, or any other unique reference used by the merchant to track users.
pricePoint true Double 1.00 Amount to be sent. The value to be sent is set to a maximum of 2 decimal places.
executionType true String PAYOUT Possible values: PAYOUT
executionDate true Date 2021-04-25 Format YYYY-MM-DD. This field is mandatory with a valid date (present/future) in the request in all scenarios. The value of this field is not used when the execution type is 'PAYOUT'.
hash true String A23DSS Hash - Unique hash. Details to generate this hash will be provided in a seperate Technical Requirements doc.
accountId true String A23DSS Provided by GlobalCharge at the time of account set up.
uicNotification false String http://merchants-server-not.com Either pass a dynamic URL to receive FSN callback, or provide a static URL(To be supplied as part of account configuration setup).
creditor true object Creditors/Recipients details, see below for more details

Creditor Object:

Parameter Mandatory Type Demo Value Description
name true String John Doe Name of the recipient.
addressLines true String 123 JohnDoe Street Address of the recipient.
city true String City of JohnDoe City of receipient.
postCode true String 11AB Post code of recipient.
bankName true String Revolut Bank name of recipient.
accountNumber true String A23DSS Receipients account identification. (IBAN, ACCOUNT NUMBER).
bankClearingSystemId Conditional String KK123ABC Bank’s clearing system ID required for countryCode 'IN' or 'GB'. For GB provide SORT CODE.
type true String private private or orgnaization. If creditor is a individual with full name use private. If creditor is business/organization use organization.

POST Response:

STEP 1 Response:

{
  "accepted": true
}
CODE Description
200 accepted = true - Await FSN notification, accepted = false - Request will not be processed
400 Bad request, Parameters are missing or invalid. Contact ob@globalcharge.com

Notifications

FSN Pattern: ruby Example will be provided soon

Example will be provided soon
# With shell, use below curl example
curl -i -X POST -H "Content-Type: application/json" -d '{ "status":"status", "transactionId":"WEB8433RQPCIMQLCBP", "merchantTransactionReference":"string", "countryCode":"GB", "pricePoint":1 }' 'http://your-notification-end-point.com/receive_notification'
Example will be provided soon

The FSN is the confirmation of the payout completition. The notification will be server to server, sent to your end point (configured during set up/sent in request) using an HTTP POST call. We expect a '200' HTTP response code receipt confirmation, if this is not received we will resend the notification according to our retry policy.

Parameters

Parameter Mandatory Type Demo Value Description
status true ENUM COMPLETED Status of a request. COMPLETED / FAILED
merchantTransactionReference true String A23DSS Passed by you with /ext/payout API.
transactionId true String DKHDK66 GlobalCharge transaction reference.
countryCode true String GB ISO country code from where the payment originated.
pricePoint true String 1.00 Payout value.
hash true String A23DSS Unique hash. Details will be provided through external communication with our tech team.

APPENDIX

FSN STATUS

Status Meaning
BILLED Payment was succesfully completed.
NOT_PROCEEDED Failure before attempting payment.
FAILED Payment was not completed.
PENDING Payment process is in a PENDING state, we are checking the status with the bank in the background and once updated another notification will be sent with BILLED or FAILED.
SETTLED Payment processed and received by beneficiary bank account. (Optional & Dependant on AIS access to beneficiary bank account)

PSN STATUS

Status Meaning
REDIRECTED User is redirected to Bank's page successfully.
AUTH_COMPLETED User completed the authentication process on bank's page and redirected back to GC.
TRANSACTION_COMPLETED Transaction has completed. we are checking the status with the bank in the background and you must receive a FSN.

Execution Type

Status Meaning
IMMEDIATE Payment will be executed as soon as the request is received.
PERIODIC Subscription based payments, NOT SUPPORTED YET
SCHEDULED Will be executed on the date provided, execution date should a future date. NOT SUPPORTED YET