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. API Key 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 3D Secure authentication on the bank's page. |
| H51 | The transaction requires 3D Secure authentication. |
Generate Client Key
Generates an apiRequestKey, clientIV and clientKey for secure communication with other endpoints.
METHOD: GET
Live URL: https://api.hydrogenpay.com/bepay/api/v2/Payment/generate-aggregator-client-keys
API Key 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
Live URL: https://api.hydrogenpay.com/bepay/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
Live URL: https://api.hydrogenpay.com/bepay/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
Live URL: https://api.hydrogenpay.com/bepay/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
Live URL: https://api.hydrogenpay.com/bepay/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. |
Validate 3D Secure
Validates 3D Secure when the purchase call response code is H51.
METHOD: POST
Live URL: https://api.hydrogenpay.com/bepay/api/v2/Payment/validate-3dsecure
Sample Request
{
"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"
}
}
Billing Information
Process billing information for 3D Secure if response code is H51.
METHOD: POST
Live URL: https://api.hydrogenpay.com/bepay/api/v2/Payment/validate-3dsecure
Sample Request
{
"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"
}
}
Endpoint Flow
Based on the response code from the purchase call, the payment flow varies:
For Response Code H01 (OTP Authentication Required)
- After initiating the purchase call, if the system returns the H01 response code, the user will be directed to an OTP (One-Time Password) page.
- On the OTP page, the user inputs the OTP they receive.
- The OTP is then validated via a separate call.
- Once the OTP is confirmed as valid, the payment status is updated to reflect the success or failure of the transaction.
For Response Code H21 (Local Cards - 3D Secure Required)
- If the H21 response code is returned, indicating a local card that requires 3D Secure authentication, the user will be redirected to the issuing bank's 3D Secure page.
- The purchase call takes place and the user is redirected to the bank’s 3D Secure page for verification
- After completing 3D Secure authentication, the system validates the 3D Secure response from the bank.
- Finally, the payment status is updated to reflect the status of the transaction.
For Response Code H51 (International Cards - 3D Secure with Billing Information)
- When an H51 response code is returned, the flow starts by collecting additional billing information from the user.
- After entering the required billing details, the purchase call is initiated.
- Next, the user is redirected to the issuing bank's 3D Secure page for authentication.
- Once the 3D Secure process is completed and the bank's response is validated, the system updates the payment status based on the outcome.
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.