This guide will walk developers through the integration process for the server-to-server connection from HydrogenPay. The integration involves several API calls, each with a specific purpose within the payment flow.
Before starting, ensure you have the necessary credentials such as the authorization token and apiRequesKey. Authorization token should be used as Bearer Token and apiRequestKey as Header for all end endpoints except Generate Client Key.
Generate Client Key
Generates an apiRequestKey, clientIV and clientKey for secure communication with other endpoints.
METHOD: GET
Test URL: https://qa-api.hydrogenpay.com/bepayment/api/v2/Payment/generate-aggregator-client-keys
Live URL: https://api.hydrogenpay.com/bepayment/api/v2/Payment/generate-aggregator-client-keys
Authorization token should be used as Bearer Token for this endpoint.
Sample Response:
{
"statusCode": "90000",
"message": null,
"data": {
"merchantRef": "30013606",
"apiRequestKey": "617602DFEF417A1C00338E37534F002DC5F433490148696B13D193EC5917345D",
"clientIV": "4betVRpFIVwvbNLJwMszew==",
"clientKey": "NBiPLxlq0WWInT4Hob+glw=="
}
}
The clientIV and clientKey from this response are required to encrypt customer card details.
Purchase
Initiates a payment request to the customer.
METHOD: POST
Test URL: https://qa-api.hydrogenpay.com/bepayment/api/v2/Payment/purchase
Live URL: https://api.hydrogenpay.com/bepayment/api/v2/Payment/purchase
Sample Request
{
"transactionRef": "1164vy3279",
"customerId": "abc",
"amount": "10",
"currency": "NGN",
"ipAddress": "1.0.0.1",
"callbackUrl": "https://hydrogenpay.com",
"cardDetails": "encrypted_card_details",
"deviceInformation": {
"httpBrowserLanguage": "en-US",
"httpBrowserJavaEnabled": false,
"httpBrowserJavaScriptEnabled": true,
"httpBrowserColorDepth": "24",
"httpBrowserScreenHeight": "820",
"httpBrowserScreenWidth": "360",
"httpBrowserTimeDifference": "05",
"userAgentBrowserValue": "Mozilla/5.0 (Linux; Android 12; Infinix X6819) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Mobile Safari/537.36",
"deviceChannel": "browser"
}
}
Sample Response
{
"statusCode": "90000",
"message": "Kindly enter the OTP sent to 234805***1111",
"data": {
"referenceInformationCode": "2347063908100_9005692230",
"responseCode": "H01",
"amount": "10",
"transactionRef": "213435954663455",
"submitTimeUtc": "Jan 23rd 2024 | 03:14pm",
"transactionId": "50b80000-ca5e-b678-323c-08dc1c260fe4",
"transactionId3DSecure": "474512713"
}
}
Purchase Call Parameters
| Parameter | Type | Description |
|---|---|---|
| transactionRef | String | Unique reference for the transaction. |
| customerId | String | Unique identifier for the customer. |
| amount | String | Amount to be charged. |
| currency | String | Currency for the transaction, e.g., NGN. |
| ipAddress | String | IP address of the customer. |
| callbackUrl | String | URL to redirect after transaction. |
| cardDetails | String | Encrypted card details. |
| deviceInformation | Object | Information about the customer's device. |
| httpBrowserLanguage | String | Browser language, e.g., en-US. |
| httpBrowserJavaEnabled | Boolean | Indicates if Java is enabled in the browser. |
| httpBrowserJavaScriptEnabled | Boolean | Indicates if JavaScript is enabled in the browser. |
| httpBrowserColorDepth | String | Color depth of the browser, e.g., 24. |
| httpBrowserScreenHeight | String | Screen height of the browser, e.g., 820. |
| httpBrowserScreenWidth | String | Screen width of the browser, e.g., 360. |
| httpBrowserTimeDifference | String | Time difference of the browser, e.g., 05. |
| userAgentBrowserValue | String | User agent of the browser. |
| deviceChannel | String | Device channel, e.g., browser. |
Validate OTP
Validates the OTP when the purchase call response code is H01.
METHOD: POST
Test URL: https://qa-api.hydrogenpay.com/bepayment/api/v2/Payment/validate-otp
Live URL: https://api.hydrogenpay.com/bepayment/api/v2/Payment/validate-otp
Sample Request
{
"otp": "123456",
"transactionRef": "213435954663455"
}
Sample Response
{
"statusCode": "90000",
"message": "Operation Successful",
"data": {
"amount": "789.00",
"transactionIdentifier": "FBN|API|MX102560|25-07-2023|474512713|693990",
"message": "Approved by Financial Institution",
"transactionRef": "503021992595_99550f9c94",
"responseCode": "00"
}
}
Validate OTP Parameters
| Parameter | Type | Description |
|---|---|---|
| otp | String | One-time password received by the customer. |
| transactionRef | String | Unique reference for the transaction. |
Resend OTP
Used when OTP fails to deliver.
METHOD: POST
Test URL: https://qa-api.hydrogenpay.com/bepayment/api/v2/Payment/resend-otp
Live URL: https://api.hydrogenpay.com/bepayment/api/v2/Payment/resend-otp
Sample Request
{
"transactionRef": "213435954663455",
"amount": "10"
}
Sample Response
{
"statusCode": "90000",
"message": "Operation Successful",
"data": {
"responseCode": "T0",
"amount": "789.00",
"message": "Kindly enter the OTP sent to 234805***1111",
"transactionRef": "2347063908100_64104d8fb4",
"supportMessage": "Didn't get the OTP? Dial *723*0# on your phone (MTN,Etisalat,Airtel) Glo,use *805*0#."
}
}
Resend OTP Parameters
| Parameter | Type | Description |
|---|---|---|
| transactionRef | String | Unique reference for the transaction. |
| amount | String | Amount to be charged. |
Confirm Status
Confirms the status of transactions.
METHOD: POST
Test URL: <https://qa-api.hydrogenpay.com/bepayment/api/v2/Payment/confirm-status
Live URL: https://api.hydrogenpay.com/bepayment/api/v2/Payment/confirm-status
Sample Request
{
"transactionRef": "21343554663456"
}
Sample Response
{
"statusCode": "90000",
"message": "Successful transaction.",
"data": {
"responseCode": "0000",
"responseDescription": "Approved by Financial Institution",
"transactionReference": "2347063908100_60829750d6",
"amount": 1000,
"remittanceAmount": 0,
"submitTimeUtc
": "2023-10-30T12:15:21",
"completedTimeUtc": "Oct 30th 2023 | 11:15am",
"maskedPan": "506099*********7499",
"cardExpiry": "jXLGNL6Jz9iMIFwhQrsdWQ==",
"transactionId": "1b790000-0e6d-7e99-7429-08dbd939808b",
"errors": []
}
}
Confirm Status Parameters
| Parameter | Type | Description |
|---|---|---|
| transactionRef | String | Unique reference for the transaction. |
Endpoint Flow
Based on the response code from the purchase call, the payment flow varies:
- H01: OTP Page → Purchase → Validate OTP → Confirm Status
- H21 (Local Cards): Bank's Page (3D Secure) → Purchase → Redirect to Bank's 3DS Page → Validate 3D Secure → Confirm Status
- H51 (International Cards): Bank's Page (3D Secure) → Purchase → Billing Information → Redirect to Bank's 3DS Page → Validate 3D Secure → Confirm Status
The above guide can help developers easily integrate the HydrogenPay server-to-server into their applications, enabling secure and efficient payment processing for their customers.