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.