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.
Response Code
Code | Description |
---|---|
0000 | Transaction was successful and approved by the financial institution. |
H01 | User is required to enter the OTP (One-Time Password) sent to their phone to complete the transaction. |
H21 | The transaction involves a local card and requires 3D Secure authentication on the bank's page. The user is redirected to the bank’s 3DS page to validate the transaction. |
H51 | The transaction involves an international card and requires 3D Secure authentication. The user must provide billing information and then is redirected to the bank’s 3DS page for validation. |
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
respo
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.