Initiate Transfer is an endpoint designed to return dynamic virtual account details for completing payment transactions. This operation collects important information, including the amount, currency, and customer details, to create a transfer request.
Users or customers can use this request to generate virtual account details, facilitating the completion of payments through bank transfers. The dynamic nature of these virtual accounts means that they automatically expire after 30 minutes, ensuring enhanced security and reducing the risk of unauthorized usage.
Request
METHOD: POST
Test URL: https://qa-dev.hydrogenpay.com/qa/bepayment/api/v1/Merchant/initiate-bank-transfer
Live URL: https://api.hydrogenpay.com/bepayment/api/v1/Merchant/initiate-bank-transfer
Request Parameters
| Mandatory | Type | Name | Description |
|---|---|---|---|
| Yes | Decimal | amount | Amount to debit the customer. |
| Yes | Customer’s Email Address. | ||
| Yes | String | customerName | Customer's name. |
| No | String | currency | Default to NGN if not passed, other currencies available are USD and GBP. |
| No | String | description | Payment Description. |
| No | String | meta | Contains any other information you want to be recorded with the transaction. |
| No | String | transactionRef | Unique transaction reference for the transfer. It will be automatically generated if not specified. |
| Yes | String | callback | Redirect URL after the transfer has been completed on the gateway. |
Success Response
| Field | Type | Value |
|---|---|---|
| statusCode | Integer | 90000 |
| message | String | Initiate bank transfer successful |
| transactionRef | String | Transaction Client Reference |
| virtualAccountNo | String | Dynamic virtual account number |
| virtualAccountName | String | Name associated with the virtual account |
| expiryDateTime | String | Expiry date and time for the virtual account with default being 30 minutes. |
| capturedDatetime | String | Time when the payment was captured (null if not captured) |
| completedDatetime | String | Time when the payment was completed (null if not completed) |
| transactionStatus | String | Current status of the transaction |
| amountPaid | Decimal | Amount paid |
| bankName | String | Bank name associated with the virtual account |
Missing Callback Response
| Field | Type | Value |
|---|---|---|
| statusCode | String | 10001 |
| message | String | Callback is Required |
| data | Object | null |
Invalid Currency Response
| Field | Type | Description |
|---|---|---|
| statusCode | String | 10001 |
| message | String | Invalid Currency |
| data | Object | null |
Missing Field Response
| Field | Type | Description |
|---|---|---|
| statusCode | String | 400 |
| success | Boolean | false |
| message | String | Validation Failed |
| error | Object | List of validation errors |
Sample Request
{
"amount": 50,
"customerName": "Dev Test",
"email": "[email protected]",
"currency": "NGN",
"description": "test desc",
"meta": "test meta",
"callback": "https://hydrogenpay.com"
}
Sample Response
{
"statusCode": "90000",
"message": "Initiate bank transfer successful",
"data": {
"transactionRef": "testref0001",
"virtualAccountNo": "7193299054",
"virtualAccountName": "HYDROGEN - Instante Tetring",
"expiryDateTime": "06/07/2024 16:16:22",
"capturedDatetime": null,
"completedDatetime": null,
"transactionStatus": "Pending",
"amountPaid": 1000,
"bankName": "Access Bank"
}
}