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.
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.
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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress
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 formular indicated below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + accountNo + bankCode + secret_key + token_string
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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress+public_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 formular 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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 MOMO 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + publickey
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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 institutions that have been profiled by Ecobank. These institutions are mostly banks and mobile money network operators (MNOs)
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + publickey
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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + publickey
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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + publickey
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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + accountNo + secretkey
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
Payment Service Endpoint
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. 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. It allows users to specify a list of recipient accounts and transfer amounts in a single transaction.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public_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 formular 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 = receiverBankCode + externalRefno + 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.
C. Domestic Transfer
This service enables corporate clients to transfer funds from their pool accounts to any Ecobank account. 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + publickey
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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + receiverAccountNo + 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.
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 not asynchronous. Response is not the true status of transactions.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + publickey
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 formular 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 = externalRefno + 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.
E. Account Transfer
This service facilitates the transfer of funds between Ecobank accounts, commonly referred to as internal transfers.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + publickey
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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 users to transfer funds from a single Ecobank account to multiple Ecobank accounts. Each recipient account requires specific transaction details to be provided. This type of transaction is not asynchronous. Response is not the true status of transactions.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 + externalRefno + 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 Debit Service Endpoint
The Direct Debit API allows Ecobank customers to authorize payments directly from their bank accounts for goods and services on merchant platforms. A direct debit mandate empowers merchants to collect payments from a customer’s bank account upon authorization, streamlining the payment process for recurring or one-time transactions.
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. This is used when a customer began his/her onboarding journey but was not able to complete it due to some reasons. The profile remains deactivated until this endpoint is called. It enables the customer to begin using the Ecobank Authenticator app for direct debit transactions. 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public 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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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
This endpoint completes the account profile by finalizing the onboarding process. 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public 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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 endpoint creates a new customer profile for users who wish to onboard onto the Ecobank Direct Debit system. It captures essential customer details and links their bank account to the Ecobank Authenticator. The creation of this profile is a prerequisite for using the direct debit functionality for future transactions.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public 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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 deactivates a customer’s profile from 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public 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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public 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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 sends a one-time password (OTP) to the customer’s registered email address. The OTP is part of the authentication process to ensure the validity of the customer’s identity during profile creation, activation, or direct debit authorization.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public 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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 verifies the one-time password (OTP) provided by the customer. It ensures that the correct OTP is entered, confirming the customer’s identity and allowing them to proceed with the onboarding or transaction authorization process.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public 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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 re-sends the OTP to the customer if the previous one 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 or payment.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public 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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 initiates a direct debit payment from the customer’s account to the merchant’s pool account. It processes the transaction once the customer has authenticated the request using the Ecobank Authenticator app. The endpoint handles fund transfers and provides real-time transaction status updates to ensure that payments are processed securely and efficiently.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public 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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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
This endpoint validates the direct debit payment request made by the customer. It ensures that all details of the transaction, including customer credentials, payment amount, and authorization via the Ecobank Authenticator, are correct. The validation step confirms the payment’s legitimacy and ensures smooth settlement between customer and merchant.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + public 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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + 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 Payment API facilitates seamless financial transactions for various use cases, including wallet transfers, bill payments, and airtime top-ups. Designed for quick integration with various platforms, this API ensures secure, reliable, and efficient payment processes by allowing users to interact with multiple billers, retrieve biller information, and complete transactions. The API is ideal for merchants, service providers, and financial platforms seeking to automate payments and deliver a smooth customer experience.
A. Get Biller List
This endpoint provides a categorized list of billers based on the services they offer. 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + category + account_lab_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 within the system. It allows 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 validates a biller before processing any payment transactions. It confirms the legitimacy 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + billerCode + billerRefno + productCode + ccy + dataConcatenationString + account_lab_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. 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + billerCode + account_lab_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 facilitates the initiation of payments for various bills, such as utilities, and other services. It enables users to make secure and efficient payments directly from their account to the service provider. The endpoint verifies the biller details, 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + billerId + billerCode + productCode + billRefNo + customerName + customerRef + amount + currency + narration + dataConcatenationString + account_lab_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 allows 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + billerId + billerCode + productCode + mobileNo + amount + currency + narration + account_lab_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
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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + billerId + billerCode + productCode + mobileNo + amount + currency + narration + account_lab_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 API is designed to provide a secure and efficient means for clients to generate and manage cash tokens. These tokens can be used for various cash withdrawal and redemption purposes, primarily at ATMs or designated agent points. The API aims to enhance financial service flexibility by enabling customers and businesses to carry out cash transactions without the need for physical cards.
A. Generate Token
The Generate Token endpoint allows clients to create a cash token, which can be redeemed at 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + receiverMobileNo + amount + currency + description + account_lab_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. This ensures that the actual status of the token is known.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + transactionReference + account_lab_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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + transactionReference + account_lab_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. By integrating with the API, third-party applications or platforms can enable seamless account creation and status management, reducing manual intervention and improving the overall customer experience.
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 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 a simplified and fast-tracked account opening process. 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + firstName + middleName + lastName + mobileNo + email + gender + dateOfBirth + identityType + identityNo + idIssueDate + idExpiryDate + city + state + street + currency + account_lab_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
B. Corporate Account Opening
This endpoint facilitates the opening of corporate accounts for registered business entities, including corporations, LLCs, partnerships, and sole proprietorships. The API captures company details, directors' information, and business documentation necessary for account creation.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + trackReference + account_lab_key
Generate a SHA-512 string of the hashString generated above. The generated SHA string should be used as the secureHash value.
C. Individual Account Opening
This endpoint allows the creation of personal bank 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 formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + firstName + middleName + lastName + mobileNo + email + gender + dateOfBirth + identityType + identityNo + idIssueDate + idExpiryDate + city + state + street + currency + bvn + nin + occupation + image + signature + account_lab_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. It checks whether the account has been created successfully and return the account details. Response will return an empty data is account is not completed.
a. Endpoint
b. Generate Request Token (requestToken) and Secure Hash (secureHash)
Generate a request string using the formular indicated below
tokenString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + account_lab_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 formular below
hashString = clientId + affiliateCode + sourceCode + requestId + requestType + ipAddress + trackReference + account_lab_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.
