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

STEP 1 - Initiate

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 A unique, alphanumeric maximum 32 char length user identifier generated at merchant's side (To identify a user uniquely)
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 Either pass a dynamic URL to obtain the UI control back at the end of the bank page process or use a static URL(supplied as part of account configuration setup).
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

STEP 2 - 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' to hand UI control back to you. Please note the 'uicReturn' 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.

STEP 3 - Notification

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)
  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.

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