Ecobank APIs
Endpoint Flow
This section outlines the supported protocols, header parameters, platform versioning, the various endpoints and status codes required for making a successful API calls.
a. All requests on the platform are required to have a POST HTTP method for all operations. This is used to create and read resources from various services.
b. The platform primarily uses JSON (JavaScript Object Notation) for both request payloads and response bodies. Each request must include appropriate HTTP headers, and the response will typically provide a JSON-formatted body, along with an HTTP status code that indicates the outcome of the request.
i. Content-Type: All requests must include the Content-Type: application/json header.
ii. Accept: The API supports the Accept: application/json header for responses.
c. The platform uses versioning to ensure backward compatibility while providing new features and improvements. The version number is included as part of the API URL (e.g., /v1/). Future versions may introduce changes or enhancements, but existing functionality in previous versions will remain supported as per our API deprecation policy.
d. The platform uses standard HTTP status codes to indicate the result of each API request. Below is a brief overview of the most used status codes:
200 OK: The request was successful, and the response contains the requested data.
400 Bad Request: The request was invalid or malformed.
401 Unauthorized: Authentication failed, or the token is invalid or expired.
403 Forbidden: The generated token does not have the required permission
404 Not Found: The requested resource does not exist.
500 Internal Server Error: The server encountered an unexpected condition.
A complete list of response codes and their responses is provided in the response code section.
A. Key Generation and Authorisation Process
To ensure secure access to all endpoints, additional security measures, requestToken and secureHash have been implemented.
requestToken: This is generated by applying the SHA-512 algorithm to a concatenated string comprising the request payload's header parameters and the Secret Key.
secureHash: This is generated by applying the SHA-512 algorithm to a concatenated string comprising the whole request payload's parameters and the Secret Key.
Refer to the respective endpoint documentation for detailed information on the parameters to concatenate and the step-by-step guidelines for generating these hash keys.
B. Endpoint Testing
Sign-in into your sandbox account, following the steps indicated at the Login to Account section to help populate all keys for sandbox testing.
On the navigation menu, click on the sandbox menu link item
Click on the preferred API service to access the service. E.g. Account Enquiry Service (Ensure the preferred service has been subscribed to under the product menu link. Follow the process outlined under the “section How to set up Sandbox Environment” to subscribe to a product).
4. Select the preferred endpoint you want to test under the selected service. E.g. Get Account Balance endpoint.
5. Use the obtained token for the preferred service under the section labelled “Steps to Obtain an Access Token” as the value of the Authorization header. The value should be “Bearer <obtained token>”
6. Click on the Send button to test the endpoint.
NOTE: The steps indicated under this section are applicable to all services and endpoints under the sandbox navigation menu.
In sections where the header of the request has no Authorization parameter, do the following:
1. In the request drawer navigation pane, click on the “Add header” button
2. For the name field enter “Authorization” and for the value field enter “Bearer <authorization token>”
Account Service Endpoint
The Account Service Endpoints provide access to account-related information. These endpoints offer a comprehensive set of functionalities for retrieving account data. Partners can leverage these APIs to build applications that require real-time account information, such as account balances, transaction histories, and account details.
A. Validate Account API Endpoint
The validate account name endpoint allows to validate account whether the account is active or inactive and associated with a valid customer and gives a brief description of the customer details
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string should be used as the requestToken value in the payload.
Generate a secure hash string using the formula indicated below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + accountNo + bankCode +request token + secret key
Generate a SHA-512 string using the hashString above. The generated SHA string should be used as the secureHash value.
B. Account Statement Inquiry
The Statement Inquiry API allows users to retrieve a detailed account statement for a specific account number within a defined date range, by calling the Get Account Statement endpoint. Generate statements on account are only allowed for a period not beyond 30 days.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request token+ accountNo + startDate + endDate + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
C. Get Pool Account Statement
The pool account statement Inquiry API allows partners to retrieve statement on their pool account, within a defined date range. Generate statements on account is only allowed for a period not beyond 30 days.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret keyGenerate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request token + accountNo + startDate + endDate + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
D. Get Pool Account Balance
This endpoint enables partners to check the balance of their pool accounts.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request token + accountNo + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
E. Get MOMO Networks
This endpoint gives a list of all profiled Telco or wallet provider networks by the bank in a particular country where Ecobank operates.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request token+ secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
F. Get Airtime Networks
This endpoint gives a list of all profiled network airtime providers by the bank.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress +request_token + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
G. Get Bank Institutions
This API allows users to query information of bank and other financial institutions that have been profiled by Ecobank.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + secretkey
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
H. Get Account Information
This endpoint allows users to retrieve the basic information of a specified account.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + accountNo + secretkey
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
I. Get Account Balance
This endpoint allows users to retrieve the balance of a specified account.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress +request_token + accountNo + secretkey
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
Local Bank Payment Service Endpoints
Local Bank Payment Service Endpoints provide a robust and efficient way to initiate and manage various payment transactions. These endpoints offer a comprehensive set of functionalities for processing payments, including domestic transfers, inter-bank payment and account transfers.
A. Inter-bank Transfers
This service allows you to transfer funds from your Ecobank account to accounts at other banks, within the same country. The service allows a single transfer per request.
a. Endpoint
B. Bulk Inter-bank Transfers
This service facilitates bulk transfers from Ecobank accounts to multiple external bank accounts within same country. It allows users to specify a list of recipient accounts and transfer amounts in a single call.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + requestToken + bankCode + receiverAccountNo + amountString + currency + description + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
C. Domestic Transfer
This service enables corporate clients to transfer funds from their pool accounts to any Ecobank account within the same country. Each transaction is processed individually, allowing for precise control and flexibility in payment disbursement.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + requestToken + receiverAccountNo + amountString + currency + description + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
D. Bulk Domestic Transfer
This service enables corporate clients to transfer funds from their pool accounts to designated Ecobank accounts in a single transaction. Multiple transfers can be initiated within a single request, streamlining the process for businesses with diverse payment needs. This type of transaction is asynchronous.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + dataConcatenationString + secret_key
NB: The dataConcatenationString should be generated by looping through the data key values of the payload and concatenating them as below
dataConcatenationString = receiverAccountNo + amountString + currency + description
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
E. Account Transfer
This service facilitates the transfer of funds between the partner’s pool account and other accounts associated with the partner. This is commonly referred to as internal transfers.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress +request_token + sourceAccountNo + receiverAccountNo + amount + currency + description + secretkey
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
F. Bulk Account Transfer
This service enables the partner transfer funds from their pool account to multiple accounts associated with their profile. This type of transaction is asynchronous.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + dataConcatenationString + public_key
NB: The dataConcatenationString should be generated by looping through the data key values of the payload and concatenating them as below
dataConcatenationString = sourceAccountNo + receiverAccountNo + amount + currency + description
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
Direct Payment From Ecobank Account Service Endpoint
The Direct Payment From Ecobank Account, also called Direct Debit API, allows Ecobank customers to authorize payments directly from their bank accounts for goods and services on merchant platforms. This requires onboarding on the Ecobank Authenticator App for transaction approvals using one-time password.
BASIC FLOW
Note:
Object ID is the same as the profile ID
Use Profile by user ID endpoint to get information about an account if you wish to call the deactivate or activate endpoints.
In a situation where one is unable to complete their profile set up with the stipulated time (15 minutes), they may use the activate API to complete the set up.
Deactivate profile is used to prevent an account from transacting via the service.
A. Customer Profile Activation
This endpoint activates a customer profile within the Ecobank Direct Debit system. For a deactivated profile, this endpoint ensures the user profile is made ready again for the service. The activation ensures that the customer’s profile is valid and ready for seamless integration into the direct debit process, linking their account to the authentication mechanism.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request _token + profileId + secret key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
B. Complete Customer Profile
If a customer cannot complete onboarding within the allotted window, this endpoint is used to finalize the onboarding processes. The profile remains deactivated until this endpoint is called. The system validates the information to ensure the customer is fully set up for Ecobank Direct Debit payments and authenticated transactions.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + token + userId + secret key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
C. Create Customer Profile
This is the main endpoint to create a new customer profile for users on the Ecobank Direct Debit system. It captures essential customer details and links their bank account to the Ecobank Authenticator.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + userId + userType + secret key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
D. Customer Profile Deactivation
This endpoint is used to deactivate a customer’s profile on the Ecobank Direct Debit system, preventing any future direct debit transactions via the Ecobank Authenticator. Deactivation might be required in cases of account closure, profile changes, or security reasons. The endpoint ensures that all services tied to the customer profile are securely disabled.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + profileId + secret key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
E. Get Customer Profile by ID
This endpoint retrieves detailed information about a customer’s profile using a unique identifier. It provides insights into the status of the profile, including whether the customer is successfully onboarded and activated, and returns other relevant data that could be used for further account management.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + userId + secret key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
F. Send OTP
This endpoint is used to send a one-time password (OTP) to the customer’s registered email address. The OTP is part is used to authenticate customer’s identity during profile creation ,activation, or deactivation.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + userId + secret key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
G. Customer OTP Validation
This endpoint is used to verify the one-time password (OTP) provided by the customer, following response from the Send OTP endpoint. It validates the OTP and thereby confirming the customer’s identity and allowing them to proceed with the onboarding processes.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress +request_token + code + trackingId + userType + secret key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
H. Resend OTP
This endpoint is used for resending the OTP to the customer if the previous one (obtained from Send OTP endpoint) has expired or was not received. It ensures that the customer can proceed with the authentication or transaction process even in the event of delivery issues or timeouts, maintaining the flow of the onboarding.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + trackingId + secret key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
I. Initiate Direct Debit Payment
This endpoint is used to initiate direct debit payments from the customer’s account to the merchant’s pool account. The funds transfer is initiated, waiting for an OTP from the customer’s Ecobank Authenticator App.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token+ amount + currency + description + secret key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
J. Validate Direct Debit Payment
The endpoint is used to consummate the funds transfer once the user provides an OTP from Ecobank Authenticator App.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + token + transactionReference + secret key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
Bill Payment
The Bill Payment API suite facilitates seamless financial transactions for various use cases, including wallet transfers, bill payments, and airtime top-ups. Designed for quick integration with various platforms, these APIs ensure secure, reliable, and efficient payment processes by allowing users to interact with multiple billers, retrieve biller information, and complete transactions.
A. Get Biller List
This endpoint provides a categorized list of billers based on the services they offer in a particular country. Categories may include utilities, telecommunications, insurance, and more. The categorization helps users navigate and find relevant billers quickly and effectively.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + category + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
B. Get Biller Category
This endpoint returns a comprehensive list of all available billers maintained in our system for a particular country. It allows partners and users to view and select billers for payments, streamlining the bill payment process. The list can be filtered by category, service type, or region for ease of use.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
C. Validate Biller
This endpoint is used to validate a biller before payment processing is initiated. It confirms the validity of the biller and ensures the correct details are in place for secure bill payments. Validation is crucial for avoiding errors and fraud during the payment process.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + billerCode + billerRefno + productCode + ccy + dataConcatenationString + secret_key
NB: The dataConcatenationString should be generated by looping through the formDataValue key values of the payload and concatenating them as below e.g.
dataConcatenationString = STUDENT_ID + STUDENT_ID_2
D. Get Biller Details
This endpoint retrieves detailed information about a specific biller, including their products, biller details, and form data details of a biller. It helps users understand the biller’s requirements before making payments, providing transparency and reducing errors in the payment process.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + billerCode + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
E. Pay Biller
This endpoint is used for the initiation of payments after a successful biller validation call. It processes the payment, and returns a transaction status, ensuring a seamless bill payment experience for the user.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress request_token + + billerId + billerCode + productCode + billRefNo + customerName + customerRef + amount + currency + narration + dataConcatenationString + secret_key
NB: The dataConcatenationString should be generated by looping through the formDataValue key values of the payload and concatenating them as below e.g.
dataConcatenationString = STUDENT_ID + STUDENT_ID_2
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
F. MOMO Transfer
The MOMO Transfer endpoint enables partners and users to transfer funds from their account to a mobile money wallet. The endpoint ensures secure processing of the transfer, from the user’s account to the recipient’s mobile money wallet, with a clear confirmation of transaction status.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + billerId + billerCode + productCode + mobileNo + amount + currency + narration + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
G. Airtime Top-up Service
This endpoint enables users to purchase airtime for mobile numbers, either for themselves or others, directly from their account. By providing mobile network and phone number details, users can top up airtime in real-time. The endpoint ensures that the correct airtime amount is credited, and it provides confirmation once the transaction is successfully completed.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + billerId + billerCode + productCode + mobileNo + amount + currency + narration + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
Xpress Cash Token
The Xpress Cash Token APIs are designed to provide a secure and efficient means for partners and clients to generate and manage cash tokens. These tokens can be redeemed at various Ecobank service points: ATMs, Ecobank branch, or designated agent points. Xpress Cash Token enhances financial service flexibility by enabling customers and businesses to carry out cash transactions without the need for physical cards.
A. Generate Token
This Generate Token endpoint enables clients to generate a cash token. The token can be shared with the beneficiary for redemption at Ecobank branch, ATMs or agent points. This token is a secure, time-bound representation of a cash value.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress request_token + + receiverMobileNo + amount + currency + description + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
B. Check Token Status
The Check Token Status endpoint allows clients to retrieve the status of a previously generated token.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + transactionReference + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
C. Get List of Token
The Get List of Tokens endpoint allows clients to retrieve a list of all tokens they have generated, along with their current statuses. This helps clients manage their tokens and track usage or redemption.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
D. Token Cancellation
The Cancel Token endpoint allows clients to invalidate a previously generated token. Once canceled, the token can no longer be used for cash redemption at ATMs or agent points.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + transactionReference + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
Account Opening
The Account Opening API provides a suite of services designed to simplify and automate the process of creating and managing bank accounts. These services cater to both individuals and businesses, offering flexibility and efficiency in onboarding new customers.
The API supports a range of account opening types, including individual accounts, corporate accounts for businesses, and express accounts for quick enrollment. Additionally, the API service includes functionality to check the status of accounts, ensuring that financial institutions and service providers can easily track and manage account activity.
A. Express Account Opening
This endpoint is designed for opening of bank account with minimum KYC details. It captures minimal customer details and is typically used for creating low-tier accounts, allowing users to quickly go onboard with fewer verification steps.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + firstName + middleName + lastName + mobileNo + email + gender + dateOfBirth + identityType + identityNo + idIssueDate + idExpiryDate + city + state + street + currency + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
B. Individual Account Opening
This endpoint allows the creation of savings accounts for individuals. The API collects personal details such as name, date of birth, identification, and contact information, and processes the request to open a bank account for the individual.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + firstName + middleName + lastName + mobileNo + email + gender + dateOfBirth + identityType + identityNo + idIssueDate + idExpiryDate + city + state + street + currency + bvn + nin + occupation + image + signature + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
E. Get Account Status
This endpoint provides the ability to query and retrieve the status of a bank account, especially during account creation. It checks whether the account has been successfully created or not. Response will return an empty data if account creation has not been completed.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formula indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + secret_key
Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.Generate a SHA-512 string using the tokenString generated above. This generated string from the SHA should be used for the requestToken value.
Generate a hash string using the indicated formula below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + request_token + trackReference + secret_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
Single IMTO API
The single IMTO API endpoint provides standardized integration for International Money Transfer Operators (IMTOs) and financial partners to process cross-border and domestic transfers through a single endpoint. This service enables seamless money movement to bank accounts, mobile wallets, and third-party payment networks while maintaining compliance and operational efficiency.
Key capabilities include:
Unified Transaction Processing: A single API integration supports multiple payout channels, including bank transfers, mobile money, and country-specific switches.
Real-Time Processing: Transactions are executed with low latency, and status updates are delivered via automated callbacks.
Compliance Integration: Built-in KYC, AML, and fraud screening ensure regulatory adherence.
Dynamic Routing: Intelligent middleware selects the optimal payment route based on recipient type, cost, and availability.
This documentation provides technical specifications for integrating with Ecobank's remittance infrastructure, covering authentication, request/response formats, error handling, and testing procedures.
A. Institution Lookup
Retrieves a comprehensive list of supported financial institutions where remittance transactions can be terminated. This endpoint provides metadata for banks, mobile network operators (MNOs), and third-party fintech partners across Ecobank’s network. Each institution entry includes identifiers, service types, supported countries, and currencies. Partners use this data to populate recipient selection menus and validate payout destinations before transaction initiation.
B. Get Rate Only
Fetches real-time exchange rates between specified source and target currencies. Provides the current conversion rate without fees, valid for a short window (typically 10-30 seconds). Used when partners need to display real-time rate tickers or calculate recipient amounts independently. Rate expiry timestamps prevent stale quotations.
C. Rate and Fees
Calculates the total cost of a remittance, including exchange rates, transfer fees, and recipient payout amounts. Accepts a specific transfer amount to return a detailed fee breakdown. Partners use this to display "Send X, Recipient Gets Y" calculations to end-users. The response includes all fees, total debit amount and conversions.
D. Transfer Validation
Pre-validates recipient account details and transaction parameters before fund submission.
Verifies account existence, name matching, and institution-specific rules (e.g., wallet number formats). Returns a confirmation flag and normalized recipient name. Critical for reducing failed transactions due to incorrect beneficiary data.
E. Initate Transfer
Submits a remittance transaction for processing after validation and compliance checks.
Handles the end-to-end workflow: sender/recipient details, currency conversion, routing, and compliance screening. Returns a transaction reference for tracking. Supports one-time transfers, with status updates delivered asynchronously via webhooks.
F. Transaction Status
Retrieves the current state and details of an initiated remittance. Provides real-time visibility into transaction progress (pending/success/failed). Includes timestamps, credited amounts, and failure reasons (e.g., "AML_BLOCK"). Used for customer notifications, dashboards, and reconciliation.
G. Initiate Reversal
Requests cancellation of a pending/completed transfer within a limited reversal window. Initiates fund recall for erroneous or duplicate transactions. Subject to recipient institution reversibility rules. Returns a reversal reference and deadline for tracking. Not guaranteed for completed cross-border transfers.
