Bank transfers in Nigeria
| Name | The code | Description |
|---|---|---|
Integration type |
|
Payment via HighHelp payment widget |
Currency |
|
Nigerian Naira |
Side |
|
Nigeria |
Deposits |
✅ |
Available payment methods: |
Payments |
❌ |
Payments not available |
Payment
Creating an application
Create a payment request on your server using the API method
POST https://api.hh-processing.com/api/v1/widget/payin
Request body parameters when creating a P2P request.
-
general— information about the application.-
project_id— cashier identifier issued by HighHelp at the integration stage.
(string) (<= 32) -
payment_id— payment identifier, unique within the merchant’s checkout. You can use any letters, numbers and symbols in UTF-8 encoding.
(string) (<= 255) -
merchant_callback_url— dynamic URL for receiving notifications with intermediate information: changes in application status, payment details, etc. Notifications regarding the final status of the application are sent to the URLs specified inmerchant_success_callback_urlmerchant_decline_callback_url.
(string<https-url>) (<= 2048) -
merchant_success_callback_url— dynamic URL to receive a notification when the operation is successful.
(string<https-url>) (<= 2048) -
merchant_decline_callback_url— dynamic URL to receive an alert if the operation is not successful.
(string<https-url>) (<= 2048) -
redirect_url— a link to redirect the user from the payment page after completing the payment.
(string<https-url>) (<= 2048)
-
-
payment— payment information.-
widget_method— code of the payment method that will be pre-selected on the payment page. If the parameter is not passed, the user will select a payment method on the page. For a list of methods, seeWidget Methods (H2C).
(string) (<= 32) -
amount— the amount paid by the user. The amount is indicated in fractional units. See more details.Currency codes.
(integer) (1 <= X <= 10000000000000) -
currency— payment currency code in ISO 4217 alpha-3 format. See more details.Currency codes.
(string) (regex: ^[A-Z]{3}$) -
lifetime— request lifetime in seconds. The maximum lifetime is 10 minutes. If the parameter is not specified, the default value of 10 minutes is used. (integer) (300 <= X <= 600) -
description— payment description or comment. The value is displayed in the merchant's personal account.
(string) (<= 255) -
extra_param— an additional parameter for individual routing of a request. Configured together with the HighHelp administrator.
(string) (regex: ^[A-Za-z0-9_-]{1,16}$)
-
-
customer— information about the sender.-
id— a unique identifier of the user (sender) in the merchant system.
(string) (<= 255) -
ip_address— IP address of the sender.
(string<ip-address>) (<= 255) -
country— user country code in ISO 3166-1 alpha-2 format. For a list of supported countries, seeCountry codes.
(string) (regex: ^[A-Z]{2}$) -
language— language code in ISO 639-1 format, which will be pre-selected on the payment page. If no language is specified, the default language for the country is used. For a list of supported languages, seeLanguage codes.
(string) (regex: ^[a-z]{2}$) -
customer_type— user type:ftdfor primary traffic,trustfor secondary traffic.
(string) (regex: ^(ftd|trust)$) -
email— sender’s email address.
(string<email>) (<= 255)
-
|
For NGN, some fields cannot be pre-transmitted in the ticket creation request. HighHelp will reject the request if these fields are passed:
These values must be filled in by the client on the widget page. |
|
Fields marked, are mandatory. |
Example request:
curl https://api.hh-processing.com/api/v1/widget/payin \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
-H 'x-access-signature: SIGNATURE' \
-H 'x-access-token: API_KEY' \
-H 'content-type: application/json' \
-d '{
"general": {
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "NGN-PAYMENT-123456",
"merchant_callback_url": "https://your-domain.com/internal",
"merchant_success_callback_url": "https://your-domain.com/success",
"merchant_decline_callback_url": "https://your-domain.com/decline",
"redirect_url": "https://your-domain.com/order/page"
},
"payment": {
"amount": 150000,
"currency": "NGN",
"lifetime": 300,
"description": "Comment about the payment",
"extra_param": "example",
"widget_method": "payin-ussd"
},
"customer": {
"id": "cus_12345",
"ip_address": "192.0.2.1",
"customer_type": "ftd",
"country": "NG",
"email": "customer@example.com"
}
}'
Sample answer:
{
"status": "processing",
"sub_status": "requisites",
"status_description": null,
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "NGN-PAYMENT-123456",
"integration": {
"form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
"redirect_url": "https://your-domain.com/order/page"
}
}
Response options:
-
status— payment processing status. For a list of statuses, see sectionStatus codes.
(string) (<= 32) -
sub_status— payment processing substatus. Used only for some statuses. For a complete list of combinations of statuses and substatuses, seeStatus codes.
(string) (<= 32) -
status_description— additional information about the status. Used when there is a payment error.
(string) (<= 1024) -
request_id— payment identifier, which is generated in the HighHelp payment system.
(string) (<= 32) -
project_id— cash ID issued by HighHelp during the integration process.
(string) (<= 32) -
payment_id— payment identifier, unique within the merchant’s checkout.
(string) (<= 255) -
integration— additional meta-information about the payment.-
form_url— link to the payment page. The page displays payment details, payment instructions and service information.
(string<https-url>) (<= 255) -
redirect_url— a link to redirect the user from the payment page after completing the payment.
(string<https-url>) (<= 2048)
-
|
Fields marked, are mandatory. |
Application information
POST https://api.hh-processing.com/api/v1/widget/payin/info
Request body parameters for obtaining the status of a P2P application.
-
general— information about the application.-
project_id— cash ID issued by HighHelp during the integration process.
(string) (<= 32) -
payment_id— payment ID.
(string) (<= 255)
-
|
Fields marked, are mandatory. |
Example request:
curl https://api.hh-processing.com/api/v1/widget/payin/info \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
-H 'x-access-signature: SIGNATURE' \
-H 'x-access-token: API_KEY' \
-H 'content-type: application/json' \
-d '{
"general": {
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782',
"payment_id": "NGN-PAYMENT-123456"
}
}'
Sample answer:
{
"status": "processing",
"sub_status": "awaiting_confirm",
"status_description": null,
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "NGN-PAYMENT-123456",
"payment_info": {
"amount": 10000,
"old_amount": 10000,
"initial_amount": 3000,
"currency": "NGN",
"lifetime": 300,
"expiration_date": 1721647251,
"method": "ussd",
"widget_method": "payin-ussd",
"type": "payin"
},
"integration": {
"form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
"redirect_url": "https://your-domain.com/order/page"
}
}
Response options:
-
status— payment processing status. For a list of statuses, see sectionStatus codes.
(string) (<= 32) -
sub_status— payment processing substatus. Used only for some statuses. For a complete list of combinations of statuses and substatuses, seeStatus codes.
(string) (<= 32) -
status_description— additional information about the status. Used when there is a payment error.
(string) (<= 1024) -
request_id— payment identifier, which is generated in the HighHelp payment system.
(string) (<= 32) -
project_id— cash ID issued by HighHelp during the integration process.
(string) (<= 32) -
payment_id— payment identifier, unique within the merchant’s checkout.
(string) (<= 255) -
payment_info— payment information.-
amount— application amount. The amount is indicated in fractional units. See more details.Currency codes.
(integer) (1 <= X <= 10000000000000) -
old_amount— the amount of the application before the appeal. The value may differ fromamount, if the application was created for one amount, and the user transferred another. In this case, in the fieldamountthe actual amount received from the user is transmitted, and in the fieldold_amount— the amount for which the application was created. If the amount has not changed, the field values are the same.
(integer) (1 <= X <= 10000000000000) -
initial_amount— the amount specified when creating the application. The value does not change.
(integer) (1 <= X <= 10000000000000) -
currency— payment currency code in ISO 4217 alpha-3 format. See more details.Currency codes.
(string) (regex: ^[A-Z]{3}$) -
lifetime— request lifetime in seconds. The maximum lifetime is 10 minutes. If the parameter is not specified, the default value of 10 minutes is used. (integer) (300 <= X <= 600) -
expiration_date— time until which the application is valid, in Unix Timestamp (UTC) format.
(integer) (X <= 2^32) -
method— , . See more details.Payment methods.
(string) (<= 32) -
widget_method— payment method code of the payment page. See more details.Widget Methods (H2C).
(string) (<= 32) -
type— type of operation, for examplepayin; a general list of types is given in the sectionPayment types.
(string) (<= 32)
-
-
integration— additional meta-information about the payment.-
form_url— link to the payment page. The page displays payment details, payment instructions and service information.
(string<https-url>) (<= 255) -
redirect_url— a link to redirect the user from the payment page after completing the payment.
(string<https-url>) (<= 2048)
-
Payment statuses
For a complete list of statuses and substatuses, see the sectionStatus codes.
| Status | Substatus | Description | Merchant actions |
|---|---|---|---|
|
The request was rejected due to an error related to the payment parameters. |
Contact support |
|
|
|
The payment has been created and is awaiting client action. |
No action required |
|
Entering details is required, a link to the form is available in |
Direct the client to the payment form |
|
|
Client confirmation of payment is awaited. Payment is possible via redirection, QR or push notification (for example, for |
Wait for the payment to complete |
|
|
Funds have been secured and final confirmation is awaited. |
Wait for the payment to complete |
|
|
|
The client did not complete the payment within the payment lifetime ( |
No action required |
|
An amount received that does not match the stated amount. |
Contact support |
|
|
The confirmation timeout has expired and the payment has not been completed. |
Contact support |
|
|
Payment declined. |
Inform the client about the refusal |
|
|
Payment has been successfully confirmed. |
No action required |
Alerts
|
It is recommended to implement checking of incoming notifications for duplicates. The idempotency key can be generated using a template |
|
Each alert is digitally signed by HighHelp. The current public key for verifying the signature can be obtained in the admin panel. The key is unique for each cash register. The signature verification algorithm is the reverse of the signature generation algorithm when calling an API. Examples of signature verification are given in sectionsAlert Signing (RSA)Alert signature (HMAC). |
There are three types of alerts:
-
Informative— notifications in non-final statuses, if they are provided for a specific product (for example,
processing:*,dispute:*orerror). The URL is specified in the parametermerchant_callback_urlwhen creating an application. -
Successful— notifications for applications completed in status
success. The URL is specified in the parametermerchant_success_callback_url. -
Unsuccessful— notifications for applications completed in status
decline. The URL is specified in the parametermerchant_decline_callback_url.
The composition of the fields and the list of informative statuses depend on the product and integration scenario. See more details.H2H AlertsWidget Alerts.
Informative Alerts
Example of an alert with statusprocessing:awaiting_confirm:
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "NGN-PAYMENT-123456"
},
"status": {
"status": "processing",
"sub_status": "awaiting_confirm",
"status_description": null
},
"payment_info": {
"amount": 7000,
"old_amount": 7000,
"initial_amount": 3000,
"currency": "NGN",
"lifetime": 300,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "ussd",
"widget_method": "payin-ussd",
"type": "payin"
},
"recipient_requisites": {
"pan_hidden": "*901****713#",
"card_holder_hidden": "---",
"bank_name": "fidelity-bank-ngn",
"bank_country": "NG",
"currency": "NGN"
},
"integration": {
"form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
"redirect_url": "https://your-domain.com/order/page"
}
}
|
Masked details in the block |
Successful Alerts
An alert is sent if the application has reached the final successful statussuccess.
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "NGN-PAYMENT-123456"
},
"status": {
"status": "success",
"sub_status": null,
"status_description": null
},
"payment_info": {
"amount": 700000,
"old_amount": 500000,
"initial_amount": 300000,
"currency": "NGN",
"lifetime": 300,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "ussd",
"widget_method": "payin-ussd",
"type": "payin"
}
}
Unsuccessful Alerts
An alert is sent if the application is unsuccessful (for example, final statusdecline).
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "NGN-PAYMENT-123456"
},
"status": {
"status": "decline",
"sub_status": null,
"status_description": "Declined by anti-fraud"
},
"payment_info": {
"amount": 700000,
"old_amount": 700000,
"initial_amount": 300000,
"currency": "NGN",
"lifetime": 300,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "ussd",
"widget_method": "payin-ussd",
"type": "payin"
}
}