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:
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
- Progress update status notification (PSN)
- 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 |