Welcome to the official API documentation for Finecore Partners' Backend-as-a-Service (BAAS) platform. This collection includes endpoints for managing wallets and accounts, including both static and dynamic account generation.
\nAvailable Services
\nWallet Management
\nCreate and retrieve wallet details
\nCheck balances
\nView transaction history
\nAccount Management
\nGenerate static accounts for users or organizations
\nCreate dynamic virtual accounts for one-time or scoped use
\nLink accounts to wallets
\nFor questions or technical support, contact our team at tech@finecore.co.
\nGetting Started
\nSet up your environment variables (e.g. https://api.finecore.co/v1, {{API_KEY}})
\nUse your API key in the X-API-Key header:
\nX-API-Key: {{API_KEY}}
\nExplore the endpoints organized by service in this collection
\nReview the example requests and responses for correct formatting
\nNotes
\nThis is the v1 version of the Finecore BAAS API.
\nAll responses are returned in JSON format.
\nEnsure your API key is kept secure and not exposed in public environments.
\nError responses will contain helpful messages and status codes.
\nThis document outlines the webhook event types and their associated data structures.
\ncustomer_bank_transfer: Represents a customer bank transfer event.
bank_transfer: Represents a merchant bank transfer event.
customer_wallet_debited: Represents an event where a customer's wallet is debited.
customer_wallet_credited: Represents an event where a customer's wallet is credited.
wallet_to_wallet_transfer: Represents a wallet-to-wallet transfer event.
batch_bank_transfer: Represents a batch bank transfer event.
account_funded: Represents an event where an account is funded.
When an event occurs, a webhook will be sent with the following JSON structure:
\n{\n\"event\": \"customer_bank_transfer\",\n\"data\":{\n \"id\": \"5a8d6c3e-bbf4-4f4b-80b9-8f2877363eae\",\n \"user_id\": \"2c8e91cd-7ae4-4b34-bc9f-39e72b2dd9c4\",\n \"merchant_id\": \"77b2d420-531c-44e7-a0fd-3d7e87b264dc\",\n \"reference\": \"TXN-239487293847\",\n \"amount\": 1500.75,\n \"currency\": \"NGN\",\n \"status\": \"COMPLETED\",\n \"balance_before\": 3500.00,\n \"balance_after\": 2000.25,\n \"environment\": \"SANDBOX\",\n \"type\": \"DEBIT\",\n \"category\": \"BANK_TRANSFER\",\n \"source\": \"wallet\",\n \"destination\": \"merchant_account\",\n \"description\": \"Payment for Order #12345\",\n \"metadata\": {\n \"order_id\": \"12345\",\n \"channel\": \"web\"\n },\n \"created_at\": \"2025-05-01T13:25:43Z\"\n}\n}\n\nThis webhook system allows Finecore to send event notifications to your server in real-time. The webhook delivers a JSON payload via an HTTP POST request to your specified webhook URL.
\nHow It Works:
\nThe server sends a POST request to your webhookUrl with a JSON payload.
The payload is signed using an HMAC-SHA256 signature generated with your secretKey.
The request includes headers to help you verify authenticity and ensure security.
\nHeaders:
\nContent-Type: application/json
\nX-Webhook-Signature: {HMAC_SHA256_SIGNATURE}
\nX-Webhook-Timestamp: {ISO_8601_UTC_TIMESTAMP}
\nExample:
\nX-Webhook-Signature: b1946ac92492d2347c6235b4d2611184
X-Webhook-Timestamp: 2025-05-08T12:34:56.789Z
Payload:
\nThe payload is a JSON object that contains the data relevant to the event. The structure will vary based on the event type.
\nExample payload:
\n{\n\"event\": \"customer_bank_transfer\",\n\"data\":{\n \"id\": \"5a8d6c3e-bbf4-4f4b-80b9-8f2877363eae\",\n \"user_id\": \"2c8e91cd-7ae4-4b34-bc9f-39e72b2dd9c4\",\n \"merchant_id\": \"77b2d420-531c-44e7-a0fd-3d7e87b264dc\",\n \"reference\": \"TXN-239487293847\",\n \"amount\": 1500.75,\n \"currency\": \"NGN\",\n \"status\": \"COMPLETED\",\n \"balance_before\": 3500.00,\n \"balance_after\": 2000.25,\n \"environment\": \"SANDBOX\",\n \"type\": \"DEBIT\",\n \"category\": \"BANK_TRANSFER\",\n \"source\": \"wallet\",\n \"destination\": \"merchant_account\",\n \"description\": \"Payment for Order #12345\",\n \"metadata\": {\n \"order_id\": \"12345\",\n \"channel\": \"web\"\n },\n \"created_at\": \"2025-05-01T13:25:43Z\"\n}\n}\n\nVerifying the Webhook:
\nCompute an HMAC-SHA256 hash of the raw request body using your secretKey.
Compare your computed hash with the value in the X-Webhook-Signature header.
Check that the X-Webhook-Timestamp is recent (recommended within 5 minutes) to prevent replay attacks.
Example verification steps:
\nExtract X-Webhook-Signature and X-Webhook-Timestamp from the headers.
Compute:
\nsignature = HMAC_SHA256(secretKey, rawBody)
\nCompare:
\nIf signature === X-Webhook-Signature β β valid.
\nWebhook Retry Policy
\nTo ensure reliable delivery, Finecoreβs webhook system implements an automatic retry mechanism when delivering webhook events to your endpoint.
\nBehavior:
\nNumber of retries: 3 attempts in total (1 initial + 2 retries).
\nRetry interval: Exponential backoff starting at 100 milliseconds:
\n1st attempt: immediately.
\n2nd attempt: after 5 seconds.
\n3rd attempt: after 10 seconds.
\nTimeout: Each webhook request will timeout after 30 seconds if your server does not respond.
\nRetry triggers: Retries occur if:
\nYour server is unreachable (network error).
\nYour server responds with a non-2xx HTTP status code.
\nYour server takes too long to respond (exceeds 30 seconds).
\nStopping Condition:
\nBest Practices for Your Endpoint:
\nAlways respond with a 2xx HTTP status code to acknowledge successful receipt.
\nValidate the X-Webhook-Signature header to ensure the requestβs authenticity.
Process webhook payloads idempotently to avoid duplicate side effects in case of retries.
\nExample Retry Flow:
\nImportant Notes:
\nAlways acknowledge receipt with a 200 OK HTTP status code.
Make sure your endpoint is secure and can handle requests at scale.
\nYour server should verify the signature and timestamp before processing the webhook payload.
\nFor technical support or questions, contact tech@finecore.co.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Finecore BAAS API Documentation","slug":"finecore-baas-api-documentation"}],"owner":"38720320","collectionId":"7e1f7326-12aa-4efa-9983-031ba436cd67","publishedId":"2sB2j4eW8P","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2025-07-25T22:18:46.000Z"},"item":[{"name":"Wallet","item":[{"name":"Transaction","item":[{"name":"Fetch customer transaction","id":"0777b6a9-66af-4478-9d9d-6d5429335ed9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"url":"{{BASE_URL}}/transactions/customer/:customer_id/:reference","description":"Fetch Transaction by Customer ID and Reference
\nEndpoint: GET /v1/transactions/customer/:customer_id/:reference
Description:
This endpoint retrieves a specific transaction for a given customer based on their unique customer_id and a unique transaction reference.
Parameters:
\ncustomer_id (path parameter): The unique identifier for the customer whose transaction is being fetched.
reference (path parameter): The unique reference code of the transaction you want to retrieve.
Response:
\nOn success, returns the transaction details including:
\nAmount
\nStatus (e.g., FAILED, COMPLETE, PENDING)
\nDate of transaction
\nTransaction type (CREDIT or DEBIT)
\nMetadata (optional)
\nError Handling:
\nIf the transaction is not found, a 404 Not Found response is returned.
If an error occurs, a relevant error message with status code is returned.
\nExample Request:
\nNotes:
\nEnsure that the customer_id and reference are correctly passed as path parameters.
Include the X-API-Key header for authentication:
X-API-Key: {{API_KEY}}
\nFetch All Transactions by Customer ID
\nEndpoint: GET /v1/transactions/customer/:customer_id
Description:
This endpoint retrieves all transactions associated with a specific customer identified by their unique customer_id. Use this to view the complete transaction history for a customer.
Parameters:
\ncustomer_id (path parameter): The unique identifier for the customer whose transactions are being fetched.Response:
\nOn success, returns a list of transactions with details including:
\nAmount
\nStatus (e.g., successful, failed)
\nDate of transaction
\nTransaction type (credit or debit)
\nMetadata (optional)
\nError Handling:
\nIf no transactions are found for the given customer, returns an empty list.
\nIf the customer ID is invalid, a 404 Not Found response is returned.
Any other errors will return a relevant error message with a corresponding status code.
\nNotes:
\nEnsure that the customer_id is passed correctly as a path parameter.
Include the X-API-Key header for authentication:
X-API-Key: {{API_KEY}}
\nTransaction Endpoints (Wallet)
\nThis folder contains endpoints for fetching transaction details related to wallets in the Finecore BAAS platform.
\nAvailable Actions:
\nFetch Transaction by Customer ID and Reference
\nRetrieve a specific transaction using the customer ID and transaction reference.
\nUse this endpoint to get detailed information about a single transaction.
\nFetch All Transactions by Customer ID
\nRetrieve all transactions associated with a specific customer ID.
\nThis can be used to view the complete transaction history for a customer.
\nFetch Transaction by Reference
\nRetrieve a transaction based on the transaction reference.
\nUse this endpoint to find a specific transaction using its unique reference code.
\nNotes:
\nThe customer_id and reference parameters are essential for fetching specific transactions.
Transactions are returned with details such as amount, status, date, and type (credit/debit).
\nMake sure to include the required X-API-Key in the header:
X-API-Key: {{API_KEY}}
\nCreate Wallet
\nEndpoint: POST /v1/wallets
Description:
This endpoint allows the creation of a new wallet for a customer. You need to provide the customer's personal information, such as BVN, name, date of birth, phone number, email, and address. A wallet will be created and linked to the provided customer details.
Request Body:
The request body must contain the following fields:
bvn (string): The customer's Bank Verification Number (BVN) for identity verification.
first_name (string): The first name of the customer, default is John/Doe for sandbox environment.
last_name (string): The last name of the customer.
date_of_birth (string): The customer's date of birth in DD-MM-YYYY(15-01-1990) format.
phone_number (string): The customer's phone number.
email (string): The customer's email address.
address (string): The customer's residential address.
On success, returns the details of the created wallet, including:
\nWallet ID
\nCustomer details (name, email, etc.)
\nWallet balance (initially 0)
\nError Handling:
\nIf required fields are missing or invalid, a 400 Bad Request response is returned.
If there are issues with the provided BVN, a 422 Unprocessable Entity response is returned.
Other errors will return a relevant error message with the corresponding status code.
\nNotes:
\nEnsure that all required fields are included in the request body.
\nInclude the X-API-Key header for authentication:
X-API-Key: {{API_KEY}}
\nFetch Wallets (Paginated)
\nEndpoint: GET /v1/wallets
Description:
This endpoint allows you to fetch a list of customer wallets with pagination. You can specify the page number and limit to control how many wallets are returned per request. This is useful when you need to retrieve a large set of wallets in chunks.
Query Parameters:
\npage (integer): The page number to retrieve. Defaults to 1 if not provided.
limit (integer): The number of wallets to return per page. Defaults to 10 if not provided. The maximum allowed value is 100.
Response:
\nOn success, returns a paginated list of wallets with the following details:
\nCustomer information (e.g., name, email, etc.)
\nWallet balance
\nPagination details (e.g., current page, total pages, etc.)
\nError Handling:
\nIf the page or limit parameters are invalid (e.g., negative numbers or non-integer values), a 400 Bad Request response is returned.
Any other errors will return a relevant error message with the corresponding status code.
\nNotes:
\nEnsure that the page and limit query parameters are provided for pagination.
Include the X-API-Key header for authentication:
X-API-Key: {{API_KEY}}
\nFetch Customer Wallet
\nEndpoint: GET /v1/wallets/:customer_id
Description:
This endpoint allows you to fetch the details of a customer's wallet using their unique customer_id. The response will contain the wallet information such as the current balance and other associated customer details.
Parameters:
\ncustomer_id (path parameter): The unique identifier of the customer whose wallet is being fetched.Response:
\nOn success, returns the wallet details, including:
\nCustomer information (e.g., name, email, etc.)
\nWallet balance
\nAdditional metadata (if available)
\nError Handling:
\nIf the customer wallet does not exist, a 404 Not Found response is returned.
If the customer_id is invalid, a 400 Bad Request response is returned.
Any other errors will return a relevant error message with the corresponding status code.
\nNotes:
\nEnsure that the customer_id is passed correctly as a path parameter.
Include the X-API-Key header for authentication:
X-API-Key: {{API_KEY}}
\nCredit Customer Wallet
\nEndpoint: POST /v1/wallets/credit
Description:
This endpoint allows you to credit a customer's wallet with a specified amount. You need to provide the customer_id, amount, and optional reference. If a reference is provided by the client, it will be used; otherwise, a reference will be automatically generated.
Request Body:
The request body must contain the following fields:
amount (float): The amount to credit to the customer's wallet.
customer_id (string): The unique identifier of the customer whose wallet is being credited.
reference (string, optional): The unique reference for the transaction. If not provided, a reference will be automatically generated for you.
metadata (object, optional): Additional information regarding the transaction. In this case, a reason field can be included, such as the purpose for the credit.
If no reference is provided, the system will generate one.
\nResponse:
\nOn success, returns a confirmation of the credited amount along with the transaction details:
\nAmount credited
\nCustomer wallet balance (updated)
\nTransaction reference
\nMetadata (if included)
\nError Handling:
\nIf any required fields are missing or invalid, a 400 Bad Request response is returned.
If the customer_id does not exist, a 404 Not Found response is returned.
If the amount is negative or invalid, a 400 Bad Request response is returned.
Any other errors will return a relevant error message with the corresponding status code.
\nFetch Transaction by Reference
\nEndpoint: GET /v1/transactions/:reference
Description:
This endpoint retrieves a specific transaction using its unique transaction reference. The reference is typically a code generated for each transaction to track it in the system.
Parameters:
\nreference (path parameter): The unique reference code of the transaction you want to retrieve. This reference is assigned to each transaction at the time of creation.Response:
\nOn success, returns the transaction details including:
\nAmount
\nStatus (e.g., successful, failed)
\nDate of transaction
\nTransaction type (credit or debit)
\nMetadata (optional)
\nError Handling:
\nIf the transaction is not found, a 404 Not Found response is returned.
If an invalid reference is provided, a 400 Bad Request response is returned.
Any other errors will return a relevant error message with status code.
\nNotes:
\nEnsure that the reference is passed correctly as a path parameter.
Include the X-API-Key header for authentication:
X-API-Key: {{API_KEY}}
\nCreate Wallet
\nEndpoint: POST /v1/wallets
Description:
This endpoint allows the creation of a new wallet for a customer. You need to provide the customer's personal information, such as BVN, name, date of birth, phone number, email, and address. A wallet will be created and linked to the provided customer details.
Request Body:
The request body must contain the following fields:
bvn (string): The customer's Bank Verification Number (BVN) for identity verification.
first_name (string): The first name of the customer, default is John/Doe for sandbox environment.
last_name (string): The last name of the customer.
date_of_birth (string): The customer's date of birth in DD-MM-YYYY(15-01-1990) format.
phone_number (string): The customer's phone number.
email (string): The customer's email address.
address (string): The customer's residential address.
On success, returns the details of the created wallet, including:
\nWallet ID
\nCustomer details (name, email, etc.)
\nWallet balance (initially 0)
\nError Handling:
\nIf required fields are missing or invalid, a 400 Bad Request response is returned.
If there are issues with the provided BVN, a 422 Unprocessable Entity response is returned.
Other errors will return a relevant error message with the corresponding status code.
\nNotes:
\nEnsure that all required fields are included in the request body.
\nInclude the X-API-Key header for authentication:
X-API-Key: {{API_KEY}}
\nCreate Wallet
\nEndpoint: POST /v1/wallets
Description:
This endpoint allows the creation of a new wallet for a customer. You need to provide the customer's personal information, such as BVN, name, date of birth, phone number, email, and address. A wallet will be created and linked to the provided customer details.
Request Body:
The request body must contain the following fields:
bvn (string): The customer's Bank Verification Number (BVN) for identity verification.
first_name (string): The first name of the customer, default is John/Doe for sandbox environment.
last_name (string): The last name of the customer.
date_of_birth (string): The customer's date of birth in DD-MM-YYYY(15-01-1990) format.
phone_number (string): The customer's phone number.
email (string): The customer's email address.
address (string): The customer's residential address.
On success, returns the details of the created wallet, including:
\nWallet ID
\nCustomer details (name, email, etc.)
\nWallet balance (initially 0)
\nError Handling:
\nIf required fields are missing or invalid, a 400 Bad Request response is returned.
If there are issues with the provided BVN, a 422 Unprocessable Entity response is returned.
Other errors will return a relevant error message with the corresponding status code.
\nNotes:
\nEnsure that all required fields are included in the request body.
\nInclude the X-API-Key header for authentication:
X-API-Key: {{API_KEY}}
\nWallet Endpoints
\nThis folder contains all endpoints related to wallet operations in the Finecore BAAS platform.
\nAvailable Actions:
\nCreate a new wallet for a user or organization
\nRetrieve wallet details by ID or user reference
\nCheck current wallet balance
\nView wallet transaction history
\nNotes:
\nWallets are linked to users or organizations by unique identifiers
\nAll balances are returned in the default system currency
\nTransactions include metadata such as type (credit/debit), source, and timestamp
\nEnsure your requests include the required headers, especially:
\nX-API-Key: {{API_KEY}}
\n","_postman_id":"8cf6783c-6f4e-472f-af38-9fce067de1cd"},{"name":"Bank Transfer","item":[{"name":"Merchant Transfer to bank account","id":"158e4df1-bd11-4787-b15d-5c3739c4dc14","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"amount\": 6000,\r\n \"reference\": \"t68bay1ootinzPZiaZpVxMHd\",\r\n \"sort_code\": \"090405\",\r\n \"narration\": \"Testing41330324\",\r\n \"account_number\": \"8034074748\",\r\n \"account_name\": \"Obagunwa Emmanuel\",\r\n \"metadata\": {\r\n \"reason\": \"testing\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/transfers/bank","description":"Merchant Bank Transfer
\nEndpoint: POST /v1/transfers/bank
Description:
This endpoint allows merchants to initiate a bank transfer by providing the required transfer details. An optional reference can be provided by the merchant. If not provided, a new reference will be generated automatically.
Request Body:
\namount (float): The amount to be transferred.
reference (string, optional): A unique reference for the transaction. If not provided, a new reference will be generated.
sortCode (string): The sort code of the recipient's bank.
narration (string): A short description or message about the transfer.
accountNumber (string): The account number of the recipient.
accountName (string): The name of the account holder.
metadata (object, optional): Additional information about the transfer (e.g., reason).
reason (string, optional): The reason for the transfer.Response:
\nOn success, returns the details of the initiated bank transfer, including the transaction status and the reference used.
\nIf the reference is provided and a transaction already exists with that reference, an error will be returned.
Error Handling:
\nIf the provided reference already exists, a 409 Conflict error will be returned.
If any required parameter is missing or invalid, a 400 Bad Request error will be returned.
Notes:
\nEnsure that the X-API-Key header is included for authentication:
X-API-Key: {{API_KEY}}
\nList of Banks
\nEndpoint: GET /v1/transfers/banks
Description:
This endpoint retrieves a list of banks available for transfers. The list contains details about each bank, including the bank name, code, and other relevant information. This can be used to view all supported banks for transfer operations.
Response:
\nOn success, returns a list of banks, including their details such as bank name, code, and any other relevant information.
\nIf no banks are available, an empty list is returned.
\nError Handling:
\n500 Internal Server Error will be returned.Notes:
\nEnsure that the X-API-Key header is included for authentication:
X-API-Key: {{API_KEY}}
\nCustomer Bank Transfer
\nEndpoint: POST /v1/transfers/bank/customer
Description:
This endpoint allows a customer to initiate a transfer to a bank account. The customer can provide an optional reference. If the reference is not provided, a unique reference will be generated.
Request Body:
\namount (float): The amount to be transferred.
reference (string, optional): A unique reference for the transaction. If not provided, a new reference will be generated.
sortCode (string): The sort code of the recipient's bank.
narration (string): A brief description or message about the transfer.
accountNumber (string): The bank account number of the recipient.
accountName (string): The name of the account holder.
customerId (string): The ID of the customer initiating the transfer.
metadata (object, optional): Additional information regarding the transfer (e.g., custom key-value pairs).
key (string): A key for storing additional information.
value (string): The value associated with the key.
Response:
\nOn success, returns a confirmation of the transfer with the transaction details and the reference.
\nIf the reference is provided and a transaction already exists with that reference, an error will be returned.
Error Handling:
\nIf the provided reference already exists, a 409 Conflict error will be returned.
If any required parameter is missing or invalid, a 400 Bad Request error will be returned.
Notes:
\nEnsure that the X-API-Key header is included for authentication:
X-API-Key: {{API_KEY}}
\nBank Transfer API
\nDescription:
This folder contains endpoints for handling bank transfers. It provides functionality for merchant and customer bank transfers, as well as retrieving a list of available banks and checking bank account details.
Endpoints:
\nMerchant Bank Transfer
\nURL: {{BASE_URL}}/transfers/bank
Description: This endpoint is used by merchants to initiate a bank transfer.
\nMethod: POST
Request Body:
\nResponse:
\nList of Banks
\nURL: {{BASE_URL}}/transfers/banks
Description: This endpoint returns a list of available banks for transfer purposes.
\nMethod: GET
Response:
\nGet Bank Detail
\nURL: {{BASE_URL}}/transfers/account
Description: This endpoint allows you to retrieve details of a bank account, given the account number and other necessary details.
\nMethod: GET
Request Parameters:
\naccount_number (string): The account number for which details are to be fetched.Response:
\nCustomer Bank Transfer
\nURL: {{BASE_URL}}/transfers/bank/customer
Description: This endpoint is used by customers to initiate a bank transfer.
\nMethod: POST
Request Body:
\nResponse:
\nCommon Request Headers:
\nX-API-Key: Authentication key to access the API.Create Dynamic Account
\nEndpoint: POST /v1/accounts/dynamic
\nDescription:
This endpoint generates a dynamic virtual account tied to a specific transaction. The account is temporary and will expire after the specified duration. It is primarily used for one-time payments.
Request Headers:
\nRequest Body:
{
\"amount\": 100.00,
\"reference\": \"yofddearndcdss\",
\"duration_in_minutes\": 30
}
Body Parameters:
\namount (number, required): The expected amount to be paid into the dynamic account.
\nreference (string, optional): A unique identifier for the transaction. If not provided, one will be auto-generated.
\nduration_in_minutes (integer, required): How long the account should stay active before expiration.
\nResponse:
\nReturns the dynamic account details including:
\naccount_number
\naccount_name
\nbank_name
\nexpiration_time
\nreference
\nPossible Status Codes:
\n201 Created: Dynamic account successfully generated.
\n400 Bad Request: Invalid or missing input fields.
\n409 Conflict: Reference already exists.
\n500 Internal Server Error: An error occurred during account generation.
\nNote:
\nThis account is valid for a limited time only.
\nIt is recommended to monitor the expiration timestamp to ensure payment is received within the valid window.
\nCreate Static Account
\nEndpoint: POST /v1/accounts/static
Description:
This endpoint is used to create a static virtual account for a user. A static account is permanently associated with the user and can be used for receiving payments multiple times.
Request Headers:
\nX-API-Key: Your API key for authentication.Body Parameters:
\nemail_address (string, required): The email of the user to whom the static account will be linked.
first_name (string, required): The first name of the user.
last_name (string, required): The last name of the user.
phone_number (string, required): The userβs phone number.
Response:
\nReturns the details of the created static account including the account number, account name, and bank name.
\nPossible Status Codes:
\n201 Created: Static account successfully created.
400 Bad Request: Missing or invalid fields in the request.
409 Conflict: Account already exists with the provided email or phone number.
500 Internal Server Error: A problem occurred while processing the request.
Note:
The static account created can be used by the customer to receive funds repeatedly. It is uniquely tied to the user profile.
Get Static Virtual Account Detail
\nEndpoint: GET /v1/accounts/static/:account_number
\nDescription:
Retrieves the details of a static virtual account using the account number. Useful for verifying the owner or status of a static account.
Request Headers:
\nPath Parameter:
\nResponse:
\nReturns the static account details including:
\naccount_number
\naccount_name
\nbank_name
\nassociated user information (e.g., email, phone number)
\nPossible Status Codes:
\n200 OK: Account details retrieved successfully.
\n404 Not Found: No static account found with the provided account number.
\n500 Internal Server Error: An error occurred while fetching the account details.
\nNote:
\nGet Dynamic Virtual Account Detail
\nEndpoint: GET /v1/accounts/dynamic/:account_number
\nDescription:
Retrieves the details of a dynamic virtual account using the account number. This is useful for validating a temporary account created for one-time payments.
Request Headers:
\nPath Parameter:
\nResponse:
\nReturns details of the dynamic account including:
\naccount_number
\naccount_name
\nbank_name
\nexpiration_time
\nreference
\namount
\nstatus
\nPossible Status Codes:
\n200 OK: Account details successfully retrieved.
\n404 Not Found: No dynamic account exists with the provided account number.
\n410 Gone: Account has expired and is no longer active.
\n500 Internal Server Error: An unexpected error occurred while retrieving the account details.
\nNote:
\n410 Gone status.Close Static Virtual Account
\nEndpoint: POST /v1/accounts/static/close
\nDescription:
Closes a static virtual account. This action disables the account, preventing any further transactions. Typically used when an account is no longer needed or needs to be deactivated for security reasons.
Request Headers:
\nRequest Body:
\naccount_number (number, required): The static account number to be closed.
\nnote (string, optional): A remark or reason for closing the account.
\n{ \"account_number\": 7000026062, \"note\": \"for testing\"}
\nList Virtual Accounts
\nEndpoint: GET /v1/accounts
\nDescription:
Retrieves a list of all virtual accounts (static and/or dynamic) associated with your API key. You can optionally filter the results by account type.
Request Headers:
\nQuery Parameters:
\nSTATIC to list only static accounts, or DYNAMIC to list only dynamic accounts.Examples:
\nList all accounts: GET /v1/accounts
List only static accounts: GET /v1/accounts?account_type=STATIC
List only dynamic accounts: GET /v1/accounts?account_type=DYNAMIC
Response:
\nAn array of account objects, each containing:
\naccount_number
\naccount_name
\naccount_type (STATIC or DYNAMIC)
\nbank_name
\nstatus
\nreference (for dynamic accounts)
\nexpiration_time (if applicable)
\nPossible Status Codes:
\n200 OK: Accounts retrieved successfully.
\n400 Bad Request: Invalid account_type parameter.
\n500 Internal Server Error: Failed to retrieve accounts.
\nNote:
\npage and limit query parameters if supported.Account Folder
\nThis folder contains endpoints related to managing accounts. It includes functionality for creating accounts, fetching account details, updating account information, and performing other operations related to customer accounts. Below are the key endpoints available in this folder:
\nCreate Account
\nEndpoint: POST /v1/accounts
Description: This endpoint is used to create a new account for a customer.
\nRequest Body:
\nbvn (string): The customer's BVN (Bank Verification Number).
first_name (string): The first name of the customer.
last_name (string): The last name of the customer.
date_of_birth (string): The customer's date of birth (in the format DD-MM-YYYY).
phone_number (string): The customer's phone number.
email (string): The customer's email address.
address (string): The customer's physical address.
Response:
\nFetch Static Account Details
\nEndpoint: GET /v1/accounts/static/:account_number
Description: This endpoint fetches the account details for a specific customer.
\nPath Parameters:
\nResponse:
\nFetch Dynamic Account Details
\nEndpoint: GET /v1/accounts/dynamic/:account_number
Description: This endpoint fetches the account details for a specific customer.
\nPath Parameters:
\nResponse:
\nClose Account
\nEndpoint: DELETE /v1/accounts/:account_number
Description: This endpoint is used to delete a customer account.
\nPath Parameters:
\nResponse:
\nFor all endpoints, appropriate HTTP status codes will be returned for different scenarios, such as:
\n400 Bad Request: Missing or invalid parameters.
404 Not Found: The specified account does not exist.
500 Internal Server Error: A problem occurred on the server.
Ensure that the X-API-Key header is included for authentication:
X-API-Key: {{API_KEY}}
\nStarts a card payment. Depending on the card type, the transaction may require OTP or 3DS authentication.
\n","urlObject":{"path":["payments","card"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[{"id":"c5bfd64c-02f1-401e-bc0d-d328ab2b6612","name":"Payment with card","originalRequest":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"amount\": 10000.00,\r\n \"currency\": \"NGN\",\r\n \"reference\": \"txn_20231201_0015\",\r\n \"metadata\":{\r\n \"someData\": \"someData\"\r\n },\r\n \"card_details\": {\r\n \"pan\": \"5123450000000008\",\r\n \"expiry_date\": \"3901\",\r\n \"cvv\": \"100\",\r\n \"pin\": \"1111\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/card"},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Security-Policy","value":"default-src 'self';script-src 'self' 'unsafe-inline' https://cdn.example.com;style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;img-src 'self' data: https://*.example.com;font-src 'self' https://fonts.gstatic.com;connect-src 'self' https://api.example.com;frame-ancestors 'none';"},{"key":"Permissions-Policy","value":"geolocation=(), microphone=(), camera=()"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Vary","value":"Origin"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Date","value":"Thu, 11 Sep 2025 14:54:15 GMT"},{"key":"Content-Length","value":"332"},{"key":"Content-Type","value":"text/plain; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\"success\":true,\"message\":\"A verification code has been sent to your registered mobile number:234805***1111\",\"data\":{\"transaction_reference\":\"txn_20231201_0015\",\"requires_authentication\":true,\"auth_type\":\"OTP\",\"message\":\"A verification code has been sent to your registered mobile number:234805***1111\",\"next_action\":\"submit_otp\"}}\n"},{"id":"6429c909-e2c7-4c96-9a67-fe29d3e9415f","name":"Payment with card (3D)","originalRequest":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"amount\": 10000.00,\r\n \"currency\": \"NGN\",\r\n \"reference\": \"txn_20231201_0029\",\r\n \"metadata\":{\r\n \"someData\": \"someData\"\r\n },\r\n \"device_information\": { \r\n \"httpBrowserLanguage\": \"en-US\",\r\n \"httpBrowserJavaEnabled\": true,\r\n \"httpBrowserJavaScriptEnabled\": true,\r\n \"httpBrowserColorDepth\": 24,\r\n \"httpBrowserScreenHeight\": 1203,\r\n \"httpBrowserScreenWidth\": 2138,\r\n \"httpBrowserTimeDifference\": \"\",\r\n \"userAgentBrowserValue\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36\"\r\n },\r\n \"callback_url\": \"https://webhook.site/51db6bef-2c95-47ba-9612-fe9df449de46\",\r\n \"card_details\": {\r\n \"pan\": \"4000000000002503\",\r\n \"expiry_date\": \"5003\",\r\n \"cvv\": \"11\",\r\n \"pin\": \"1111\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/card"},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Security-Policy","value":"default-src 'self';script-src 'self' 'unsafe-inline' https://cdn.example.com;style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;img-src 'self' data: https://*.example.com;font-src 'self' https://fonts.gstatic.com;connect-src 'self' https://api.example.com;frame-ancestors 'none';"},{"key":"Permissions-Policy","value":"geolocation=(), microphone=(), camera=()"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Vary","value":"Origin"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Date","value":"Fri, 12 Sep 2025 13:43:08 GMT"},{"key":"Content-Length","value":"816"},{"key":"Content-Type","value":"text/plain; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\"success\":true,\"message\":\"Please complete the secure authentication process with your bank\",\"data\":{\"transaction_reference\":\"txn_20231201_0029\",\"requires_authentication\":true,\"auth_type\":\"3DS\",\"message\":\"Please complete the secure authentication process with your bank\",\"next_action\":\"redirect_3ds\",\"payment_id\":\"474982513\",\"bank_code\":\"058\",\"acs_url\":\"https://qa.interswitchng.com/collections/wibmosecure\",\"term_url\":\"http://localhost:6081/collections/api/v1/pay/wibmoCallBack\",\"md\":\"474982513\",\"jwt\":\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjRkMDVlYmY1LTJjYzMtNGIzNS05MDkyLWIyMmE0YzMxYTAxNyIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovLzNkczItYXBpLTNkc3NlcnZlci1pbnRnLnBjLmVuc3RhZ2Utc2FzLmNvbS93cmFwcGVyYXBpL2Flcmlvbi8zZHNzL2VtdmNvL3BBcnEvMzg3MTQ1ZDQtMGM5MC00OTI0LWFiYTYtMmViMTMyNGZlOWE1In0=\",\"eci_flag\":\"07\"}}\n"}],"_postman_id":"53d8f0e3-d8d1-4126-800b-0d299201bc8f"},{"name":"Approve Card Payment","id":"25a60cd0-471a-4286-82cc-3505a697d165","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"otp\": \"123456\",\r\n \"transaction_reference\": \"txn_20231201_0020\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/card/approve","description":"Approves card payment using OTP received.
\n","urlObject":{"path":["payments","card","approve"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[{"id":"c58fa88a-ce78-4af3-8242-22abf197a7e2","name":"Approve Card Payment With OTP","originalRequest":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"otp\": \"123456\",\r\n \"transaction_reference\": \"txn_20231201_0020\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/card/approve"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"Approved by Financial Institution\",\n \"data\": {\n \"transaction_reference\": \"txn_20231201_0020\",\n \"message\": \"Approved by Financial Institution\",\n \"status\": \"COMPLETED\",\n \"amount\": \"10000.00\"\n }\n}"},{"id":"fbb72ac3-fe83-44eb-94b1-28fbaedd7dd5","name":"Approve Card Payment With 3DS","originalRequest":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"transaction_reference\": \"txn_20231201_0032\",\r\n \"eci_flag\": \"07\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/card/approve"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\r\n \"success\": true,\r\n \"message\": \"Approved by Financial Institution\",\r\n \"data\": {\r\n \"transaction_reference\": \"txn_20231201_0020\",\r\n \"message\": \"Approved by Financial Institution\",\r\n \"status\": \"COMPLETED\",\r\n \"amount\": \"10000.00\"\r\n }"}],"_postman_id":"25a60cd0-471a-4286-82cc-3505a697d165"},{"name":"Resend OTP For Payment With Card","id":"92f6f021-8c7f-4fa9-843e-7baaab4771b5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"transaction_reference\": \"txn_20231201_0024\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/card/resend-otp","description":"Resends OTP if the user did not receive it.
\n","urlObject":{"path":["payments","card","resend-otp"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[{"id":"cc4ed135-9944-40fe-8d19-de3327e00a6d","name":"New Request","originalRequest":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"transaction_reference\": \"txn_20231201_0024\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/card/resend-otp"},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Security-Policy","value":"default-src 'self';script-src 'self' 'unsafe-inline' https://cdn.example.com;style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;img-src 'self' data: https://*.example.com;font-src 'self' https://fonts.gstatic.com;connect-src 'self' https://api.example.com;frame-ancestors 'none';"},{"key":"Permissions-Policy","value":"geolocation=(), microphone=(), camera=()"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Vary","value":"Origin"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Date","value":"Fri, 12 Sep 2025 08:18:53 GMT"},{"key":"Content-Length","value":"334"},{"key":"Content-Type","value":"text/plain; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\"success\":true,\"message\":\"A verification code has been sent to your registered mobile number: 234805***1111\",\"data\":{\"transaction_reference\":\"txn_20231201_0024\",\"requires_authentication\":true,\"auth_type\":\"OTP\",\"message\":\"A verification code has been sent to your registered mobile number: 234805***1111\",\"next_action\":\"submit_otp\"}}\n"}],"_postman_id":"92f6f021-8c7f-4fa9-843e-7baaab4771b5"}],"id":"903a9352-564f-4ed7-bab8-c83d1eba22dc","description":"Handles payments using credit or debit cards. Supports normal OTP flow and 3D Secure (3DS) flow.
\n","_postman_id":"903a9352-564f-4ed7-bab8-c83d1eba22dc"},{"name":"USSD","item":[{"name":"Initiate Payment With USSD","id":"9c6b0411-cafd-4073-9755-8aa373b79fb0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"amount\": \"100\",\r\n \"bank_code\": \"GTB\",\r\n \"currency_code\": \"566\",\r\n \"transaction_reference\": \"TX1R69HAAEAEYVTD1UEY93O4\",\r\n \"sursurge\": 5,\r\n \"metadata\": {\r\n \"someData\": \"some kind of object\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/ussd","description":"Starts a USSD payment by generating a code for the user to dial.
\n","urlObject":{"path":["payments","ussd"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[{"id":"32f6c6bc-d9c4-49fa-b9b8-464d6357278e","name":"Initiate Payment With USSD","originalRequest":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"amount\": \"10000\",\r\n \"bank_code\": \"GTB\",\r\n \"currency_code\": \"566\",\r\n \"transaction_reference\": \"bn12222z2aaz\",\r\n \"metadata\": {\r\n \"someData\": \"some kind of object\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/ussd"},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Security-Policy","value":"default-src 'self';script-src 'self' 'unsafe-inline' https://cdn.example.com;style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;img-src 'self' data: https://*.example.com;font-src 'self' https://fonts.gstatic.com;connect-src 'self' https://api.example.com;frame-ancestors 'none';"},{"key":"Permissions-Policy","value":"geolocation=(), microphone=(), camera=()"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Vary","value":"Origin"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Date","value":"Tue, 16 Sep 2025 16:10:19 GMT"},{"key":"Content-Length","value":"223"},{"key":"Content-Type","value":"text/plain; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\"success\":true,\"message\":\"USSD payment initiated\",\"data\":{\"bank_short_code\":\"*737*000*3865#\",\"default_short_code\":\"*322*419*051691201*3865#\",\"reference\":\"3865\",\"response_code\":\"00\",\"transaction_reference\":\"bn12222z2aaz\"}}\n"}],"_postman_id":"9c6b0411-cafd-4073-9755-8aa373b79fb0"},{"name":"Get USSD Banks","id":"f0f127d0-565a-4249-af6a-77e0b000bf09","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"amount\": 10000.00,\r\n \"currency\": \"NGN\",\r\n \"reference\": \"txn_20231201_001\",\r\n \"metadata\":{\r\n \"someData\": \"someData\"\r\n },\r\n \"card_details\": {\r\n \"pan\": \"5123450000000008\",\r\n \"expiry_date\": \"3901\",\r\n \"cvv\": \"100\",\r\n \"pin\": \"1111\"\r\n }\r\n}"},"url":"{{BASE_URL}}/payments/ussd/banks","urlObject":{"path":["payments","ussd","banks"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[{"id":"9e2d7786-d016-4585-8b70-21b4da8b493b","name":"New Request","originalRequest":{"method":"GET","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"amount\": 10000.00,\r\n \"currency\": \"NGN\",\r\n \"reference\": \"txn_20231201_001\",\r\n \"metadata\":{\r\n \"someData\": \"someData\"\r\n },\r\n \"card_details\": {\r\n \"pan\": \"5123450000000008\",\r\n \"expiry_date\": \"3901\",\r\n \"cvv\": \"100\",\r\n \"pin\": \"1111\"\r\n }\r\n}"},"url":"{{BASE_URL}}/payments/ussd/banks"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Security-Policy","value":"default-src 'self';script-src 'self' 'unsafe-inline' https://cdn.example.com;style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;img-src 'self' data: https://*.example.com;font-src 'self' https://fonts.gstatic.com;connect-src 'self' https://api.example.com;frame-ancestors 'none';"},{"key":"Permissions-Policy","value":"geolocation=(), microphone=(), camera=()"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Vary","value":"Origin"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Date","value":"Tue, 16 Sep 2025 17:35:30 GMT"},{"key":"Content-Length","value":"1105"},{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"USSD Banks successfully retrieved\",\n \"data\": [\n {\n \"cbn_code\": \"ABP\",\n \"code\": \"ABP\",\n \"name\": \"Access Bank\"\n },\n {\n \"cbn_code\": \"DBP\",\n \"code\": \"DBP\",\n \"name\": \"Diamond Bank\"\n },\n {\n \"cbn_code\": \"ECO\",\n \"code\": \"ECO\",\n \"name\": \"Ecobank\"\n },\n {\n \"cbn_code\": \"FBP\",\n \"code\": \"FBP\",\n \"name\": \"Fidelity Bank\"\n },\n {\n \"cbn_code\": \"SBP\",\n \"code\": \"SBP\",\n \"name\": \"First\"\n },\n {\n \"cbn_code\": \"FBN\",\n \"code\": \"FBN\",\n \"name\": \"First Bank\"\n },\n {\n \"cbn_code\": \"GTB\",\n \"code\": \"GTB\",\n \"name\": \"Guarantee Trust Bank\"\n },\n {\n \"cbn_code\": \"KSB\",\n \"code\": \"KSB\",\n \"name\": \"Keystone Bank\"\n },\n {\n \"cbn_code\": \"QUICKTELLER\",\n \"code\": \"QUICKTELLER\",\n \"name\": \"QUICKTELLER\"\n },\n {\n \"cbn_code\": \"SKYE\",\n \"code\": \"SKYE\",\n \"name\": \"Skye Bank\"\n },\n {\n \"cbn_code\": \"JAIZ\",\n \"code\": \"JAIZ\",\n \"name\": \"Test Bank\"\n },\n {\n \"cbn_code\": \"IBTC\",\n \"code\": \"IBTC\",\n \"name\": \"Test USSD\"\n },\n {\n \"cbn_code\": \"UBP\",\n \"code\": \"UBP\",\n \"name\": \"Test USSD\"\n },\n {\n \"cbn_code\": \"WEMA\",\n \"code\": \"WEMA\",\n \"name\": \"Test USSD\"\n },\n {\n \"cbn_code\": \"HBP\",\n \"code\": \"HBP\",\n \"name\": \"Test USSD\"\n },\n {\n \"cbn_code\": \"FCMB\",\n \"code\": \"FCMB\",\n \"name\": \"Test USSD\"\n },\n {\n \"cbn_code\": \"UBN\",\n \"code\": \"UBN\",\n \"name\": \"Union Bank\"\n },\n {\n \"cbn_code\": \"UBA\",\n \"code\": \"UBA\",\n \"name\": \"United Bank for Africa\"\n },\n {\n \"cbn_code\": \"ZIB\",\n \"code\": \"ZIB\",\n \"name\": \"Zenith Bank\"\n }\n ]\n}"}],"_postman_id":"f0f127d0-565a-4249-af6a-77e0b000bf09"},{"name":"Get USSD Bank By Code","id":"194236d5-6f4f-4212-8d18-75b4fe75fede","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-api-key","value":"{{X-API-Key}}","type":"text"}],"url":"{{BASE_URL}}/payments/ussd/banks/:code","urlObject":{"path":["payments","ussd","banks",":code"],"host":["{{BASE_URL}}"],"query":[],"variable":[{"type":"any","value":"HBP","key":"code"}]}},"response":[{"id":"cdfe8838-48d8-47a9-b1b3-760c3e03f763","name":"Get USSD Bank By Code","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{X-API-Key}}","type":"text"}],"url":{"raw":"{{BASE_URL}}/payments/ussd/banks/:code","host":["{{BASE_URL}}"],"path":["payments","ussd","banks",":code"],"variable":[{"key":"code","value":"HBP"}]}},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Security-Policy","value":"default-src 'self';script-src 'self' 'unsafe-inline' https://cdn.example.com;style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;img-src 'self' data: https://*.example.com;font-src 'self' https://fonts.gstatic.com;connect-src 'self' https://api.example.com;frame-ancestors 'none';"},{"key":"Permissions-Policy","value":"geolocation=(), microphone=(), camera=()"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Vary","value":"Origin"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Date","value":"Wed, 17 Sep 2025 08:49:15 GMT"},{"key":"Content-Length","value":"124"},{"key":"Content-Type","value":"text/plain; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\"success\":true,\"message\":\"USSD Bank successfully retrieved\",\"data\":{\"name\":\"Heritage Bank\",\"code\":\"HBP\",\"cbn_code\":\"HBP\"}}\n"}],"_postman_id":"194236d5-6f4f-4212-8d18-75b4fe75fede"}],"id":"5fe97991-757e-46dc-a26a-65435f9b78cd","description":"Handles payments via USSD codes. This method allows users to pay without using cards, typically on mobile phones that support USSD.
\n","_postman_id":"5fe97991-757e-46dc-a26a-65435f9b78cd"},{"name":"Bank Transfer (dynamic virtual account)","item":[{"name":"Generate Virtual Account (Dynamic)","id":"33bc77a6-b4e1-4127-9dc9-1a8d497dc14c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"amount\": \"100\",\r\n \"currency_code\": \"566\",\r\n \"provider\": \"WEMA\", \r\n \"transaction_reference\": \"TX3XIW7WYY11QQQP97UJ22IJO270\",\r\n \"metadata\": {\r\n \"someData\": \"some kind of object\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/virtual-account/generate","description":"Generates a unique account number for a user to receive payments.
\n","urlObject":{"path":["payments","virtual-account","generate"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[{"id":"0e1509af-9e89-41ac-887f-750b9da26336","name":"New Request","originalRequest":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"amount\": \"10000\",\r\n \"currency_code\": \"566\",\r\n \"provider\": \"WEMA\", // OPTIONAL\r\n \"transaction_reference\": \"bn1yy2222z2aAaz\",\r\n \"metadata\": {\r\n \"someData\": \"some kind of object\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/vitual-acccount/generate"},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Security-Policy","value":"default-src 'self';script-src 'self' 'unsafe-inline' https://cdn.example.com;style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;img-src 'self' data: https://*.example.com;font-src 'self' https://fonts.gstatic.com;connect-src 'self' https://api.example.com;frame-ancestors 'none';"},{"key":"Permissions-Policy","value":"geolocation=(), microphone=(), camera=()"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Vary","value":"Origin"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Date","value":"Thu, 18 Sep 2025 10:36:07 GMT"},{"key":"Content-Length","value":"284"},{"key":"Content-Type","value":"text/plain; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\"success\":true,\"message\":\"Virtual account created\",\"data\":{\"account_name\":\"Quickteller Business Payment\",\"account_number\":\"7610665773\",\"amount\":10000,\"bank_name\":\"Wema Bank\",\"provider\":\"WEMA\",\"response_code\":\"Z0\",\"transaction_reference\":\"bn1yy2222z2aAaz\",\"validity_period_mins\":30}}\n"}],"_postman_id":"33bc77a6-b4e1-4127-9dc9-1a8d497dc14c"}],"id":"58ceeeca-75e9-4115-b1f4-50cbe9281e7b","description":"Handles bank transfer payments using dynamically generated account numbers. Each user gets a unique account to deposit funds.
\n","_postman_id":"58ceeeca-75e9-4115-b1f4-50cbe9281e7b"},{"name":"Initiate Payment Page","id":"84d50c8a-34c2-4d77-b46a-73ab8b482265","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-api-key","value":"ftsk_9f5854ee670011cc78d363d3d7781c2bb1051422b4fe9690024f8e6bde6287dc_2904748957","type":"text"}],"body":{"mode":"raw","raw":"{\n \"amount\": 5000,\n \"currency\": \"NGN\",\n \"reference\": \"order_12S3458SS9118701098990\",\n \"allowed_methods\": [\"card\", \"ussd\", \"qrcode\", \"bank_transfer\"],\n \"success_url\": \"https://yoursite.com/payment/success\",\n \"cancel_url\": \"https://yoursite.com/payment/cancel\"\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/payments/checkout","urlObject":{"path":["payments","checkout"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"84d50c8a-34c2-4d77-b46a-73ab8b482265"}],"id":"21eb1361-bd62-4f25-a243-886b3580e1c8","description":"This API allows processing of payments via Card, USSD, and Bank Transfer (Dynamic Account). Each folder represents a payment method, with multiple endpoints for handling transactions, approvals, and verification.
\nFinecore Checkout makes it easy for developers and businesses to accept payments through a simple, secure, and customizable modal β no complex setup required.
\nYou can integrate it in minutes by embedding a single script and initializing the payment modal with your API key and transaction details.
\nCopy and paste this script inside your HTML before the closing tag:
\n<script src=\"https://checkout.finecore.co/finecore_pay.js\"></script>\n\nThis script automatically attaches the FinecorePay object to your window.
Add the following JavaScript code to your site or app:
\n<script>\n function payWithFinecore() {\n window.FinecorePay.open({\n key: \"flk_xxxxxxxxxxxxxx\", // Replace with your Finecore public key\n amount: 5000, // Amount in kobo (β¦50.00)\n reference: \"FC_\" + new Date().getTime(), // Unique transaction reference\n metadata: {\n name: \"John Doe\",\n phone: \"+2348012345678\",\n email: \"customer@example.com\",\n },\n onSuccess: function (response) {\n console.log(\"Payment successful:\", response);\n alert(\"Payment successful! Reference: \" + response.reference);\n },\n onClose: function () {\n console.log(\"Payment modal closed.\");\n },\n });\n }\n</script>\n\n<button onclick=\"payWithFinecore()\">Pay Now</button>\n\nWhen the user clicks the Pay Now button, the Finecore Checkout modal opens, allowing them to complete payment using their preferred method.
\nThe FinecorePay script securely loads your payment modal.
The modal connects to Finecore servers and processes payments via your provided key and reference.
Once payment is completed, the onSuccess callback returns the transaction details.
You can verify the payment on your backend using the reference ID.
\nThe Get Quote Requirement defines the validation schema and rules for all quote requests before any pricing or exchange rate calculation is performed.
\nIt ensures that every request entering the quote system is structurally valid, complete, and allowed under system rules.
\nDefine required and optional input fields for quote requests
\nValidate request structure before processing
\nEnforce business rules per transfer type
\nPrevent invalid or unsupported quote requests
\nDefines the required fields based on transfer context:
\nSource asset / currency
\nDestination asset / currency
\nAmount (source or destination-based)
\nTransfer type (fiat β stablecoin combinations)
\nDestination method (bank, wallet, card)
\nCountry or region (for fiat rails)
\nCustomer and account identifiers (where required)
\nAsset/currency must be supported
\nRequired fields must be present per transfer type
\nAmount must respect min/max limits
\nDestination format must match method (bank, wallet, card, wallet address)
\nRegion-specific restrictions must be enforced
\nPayment method must be valid for selected currency and rail
\nFiat β Fiat: requires currencies + bank/card method + country
\nFiat β Stablecoin: requires fiat currency + stablecoin asset + wallet address
\nStablecoin β Fiat: requires stablecoin asset + fiat currency + bank account
\nStablecoin β Stablecoin: requires source + destination wallet addresses
\nThis layer acts as the strict validation contract for all quote requests before pricing begins.
\n","urlObject":{"path":["stablecoin","requirements","USDC-USD"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"8c35a902-8a87-4f48-96ce-027973757a76"},{"name":"Initiate Transfer","id":"7cfa5649-17f4-45d0-90f3-6dbcaae915ac","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customer_id\": \"7dd66395-94e9-480f-b45e-16dd3a9a0714\",\r\n \"destination\": {\r\n \"beneficiary_info\": {\r\n \"beneficiary_address\": {\r\n \"city\": \"Abuja\",\r\n \"country\": \"NG\",\r\n \"postal_code\": \"900001\",\r\n \"state_province\": \"FCT\",\r\n \"street\": \"12 Ahmadu Bello Way\"\r\n },\r\n \"beneficiary_email\": \"jibrilmohammed39@gmail.com\",\r\n \"beneficiary_name\": \"Jibril Mohammed\"\r\n },\r\n \"is_self_transfer\": false,\r\n \"payout_instrument\": {\r\n \"phone_number\": \"0208953433\",\r\n \"network_provider\": \"VODAFONE\"\r\n \r\n },\r\n \"transfer_purpose\": \"SALARY\"\r\n },\r\n \"quote_id\": \"141a4682-7a16-4ea4-a220-7343f71fcead\",\r\n \"reference\": \"SALwQAqsqj1Y_qqNw0c1\",\r\n \"source\": {\r\n \"payment_instrument\": {\r\n \"account_number\": \"8034074748\",\r\n \"bank_code\": \"100004\"\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/stablecoin/transfers/initiate","description":"The Initiate Transfer service is responsible for executing transfers after a quote has been validated and accepted.
\nIt orchestrates the movement of funds across fiat rails, stablecoin networks, and internal ledger systems.
\nValidate quote and transfer eligibility
\nInitiate transfer processing
\nCoordinate with blockchain and fiat providers
\nExecute asset movement
\nTrack transfer lifecycle and status
\nHandle retries and failure recovery
\nStablecoin β Stablecoin
\nStablecoin β Fiat
\nFiat β Stablecoin
\nFiat β Fiat
\nSupported destinations include:
\nBlockchain wallet addresses
\nLocal bank accounts
\nForeign currency bank accounts (USD only)
\nLinked customer payment methods
\nTransfers may execute across supported blockchain networks such as:
\nSolana
\nEthereum
\nTron
\nAvailability depends on selected asset and provider support.
\nForeign currency transfers currently support:
\nThe Get Transfer Purposes service retrieves the list of supported transfer reasons or purposes available for a transaction.
\nThese purposes are primarily used for compliance, regulatory reporting, and transaction classification.
\nRetrieve supported transfer purposes
\nSupport compliance and AML workflows
\nValidate transfer-purpose eligibility for specific routes
\nStandardize transaction categorization
\nExamples may include:
\nFamily support
\nSalary payment
\nBusiness payment
\nInvestment
\nSavings
\nGoods and services
\nEducation
\nMedical expenses
\nAvailable options may vary depending on:
\nCurrency
\nCountry
\nTransfer route
\nPayment provider requirements
\nTransfer purposes may be required for:
\nFiat transfers
\nCross-border payments
\nForeign currency transactions
\nRegulatory reporting flows
\nForeign currency-related transfer purposes currently apply to:
\nThe Get Quote service generates real-time pricing and conversion information for a validated transfer request.
\nIt calculates exchange rates, estimated destination amounts, and applicable fees across fiat and stablecoin rails.
\nRetrieve exchange rates
\nCalculate destination amounts
\nApply FX spreads and fees
\nEstimate network and processing costs
\nReturn time-bound pricing information
\nA generated quote may include:
\nSource amount
\nDestination amount
\nExchange rate
\nFee breakdown
\nTransfer route
\nQuote expiry time
\nStablecoin β Stablecoin
\nStablecoin β Fiat
\nFiat β Stablecoin
\nFiat β Fiat
\nForeign currency pricing currently supports:
\nThe Verify Mobile Money Transfer endpoint is used to complete a GHS Mobile Money on-ramp transfer after it has been initiated.
\nIt handles the final authorization step required by the mobile money provider, which may be either:
\nOTP verification, or
\nPIN confirmation (prompted on the userβs mobile device, not submitted in the request body)
\nComplete a previously initiated Mobile Money transfer
\nHandle provider-based authentication flow
\nFinalize GHS on-ramp settlement
\nConfirm user authorization securely
\nUser initiates a Mobile Money transfer (GHS on-ramp)
\nSystem returns:
\nreference
next_step
Provider determines verification method:
\nOTP β sent to userβs phone via SMS
PIN β user is prompted on mobile device to enter PIN (not sent in API request)
User completes verification using this endpoint
\nTransfer is finalized or rejected based on provider response
\nIf next_step = PIN:
The user is prompted directly on their mobile money app/device
\nThe PIN is NOT included in the API request
\nThe system only waits for provider confirmation after user enters PIN on device
\nThe initiation response defines how verification is handled:
\nnext_step = OTP
next_step = PIN
```json
{
\"reference\": \"tx_ref_123456\",
\"otp\": \"839201\"
}
The Simulate Transfer endpoint is used to mock or test the lifecycle state changes of a transfer for internal testing, sandbox environments, or provider simulation flows.
\nIt allows developers to manually trigger different transfer states using an existing transfer reference.
\nSimulate transfer state transitions in non-production environments
\nTest downstream systems (ledger, notifications, reconciliation)
\nValidate integration flows without real money movement
\nSupport QA and development testing scenarios
\n```json
{
\"reference\": \"SALARY_JAN_a20E2yqcqsq2qsucq\",
\"action\": \"PAID\"
}
The Transfers folder contains the orchestration and execution layer for all fiat and stablecoin value movement within the platform.
\nIt coordinates transfers across supported blockchain networks, fiat payment rails, liquidity providers, and internal ledger systems while ensuring compliance, validation, and reliable settlement.
\nThe system supports:
\nFiat β Stablecoin (On-ramp)
\nStablecoin β Fiat (Off-ramp)
\nStablecoin β Stablecoin (On-chain)
\nFiat β Fiat transfers
\nQuote validation and generation
\nTransfer initiation and execution
\nStablecoin and fiat settlement coordination
\nFX conversion and pricing
\nBlockchain routing and confirmation tracking
\nBank and wallet destination validation
\nCompliance and transfer-purpose enforcement
\nIntegration with payment providers and blockchain networks
\nCurrently supported stablecoin assets include:
\nUSDC
\nUSDT
\nCNGN
\nAvailability depends on:
\nSelected blockchain network
\nTransfer type
\nProvider support
\nSupported fiat currencies currently include:
\nNGN (Nigerian Naira)
\nGHS (Ghanaian Cedi)
\nUSD
\nEUR
\nBRL
\nMXN
\nHKD
\nCNY
\nCOP
\nINR
\nAED
\nSGD
\nJPY
\nPHP
\nAvailability depends on:
\nPayment rail support
\nTransfer route
\nRegion and provider restrictions
\nSupported local fiat payment methods include:
\nBank Transfer
\nMobile Money
\nACH
\nWire Transfer
\nSEPA
\nPIX
\nSPEI
\nCHATS
\nInstaPay
\nPesoNet
\nRTP
\nFedWire
\nAvailability varies by country and currency.
\nSupported blockchain networks currently include:
\nEthereum
\nSolana
\nPolygon
\nAvalanche
\nArbitrum
\nOptimism
\nStellar
\nTron
\nTON
\nBase
\nCelo
\nBEP20
\nAvailability depends on the selected asset.
\nForeign currency transfers currently support:
\nUSD on-ramp flows
\nUSD wire payouts for selected regions
\nAdditional foreign currency support may depend on provider availability and payment rail compatibility.
\nThe Transfers folder includes:
\nGet Quote Requirement
\nGet Quote
\nInitiate Transfer
\nGet Transfer Purposes
\nSupported Assets & Currency Resolution
\nSupported Chain Resolution
\nBank & Payment Method Management
\nThe Create Customer service is responsible for onboarding and registering a new customer within the platform.
\nIt creates a unique customer identity that can be used across transfers, wallets, payment methods, stablecoin operations, and compliance workflows.
\nCreate a new customer profile
\nValidate customer information before creation
\nEnforce uniqueness constraints
\nInitialize customer identity for downstream financial services
\nStore KYC-related metadata for compliance workflows
\n```json
{
\"first_name\": \"Krystal\",
\"last_name\": \"Wilcher\",
\"email\": \"big@gmail.com\",
\"country_code\": \"US\",
\"phone_number\": \"708-916-8499\",
\"birth_date\": \"2002-06-30\",
\"kyc_description\": \"US stablecoin customer\"
}
The Customer folder contains all services responsible for managing customer identity, onboarding, and profile data within the platform.
\nIt acts as the core identity and compliance layer, ensuring every user interacting with financial services is properly registered, validated, and linked to required regulatory workflows.
\nCustomer onboarding and identity creation
\nCustomer profile storage and retrieval
\nExtended customer details management
\nCompliance and KYC enforcement
\nLinking customers to financial services (transfers, wallets, cards, bank accounts)
\nManaging customer lifecycle and status
\nFor foreign currency customers, the system enforces additional compliance requirements:
\nThe customer must undergo KYC verification
\nThe customer must accept a mandatory agreement
\nThe agreement URL is returned after customer creation
\nThe customer must accept the agreement before being allowed to perform foreign currency operations (e.g. USD on-ramp/off-ramp flows)
\nThe Customer folder includes:
\nCreate Customer
\nFetch Customer
\nFetch Customer Details
\nCustomer validation utilities
\nIf a customer is involved in foreign currency operations, the system automatically triggers KYC requirements
\nThe agreement URL returned during creation is mandatory for onboarding completion
\nFailure to accept the agreement blocks access to foreign currency transfer features
\nThe Customer folder is the identity and compliance gateway for the platform.
\nIt ensures:
\nEvery user is properly registered
\nForeign currency users complete KYC
\nRequired agreements are accepted before enabling regulated financial operations
\nThe Link Card service allows customers to attach a debit or credit card to their profile for fiat funding and payment operations.
\nIt enables card-based deposits and, where supported, withdrawals through integrated payment providers.
\nLink customer card to account
\nValidate card details with payment provider
\nTokenize and securely store card references
\nEnable card-based fiat transactions
\nSupport recurring or one-time payments
\nRedirect URL
\nCustomer ID
\nCard must pass provider validation (auth/tokenization)
\nCard must be supported in the customerβs region
\nExpiry date must be valid
\nCustomer must be active and verified where required
\nFiat deposits
\nFiat on-ramp (where enabled)
\nRecurring payments
\nWallet funding
\nThis service securely links a customerβs card for use in fiat payment flows within the platform.
\n","urlObject":{"path":["stablecoin","cards","link"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[{"id":"b09b4484-0356-4fd5-bb95-b7f6fbdf415f","name":"Link Customer Card","originalRequest":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customer_id\": \"186f303f-ea47-468b-bb51-ed4f166160ee\",\r\n \"redirect_url\": {\r\n \"success\": \"https://yourapp.com/card/success\",\r\n \"failed\": \"https://yourapp.com/card/failed\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/stablecoin/cards/link"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Permissions-Policy","value":"geolocation=(), microphone=(), camera=()"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Vary","value":"Origin"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Date","value":"Sun, 24 May 2026 00:46:49 GMT"},{"key":"Content-Length","value":"849"},{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"Card linked successfully\",\n \"data\": {\n \"card_id\": \"card_L6Gb43Wpjr7hwlUZL1y7lmqW2kTC5LqUvWlyVJW5\",\n \"status\": \"PENDING\",\n \"enabled\": false,\n \"restricted\": false,\n \"url\": \"https://link-sandbox.owlpay.com/crb/card/iframe?encoded=eyJpZnJhbWVfc3JjIjoiaHR0cHM6XC9cL3AycGNyZWRpdGNhcmRpZnJhbWVzYW5kYm94LmNyYmNvcy5jb21cLz9jcmVhdGVkQXQ9MjAyNi0wNS0yM1QyMDo0Njo0OS44Njc1NDY1WiZkb21haW49aHR0cHM6XC9cL2xpbmstc2FuZGJveC5vd2xwYXkuY29tJmV4cGlyZXNBdD0yMDI2LTA1LTIzVDIwOjUxOjQ5Ljg2NzU0NjVaJm90Y0lkPTliNzIxZGRmLTVmMGMtNGE2OC1hNWRiLTRlZDEwOWZiNWM1NiZ0ZW1wbGF0ZUlkPWMzMzYwYWJmLWY1N2EtNDk1Yy1kNGQzLTA4ZGU3YTg5ZDk0NSZmaXJzdEFuZExhc3ROYW1lUHJvdmlkZWQ9ZmFsc2UiLCJyZWRpcmVjdF9zdWNjZXNzIjoiaHR0cHM6XC9cL3lvdXJhcHAuY29tXC9jYXJkXC9zdWNjZXNzIiwicmVkaXJlY3RfZmFpbGVkIjoiaHR0cHM6XC9cL3lvdXJhcHAuY29tXC9jYXJkXC9mYWlsZWQifQ%3D%3D\",\n \"created_at\": \"2026-05-24T00:46:49+00:00\"\n }\n}"}],"_postman_id":"fe6c7389-7d7c-47a3-8a4f-21df7793c899"},{"name":"List Customer Card","id":"6196b5c9-dc65-43ae-ba5f-186e8ba9ef22","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"description":"The List Customer Cards service retrieves all cards linked to a customer profile.
\nIt provides visibility into active, inactive, or restricted card payment methods associated with the customer.
\nRetrieve all cards linked to a customer
\nProvide card metadata for display and selection
\nSupport payment method selection during transfers
\nIndicate card status (active, inactive, failed, restricted)
\nCard identifier (tokenized reference)
\nCard type (debit/credit)
\nCard brand (e.g. Visa, Mastercard)
\nExpiry date (masked)
\nCard status
\nLinked customer ID
\nCustomer must exist
\nCustomer must have linked cards
\nAccess must be authorized
\nThis service provides a list of all customer-linked cards for use in fiat payment flows.
\n","urlObject":{"query":[],"variable":[]},"url":""},"response":[],"_postman_id":"6196b5c9-dc65-43ae-ba5f-186e8ba9ef22"},{"name":"Get List of Banks","id":"5efc4b91-88ec-4b6f-95a7-0d4110672e81","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"url":"{{BASE_URL}}/stablecoin/transfers/banks/list/:country","description":"The Get List of Banks service retrieves all supported banks for local fiat currency transactions.
\nIt is used to validate bank account details and enable payout routing within supported countries.
\nRetrieve list of supported banks per country or currency
\nSupport bank selection during account linking
\nEnable validation of bank codes and names
\nProvide banking metadata for fiat transfer routing
\nNigeria (NGN)
\nGhana (GHS)
\nAdditional regions may be supported depending on provider availability.
\nBank name
\nBank code
\nCountry
\nSupported currency
\nBank identifier for routing
\nUsed for:
\nLinking bank accounts
\nValidating beneficiary details
\nFiat payout processing
\nTransfer routing selection
\nThis service provides the authoritative list of supported banks for local currency fiat operations within the platform.
\n","urlObject":{"path":["stablecoin","transfers","banks","list",":country"],"host":["{{BASE_URL}}"],"query":[],"variable":[{"type":"any","value":"GH","key":"country"}]}},"response":[{"id":"07e75738-5f35-46fa-b231-13841bbcf112","name":"Get List of Banks (NG)","originalRequest":{"method":"GET","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"url":{"raw":"{{BASE_URL}}/stablecoin/transfers/banks/list/:country","host":["{{BASE_URL}}"],"path":["stablecoin","transfers","banks","list",":country"],"variable":[{"key":"country","value":"NG"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Permissions-Policy","value":"geolocation=(), microphone=(), camera=()"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Vary","value":"Origin"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Date","value":"Mon, 04 May 2026 13:50:51 GMT"},{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"banks retrieved successfully\",\n \"data\": [\n {\n \"code\": \"120001\",\n \"name\": \"9 Payment Service Bank\"\n },\n {\n \"code\": \"090270\",\n \"name\": \"AB Microfinance Bank\"\n },\n {\n \"code\": \"070010\",\n \"name\": \"Abbey Mortgage Bank\"\n }\n ]\n}"},{"id":"e9c60113-1eca-479e-b76b-33513580d89d","name":"Get List of Banks (GH)","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{BASE_URL}}/stablecoin/transfers/banks/list/:country","host":["{{BASE_URL}}"],"path":["stablecoin","transfers","banks","list",":country"],"variable":[{"key":"country","value":"GH"}]}},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"banks retrieved successfully\",\n \"data\": [\n {\n \"code\": \"0009\",\n \"name\": \"TIGO\"\n },\n {\n \"code\": \"0006\",\n \"name\": \"VODAFONE\"\n },\n {\n \"code\": \"0004\",\n \"name\": \"MTN\"\n },\n {\n \"code\": \"0005\",\n \"name\": \"AIRTEL\"\n }\n ]\n}"}],"_postman_id":"5efc4b91-88ec-4b6f-95a7-0d4110672e81"},{"name":"Link Bank Account","id":"bc07caf2-bf4a-43df-80f7-2ef362b801a2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customer_id\": \"7dd66395-94e9-480f-b45e-16dd3a9a0714\",\r\n \"redirect_url\": {\r\n \"success\": \"https://yourapp.com/success\",\r\n \"failed\": \"https://yourapp.com/failed\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/stablecoin/transfers/banks/link","description":"The Link Bank Account service allows customers to attach a bank account to their profile for fiat payouts and deposits.
\nIt enables the system to route funds directly to supported banking networks across local and international rails.
\nLink a bank account to a customer profile
\nValidate bank details before saving
\nSupport local and foreign bank account linking
\nEnable payout routing for fiat transfers
\nStore bank metadata for future transactions
\nRedirect URL
\nCustomer ID
\nBank must be supported in the selected region
\nAccount number must follow country-specific format rules
\nAccount must be valid and reachable via provider rails
\nCustomer must exist and be active
\nCurrency must be supported for bank linkage
\nLocal currencies (e.g. NGN, GHS) supported via local banks
\nForeign currency support is limited to USD onboarding only
\nThis service links a customer to a bank account, enabling fiat payouts and deposits through supported banking rails.
\n","urlObject":{"path":["stablecoin","transfers","banks","link"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"bc07caf2-bf4a-43df-80f7-2ef362b801a2"}],"id":"fe04643d-8f1a-4a02-abd6-4ccd222d5547","description":"The Bank Accounts & Cards folder manages all customer-linked payment instruments used for fiat transactions within the platform.
\nIt provides the infrastructure for linking, retrieving, and managing bank accounts and cards, enabling seamless fiat deposits, payouts, and transfer operations.
\nThis folder primarily supports fiat rails, including local currency payments and foreign currency (USD) onboarding flows.
\nLinking customer bank accounts
\nLinking customer debit/credit cards
\nManaging and storing customer payment instruments
\nRetrieving linked payment methods for transactions
\nFetching supported banks for local fiat rails
\nEnabling payout and deposit routing through fiat providers
\nEnsuring validation and compliance of payment methods
\nFiat β Fiat transfers
\nFiat β Stablecoin on-ramp
\nStablecoin β Fiat off-ramp
\nLocal currency payouts (NGN, GHS, etc.)
\nForeign currency onboarding (USD only)
\nLocal bank transfers (country-specific)
\nCard payments (where enabled)
\nUSD bank onboarding (foreign currency support)
\nProvider-based fiat rails (ACH, SEPA, etc. depending on region)
\nThe Bank Accounts & Cards folder is the fiat payment instrument layer, responsible for managing all customer-linked funding and payout methods across supported fiat currencies and regions.
\n","_postman_id":"fe04643d-8f1a-4a02-abd6-4ccd222d5547"},{"name":"Wallet","item":[{"name":"Create Wallet","id":"581a504b-b5c3-47fa-b9df-fa706c53b801","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"chain\": \"solana\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/stablecoin/wallets","urlObject":{"path":["stablecoin","wallets"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"581a504b-b5c3-47fa-b9df-fa706c53b801"},{"name":"Get Wallet Balance","id":"a3007711-6984-4638-b8ce-13897ba621b3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/stablecoin/wallets/balance/:chain","urlObject":{"path":["stablecoin","wallets","balance",":chain"],"host":["{{BASE_URL}}"],"query":[],"variable":[{"type":"any","value":"polygon","key":"chain"}]}},"response":[],"_postman_id":"a3007711-6984-4638-b8ce-13897ba621b3"},{"name":"Get Wallet By Address","id":"326abdc1-c8f3-422f-9cdc-4d9043a706d9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"urlObject":{"query":[],"variable":[]},"url":""},"response":[],"_postman_id":"326abdc1-c8f3-422f-9cdc-4d9043a706d9"}],"id":"9d30b0ee-9532-484e-92dd-49c90f5cb178","_postman_id":"9d30b0ee-9532-484e-92dd-49c90f5cb178","description":""}],"id":"d58784fe-e7e9-4cea-a8fe-4f2e64c91710","description":"This folder contains all endpoints related to stablecoin operations on the platform. It supports blockchain-based financial transactions, enabling users and merchants to send, receive, store, and manage stablecoin assets seamlessly.
\nWallet creation and management
\nStablecoin deposits and withdrawals
\nInternal and external transfers
\nBalance and transaction history retrieval
\nBlockchain transaction status tracking
\nAddress generation and validation (where applicable)
\nThe Stablecoin module enables fast, secure, and programmable digital asset movement while maintaining a stable value equivalent to fiat currencies. It is designed for cross-border payments, treasury operations, and digital asset settlement flows.
\nCrypto-to-crypto transfers
\nFiat-backed stablecoin settlements
\nMerchant payouts in stable assets
\nCross-border remittances
\nDescription:
Uploads a supporting document for the SME onboarding application β business certificate, operating licence, company logo, memorandum, or similar.
Important: All document must be Notarized by a Pulic Notary Officer
\nEncode the file as a base64 string in media_base64.
Common media_type values:
What you get back:
file_id β save this in case you need to remove the document via DELETE /sme/media/remove
Request Body:
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"media_base64\": \"<base64_encoded_pdf_or_image>\",\n \"media_type\": \"INCORPORATION_CERTIFICATE\",\n \"content_type\": \"pdf\" // \"pdf\" or \"image\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME media uploaded successfully\",\n \"data\": {\n \"file_id\": \"FILE-001\"\n }\n}\n\nDescription:
\nRemoves a previously uploaded document from an SME onboarding application. Use this if you uploaded the wrong file and need to replace it. \nο»Ώ
\nThe file_id comes from the POST /sme/media/upload response. You can also find all file IDs in the onboarding_media_infos array returned by GET /sme/onboarding/info. \nο»Ώ
\nAfter removing, re-upload the correct file via POST /sme/media/upload.
\nRequest Body:
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"file_id\": \"FILE-001\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME media removed successfully\",\n \"data\": null\n}\n\nDescription:
Uploads a supporting document for the SME onboarding application β business certificate, operating licence, company logo, memorandum, or similar.
Important: All document must be Notarized by a Pulic Notary Officer
\nEncode the file as a base64 string in media_base64.
Common media_type values:
What you get back:
file_id β save this in case you need to remove the document via DELETE /sme/media/remove
Request Body:
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"media_base64\": \"<base64_encoded_pdf_or_image>\",\n \"media_type\": \"INCORPORATION_CERTIFICATE\",\n \"content_type\": \"pdf\" // \"pdf\" or \"image\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME media uploaded successfully\",\n \"data\": {\n \"file_id\": \"FILE-001\"\n }\n}\n\nDescription:
\nRemoves a previously uploaded document from an SME onboarding application. Use this if you uploaded the wrong file and need to replace it. \nο»Ώ
\nThe file_id comes from the POST /sme/media/upload response. You can also find all file IDs in the onboarding_media_infos array returned by GET /sme/onboarding/info. \nο»Ώ
\nAfter removing, re-upload the correct file via POST /sme/media/upload.
\nRequest Body:
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"file_id\": \"FILE-001\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME media removed successfully\",\n \"data\": null\n}\n\nDescription:
\nAdds a shareholder to an SME onboarding application. Required for LLCs, Partnerships, and NGOs (business types 2, 3, 4) before submitting for review. Not needed for Sole Proprietorships. \nο»Ώ
\nSend EITHER the Individual object OR the Organisation object β never both in the same request. \nο»Ώ
\nFor Individual shareholders, provide:
id_type, id_number, gender, country_code, mobile, first_name, last_name, tin
base64 document files: id_front_side_file, id_back_side_file, selfie_file, tin_file
\ncorresponding MIME types for each file
\nο»Ώ\nFor Organisation shareholders, provide:
company_name, registration_file (base64), registration_file_type \nο»Ώ
What you get back:
member_id β populated for individual shareholders
company_id β populated for organisation shareholders
Save these IDs to use with DELETE /sme/shareholder/remove.
Request Body (Individual shareholder):
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"Individual\": {\n \"id_type\": \"NATIONAL_ID\",\n \"id_number\": \"55544433321\",\n \"gender\": 0,\n \"email\": \"ngozi.okonkwo@example.ng\",\n \"country_code\": \"234\",\n \"mobile\": \"+2348099887766\",\n \"first_name\": \"Ngozi\",\n \"middle_name\": \"Chidinma\",\n \"last_name\": \"Okonkwo\",\n \"tin\": \"55544433-0001\",\n \"id_front_side_file\": \"<base64_encoded_image>\",\n \"id_front_side_file_type\": \"image\", // pdf or image\n \"id_back_side_file\": \"<base64_encoded_image>\",\n \"id_back_side_file_type\": \"image\", // pdf or image\n \"selfie_file\": \"<base64_encoded_image>\",\n \"selfie_file_type\": \"image\", // pdf or image\n \"tin_file\": \"<base64_encoded_image>\",\n \"tin_file_type\": \"image\" // pdf or image\n }\n}\n\nRequest Body (Organisation shareholder):
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"Organisation\": {\n \"company_name\": \"Okonkwo Holdings Limited\",\n \"registration_file\": \"<base64_encoded_pdf>\",\n \"registration_file_type\": \"pdf\"\n }\n}\n\nSuccess Response (201):
\n{\n \"success\": true,\n \"message\": \"Shareholder added successfully\",\n \"data\": {\n \"member_id\": \"M-001\",\n \"company_id\": \"\"\n }\n}\n\nError Responses:
\n// 400 β Neither provided\n{\n \"success\": false,\n \"message\": \"either Individual or Organisation shareholder info must be provided\",\n \"data\": null\n}\n// 400 β Both provided\n{\n \"success\": false,\n \"message\": \"only one of Individual or Organisation shareholder info may be provided\",\n \"data\": null\n}\n\nDescription:
\nRemoves a previously added shareholder from an SME onboarding application. \nο»Ώ
\nmember_id β the ID returned when the shareholder was added (member_id for individuals, company_id for organisations) \nο»Ώ
\nmember_type:
0 = Individual
1 = Organisation \nο»Ώ
After removing, re-add the correct shareholder via POST /sme/shareholder/add.
\nRequest Body:
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"member_id\": \"M-001\",\n \"member_type\": 0\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"Shareholder removed successfully\",\n \"data\": null\n}\n\nDescription:
\nAdds a shareholder to an SME onboarding application. Required for LLCs, Partnerships, and NGOs (business types 2, 3, 4) before submitting for review. Not needed for Sole Proprietorships. \nο»Ώ
\nSend EITHER the Individual object OR the Organisation object β never both in the same request. \nο»Ώ
\nFor Individual shareholders, provide:
id_type, id_number, gender, country_code, mobile, first_name, last_name, tin
base64 document files: id_front_side_file, id_back_side_file, selfie_file, tin_file
\ncorresponding MIME types for each file
\nο»Ώ\nFor Organisation shareholders, provide:
company_name, registration_file (base64), registration_file_type \nο»Ώ
What you get back:
member_id β populated for individual shareholders
company_id β populated for organisation shareholders
Save these IDs to use with DELETE /sme/shareholder/remove.
Request Body (Individual shareholder):
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"Individual\": {\n \"id_type\": \"NATIONAL_ID\",\n \"id_number\": \"55544433321\",\n \"gender\": 0,\n \"email\": \"ngozi.okonkwo@example.ng\",\n \"country_code\": \"234\",\n \"mobile\": \"+2348099887766\",\n \"first_name\": \"Ngozi\",\n \"middle_name\": \"Chidinma\",\n \"last_name\": \"Okonkwo\",\n \"tin\": \"55544433-0001\",\n \"id_front_side_file\": \"<base64_encoded_image>\",\n \"id_front_side_file_type\": \"image\", // pdf or image\n \"id_back_side_file\": \"<base64_encoded_image>\",\n \"id_back_side_file_type\": \"image\", // pdf or image\n \"selfie_file\": \"<base64_encoded_image>\",\n \"selfie_file_type\": \"image\", // pdf or image\n \"tin_file\": \"<base64_encoded_image>\",\n \"tin_file_type\": \"image\" // pdf or image\n }\n}\n\nRequest Body (Organisation shareholder):
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"Organisation\": {\n \"company_name\": \"Okonkwo Holdings Limited\",\n \"registration_file\": \"<base64_encoded_pdf>\",\n \"registration_file_type\": \"pdf\"\n }\n}\n\nSuccess Response (201):
\n{\n \"success\": true,\n \"message\": \"Shareholder added successfully\",\n \"data\": {\n \"member_id\": \"M-001\",\n \"company_id\": \"\"\n }\n}\n\nError Responses:
\n// 400 β Neither provided\n{\n \"success\": false,\n \"message\": \"either Individual or Organisation shareholder info must be provided\",\n \"data\": null\n}\n// 400 β Both provided\n{\n \"success\": false,\n \"message\": \"only one of Individual or Organisation shareholder info may be provided\",\n \"data\": null\n}\n\nDescription:
\nRemoves a previously added shareholder from an SME onboarding application. \nο»Ώ
\nmember_id β the ID returned when the shareholder was added (member_id for individuals, company_id for organisations) \nο»Ώ
\nmember_type:
0 = Individual
1 = Organisation \nο»Ώ
After removing, re-add the correct shareholder via POST /sme/shareholder/add.
\nRequest Body:
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"member_id\": \"M-001\",\n \"member_type\": 0\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"Shareholder removed successfully\",\n \"data\": null\n}\n\nDescription:
\nStarts the SME onboarding process and sends an OTP to the business owner. Always the first call in the SME flow.
\nbusiness_type values:
1 = Sole Proprietorship (single owner β no shareholders needed)
2 = LLC / Limited Company
3 = Partnership
4 = NGO / CBO
What you get back:
onboarding_request_id β your tracking ID for all subsequent SME steps. Save this.
After this call, confirm OTP via POST /onboarding/otp/confirm, then submit business details via POST /sme/onboarding/submit.
\n{\n \"country_code\": \"234\",\n \"mobile\": \"+2348055987654\",\n \"email\": \"info@deltafortytechltd.ng\",\n \"business_type\": 2,\n \"otp_type\": \"EMAIL\"\n}\n\n{\n \"success\": true,\n \"message\": \"SME onboarding application submitted successfully\",\n \"data\": {\n \"onboarding_request_id\": \"SME-20260628-DFT001\"\n }\n}\n\n// 400 β Invalid business_type\n{\n \"success\": false,\n \"message\": \"invalid Business type β must be 1, 2, 3, or 4\",\n \"data\": null\n}\n\nDescription:
\nChecks the review status of a submitted SME application. Poll this after calling POST /sme/onboarding/action with action: \"SUBMIT\".
\nThe same status codes as individual onboarding apply (0β9).
\nWhen approved, account_id is populated with the business's account number.
\nIf rejected, check reject_reason_msgs for details. Pull back, correct, and resubmit.
\nQuery Parameters:
\nonboarding_request_id=\"SME-20260628-DFT001\"\nbusiness_cer_no=\"RC347832\"\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME onboarding status retrieved successfully\",\n \"data\": {\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"onboarding_status\": \"7\",\n \"rejection_reason_ids\": [],\n \"reject_reason_msgs\": [],\n \"account_id\": \"3001122334\",\n \"account_type\": \"B001\",\n \"audit_time\": \"1751075200\"\n }\n}\n\nDescription:
\nRetrieves all information submitted so far for an SME onboarding request β business details, uploaded documents, shareholder list, and current status.
\nUse this to:
β Pre-populate an edit form before resubmission
β Verify all required documents have been uploaded
β Review the shareholders registered against the application
onboarding_media_infos β documents uploaded so far (file_id, file_url, media_type)
shareholders_member_infos β individual shareholders added
shareholders_company_infos β company shareholders added
Query Parameters:
\nonboarding_request_id=SME-20260628-DFT001\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME onboarding info retrieved successfully\",\n \"data\": {\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"business_name\": \"Delta Forty Tech Limited\",\n \"business_type\": 2,\n \"business_certificate_number\": \"RC-1234567\",\n \"tin\": \"23456789-0001\",\n \"business_address\": \"Plot 14, Adeola Odeku Street, Victoria Island, Lagos\",\n \"business_industry\": \"Technology\",\n \"specify_industry\": \"Fintech Infrastructure\",\n \"onboarding_media_infos\": [\n {\n \"file_id\": \"FILE-001\",\n \"file_url\": \"https://cdn.choicebank.com/uploads/deltaforty-cert.pdf\",\n \"media_type\": 0,\n \"content_type\": \"application/pdf\"\n }\n ],\n \"owner_full_name\": null,\n \"owner_id_number\": null,\n \"owner_id_type\": null,\n \"owner_birth_day\": null,\n \"kin_full_name\": null,kr\n \"kin_country_code\": null,\n \"kin_mobile\": null,\n \"kin_relationship\": null,\n \"shareholders_member_infos\": [\n {\n \"member_id\": \"M-001\",\n \"full_name\": \"Ngozi Okonkwo\",\n \"id_type\": \"NATIONAL_ID\",\n \"id_number\": \"55544433321\",\n \"tin\": \"55544433-0001\",\n \"country_code\": \"NG\",\n \"mobile\": \"+2348099887766\",\n \"id_front_file_url\": \"https://cdn.choicebank.com/uploads/ngozi-id-front.jpg\",\n \"id_back_file_url\": \"https://cdn.choicebank.com/uploads/ngozi-id-back.jpg\",\n \"selfie_file_url\": \"https://cdn.choicebank.com/uploads/ngozi-selfie.jpg\",\n \"kra_pin_file_url\": \"https://cdn.choicebank.com/uploads/ngozi-tin.jpg\"\n }\n ],\n \"shareholders_company_infos\": [],\n \"status\": 1,\n \"reject_reason_ids\": [],\n \"reject_reason_msgs\": [],\n \"create_time\": 1751068800,\n \"audit_time\": 0\n }\n}\n\nDescription:
ubmits detailed business information after OTP verification. Required fields vary by business_type.
Always required (all types):
onboarding_request_id, business_type, business_name, business_cer_num,
kra_pin, business_address, business_industry
Required for LLC / Partnership / NGO (types 2, 3, 4):
operating_mode:
1 = Singly (any one signatory can authorise)
2 = Either to Sign
3 = Any Two to Sign
4 = All of Us Jointly
Required for Sole Proprietorship only (type 1):
first_name, last_name, birthday, gender, id_number,
kin_full_name, kin_relationship, kin_country_code, kin_mobile
After submitting: upload documents β add shareholders (if applicable) β submit for review.
\nThe business_inductry field accepts an integer corresponding to the applicant's primary business industry.
The above example indicates that the business sector is Information and Communication Technology.
\nRequest Body (LLC example β business_type 2):
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"business_type\": 2,\n \"business_name\": \"Delta Forty Tech Limited\",\n \"business_cer_num\": \"RC-1234567\",\n \"tin\": \"23456789-0001\",\n \"operating_mode\": 3,\n \"business_address\": \"Plot 14, Adeola Odeku Street, Victoria Island, Lagos\",\n \"business_industry\": 5,\n \"specify_industry\": \"Fintech Infrastructure\"\n}\n\nRequest Body (Sole Proprietorship example β business_type 1):
\n{\n \"onboarding_request_id\": \"SME-20260628-SOL001\",\n \"business_type\": 1,\n \"business_name\": \"Tunde Ventures\",\n \"business_cer_num\": \"BN-9876543\",\n \"tin\": \"98765432-0001\",\n \"business_address\": \"22 Allen Avenue, Ikeja, Lagos\",\n \"business_industry\": \"Retail\",\n \"specify_industry\": \"Electronics\",\n \"first_name\": \"Babatunde\",\n \"last_name\": \"Adeyemi\",\n \"birthday\": \"1985-07-22\",\n \"gender\": 1,\n \"id_number\": \"98765432101\",\n \"kin_full_name\": \"Folake Adeyemi\",\n \"kin_relationship\": \"Spouse\",\n \"kin_country_code\": \"NG\",\n \"kin_mobile\": \"+2348022334455\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME onboarding info submitted successfully\",\n \"data\": null\n}\n\nDescription:
\nControls the final lifecycle stage of the SME onboarding. Use this to either submit the completed application for bank review, or withdraw it to make corrections.
\naction values:
SUBMIT β sends the application to Choice Bank for review.
Only call this once all info is submitted, documents uploaded, and shareholders added.
PULL_BACK β withdraws a submitted application back to draft state for edits.
After SUBMIT, poll GET /sme/onboarding/status until approved or rejected.
\nRequest Body:
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"action\": \"SUBMIT\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME onboarding request submitted successfully\",\n \"data\": {\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"message\": \"Application submitted successfully\"\n }\n}\n\nDescription:
\nPermanently cancels an SME onboarding request that has not yet been submitted for review. This action is irreversible.
\nUse this only when abandoning an application entirely. To make edits to a submitted application instead, use POST /sme/onboarding/action with action: \"PULL_BACK\".
{\n \"onboarding_request_id\": \"SME-20260628-DFT001\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME onboarding cancelled successfully\",\n \"data\": null\n}\n\nSME (Small and Medium Enterprise) onboarding registers a business entity, not an individual. Supported business types:
1 = Sole Proprietorship
2 = LLC / Limited Company
3 = Partnership
4 = NGO / CBO
The SME flow is more involved than individual onboarding because it requires business registration documents, operating mandate details, and (for companies) shareholder information.
\nFull SME flow:
\nPOST /sme/onboarding/apply β start onboarding, trigger OTP
\nPOST /onboarding/otp/confirm β verify business owner's email
\nPOST /sme/onboarding/submit β submit business details
\nPOST /sme/media/upload β upload supporting documents
\nPOST /sme/shareholder/add β add shareholders (not needed for sole prop)
\nPOST /sme/onboarding/action β submit for bank review (action: \"0\")
\nGET /sme/onboarding/status β poll until approved
\nDescription:
\nStarts the SME onboarding process and sends an OTP to the business owner. Always the first call in the SME flow.
\nbusiness_type values:
1 = Sole Proprietorship (single owner β no shareholders needed)
2 = LLC / Limited Company
3 = Partnership
4 = NGO / CBO
What you get back:
onboarding_request_id β your tracking ID for all subsequent SME steps. Save this.
After this call, confirm OTP via POST /onboarding/otp/confirm, then submit business details via POST /sme/onboarding/submit.
\n{\n \"user_id\": \"usr_ng_biz_9d4e1f2a\",\n \"country_code\": \"234\",\n \"mobile\": \"+2348055987654\",\n \"email\": \"info@deltafortytechltd.ng\",\n \"business_type\": 2,\n \"otp_type\": \"EMAIL\"\n}\n\n{\n \"success\": true,\n \"message\": \"SME onboarding application submitted successfully\",\n \"data\": {\n \"onboarding_request_id\": \"SME-20260628-DFT001\"\n }\n}\n\n// 400 β Invalid business_type\n{\n \"success\": false,\n \"message\": \"invalid Business type β must be 1, 2, 3, or 4\",\n \"data\": null\n}\n\nDescription:
ubmits detailed business information after OTP verification. Required fields vary by business_type.
Always required (all types):
onboarding_request_id, business_type, business_name, business_cer_num,
kra_pin, business_address, business_industry
Required for LLC / Partnership / NGO (types 2, 3, 4):
operating_mode:
1 = Singly (any one signatory can authorise)
2 = Either to Sign
3 = Any Two to Sign
4 = All of Us Jointly
Required for Sole Proprietorship only (type 1):
first_name, last_name, birthday, gender, id_number,
kin_full_name, kin_relationship, kin_country_code, kin_mobile
After submitting: upload documents β add shareholders (if applicable) β submit for review.
\nThe business_inductry field accepts an integer corresponding to the applicant's primary business industry.
The above example indicates that the business sector is Information and Communication Technology.
\nRequest Body (LLC example β business_type 2):
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"business_type\": 2,\n \"business_name\": \"Delta Forty Tech Limited\",\n \"business_cer_num\": \"RC-1234567\",\n \"tin\": \"23456789-0001\",\n \"operating_mode\": 3,\n \"business_address\": \"Plot 14, Adeola Odeku Street, Victoria Island, Lagos\",\n \"business_industry\": 5,\n \"specify_industry\": \"Fintech Infrastructure\"\n}\n\nRequest Body (Sole Proprietorship example β business_type 1):
\n{\n \"onboarding_request_id\": \"SME-20260628-SOL001\",\n \"business_type\": 1,\n \"business_name\": \"Tunde Ventures\",\n \"business_cer_num\": \"BN-9876543\",\n \"tin\": \"98765432-0001\",\n \"business_address\": \"22 Allen Avenue, Ikeja, Lagos\",\n \"business_industry\": 5,\n \"specify_industry\": \"Electronics\",\n \"first_name\": \"Babatunde\",\n \"last_name\": \"Adeyemi\",\n \"birthday\": \"1985-07-22\",\n \"gender\": 1,\n \"id_number\": \"98765432101\",\n \"kin_full_name\": \"Folake Adeyemi\",\n \"kin_relationship\": \"Spouse\",\n \"kin_country_code\": \"NG\",\n \"kin_mobile\": \"+2348022334455\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME onboarding info submitted successfully\",\n \"data\": null\n}\n\nDescription:
\nRetrieves all information submitted so far for an SME onboarding request β business details, uploaded documents, shareholder list, and current status.
\nUse this to:
β Pre-populate an edit form before resubmission
β Verify all required documents have been uploaded
β Review the shareholders registered against the application
onboarding_media_infos β documents uploaded so far (file_id, file_url, media_type)
shareholders_member_infos β individual shareholders added
shareholders_company_infos β company shareholders added
Query Parameters:
\nonboarding_request_id=\"SME-20260628-DFT001\"\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME onboarding info retrieved successfully\",\n \"data\": {\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"business_name\": \"Delta Forty Tech Limited\",\n \"business_type\": 2,\n \"business_certificate_number\": \"RC-1234567\",\n \"kra_pin\": \"23456789-0001\",\n \"business_address\": \"Plot 14, Adeola Odeku Street, Victoria Island, Lagos\",\n \"business_industry\": \"Technology\",\n \"specify_industry\": \"Fintech Infrastructure\",\n \"onboarding_media_infos\": [\n {\n \"file_id\": \"FILE-001\",\n \"file_url\": \"https://cdn.choicebank.com/uploads/deltaforty-cert.pdf\",\n \"media_type\": 0,\n \"content_type\": \"application/pdf\"\n }\n ],\n \"owner_full_name\": null,\n \"owner_id_number\": null,\n \"owner_id_type\": null,\n \"owner_birth_day\": null,\n \"kin_full_name\": null,\n \"kin_country_code\": null,\n \"kin_mobile\": null,\n \"kin_relationship\": null,\n \"shareholders_member_infos\": [\n {\n \"member_id\": \"M-001\",\n \"full_name\": \"Ngozi Okonkwo\",\n \"id_type\": \"NATIONAL_ID\",\n \"id_number\": \"55544433321\",\n \"tin\": \"55544433-0001\",\n \"country_code\": \"NG\",\n \"mobile\": \"+2348099887766\",\n \"id_front_file_url\": \"https://cdn.choicebank.com/uploads/ngozi-id-front.jpg\",\n \"id_back_file_url\": \"https://cdn.choicebank.com/uploads/ngozi-id-back.jpg\",\n \"selfie_file_url\": \"https://cdn.choicebank.com/uploads/ngozi-selfie.jpg\",\n \"kra_pin_file_url\": \"https://cdn.choicebank.com/uploads/ngozi-tin.jpg\"\n }\n ],\n \"shareholders_company_infos\": [],\n \"status\": 1,\n \"reject_reason_ids\": [],\n \"reject_reason_msgs\": [],\n \"create_time\": 1751068800,\n \"audit_time\": 0\n }\n}\n\nDescription:
\nChecks the review status of a submitted SME application. Poll this after calling POST /sme/onboarding/action with action: \"SUBMIT\".
\nThe same status codes as individual onboarding apply (0β9).
\nWhen approved, account_id is populated with the business's account number.
\nIf rejected, check reject_reason_msgs for details. Pull back, correct, and resubmit.
\nQuery Parameters:
\nonboarding_request_id=\"SME-20260628-DFT001\"\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME onboarding status retrieved successfully\",\n \"data\": {\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"onboarding_status\": \"7\",\n \"rejection_reason_ids\": [],\n \"reject_reason_msgs\": [],\n \"account_id\": \"3001122334\",\n \"account_type\": \"B001\",\n \"audit_time\": \"1751075200\"\n }\n}\n\nDescription:
\nControls the final lifecycle stage of the SME onboarding. Use this to either submit the completed application for bank review, or withdraw it to make corrections.
\naction values:
SUBMIT β sends the application to Choice Bank for review.
Only call this once all info is submitted, documents uploaded, and shareholders added.
PULL_BACK β withdraws a submitted application back to draft state for edits.
After SUBMIT, poll GET /sme/onboarding/status until approved or rejected.
\nRequest Body:
\n{\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"user_id\": \"usr_ng_biz_9d4e1f2a\",\n \"action\": \"SUBMIT\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME onboarding request submitted successfully\",\n \"data\": {\n \"onboarding_request_id\": \"SME-20260628-DFT001\",\n \"message\": \"Application submitted successfully\"\n }\n}\n\nDescription:
\nPermanently cancels an SME onboarding request that has not yet been submitted for review. This action is irreversible.
\nUse this only when abandoning an application entirely. To make edits to a submitted application instead, use POST /sme/onboarding/action with action: \"PULL_BACK\".
{\n \"onboarding_request_id\": \"SME-20260628-DFT001\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"SME onboarding cancelled successfully\",\n \"data\": null\n}\n\nDescription:
\nSends a one-time password to verify the customer's phone number or email address. Call this after creating the onboarding request.
otp_type: \"EMAIL\" β delivers to the email address provided
The request_id is the onboarding_request_id from POST /current-account/create.
\nAfter this, prompt the customer to enter the code they received, then confirm via POST /onboarding/otp/confirm.
\nRequest Body:
\n{\n \"request_id\": \"CB-20260628-EMK001\",\n \"otp_type\": \"EMAIL\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"OTP Sent successfully\",\n \"data\": {\n \"application_id\": \"APP-20260628-OTP001\",\n \"status\": \"SUCCESS\"\n }\n}\n\nError Responses:
\n// 400 β Missing request_id\n{\n \"success\": false,\n \"message\": \"request_id is required\",\n \"data\": null\n}\n// 400 β Missing otp_type\n{\n \"success\": false,\n \"message\": \"otp_type is required\",\n \"data\": null\n}\n\nDescription:
\nValidates the OTP the customer received. Call this after the customer enters the code in your app.
\nThe type field must match the otp_type used when sending \"EMAIL\".
\nOn success, status returns \"VERIFIED\" and onboarding advances to the next stage. If the code is wrong or expired, you get a 400 β prompt the customer to request a new OTP via POST /onboarding/otp/resend.
\nRequest Body:
\n{\n \"request_id\": \"CB-20260628-EMK001\",\n \"otp_code\": \"847291\",\n \"type\": \"EMAIL\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"OTP Confirm successfully\",\n \"data\": {\n \"application_id\": \"APP-20260628-OTP001\",\n \"status\": \"VERIFIED\",\n \"message\": \"OTP verified successfully\"\n }\n}\n\nError Responses:
\n// 400 β Wrong or expired code\n{\n \"success\": false,\n \"message\": \"Invalid or expired OTP\",\n \"data\": null\n}\n// 400 β Missing type\n{\n \"success\": false,\n \"message\": \"type is required\",\n \"data\": null\n}\n\nDescription:
\nSends a fresh OTP if the customer didn't receive the previous one or if it expired. Identical to POST /onboarding/otp/send β same fields, same response shape.
\nUse this any time the customer reports not receiving their code or says the code is no longer working.
\nRequest Body:
\n{\n \"request_id\": \"CB-20260628-EMK001\",\n \"otp_type\": \"EMAIL\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"OTP Sent successfully\",\n \"data\": {\n \"application_id\": \"APP-20260628-OTP002\",\n \"status\": \"SUCCESS\"\n }\n}\n\nDescription:
\nSends a one-time password to verify the customer's phone number or email address. Call this after creating the onboarding request.
otp_type: \"EMAIL\" β delivers to the email address provided
The request_id is the onboarding_request_id from POST /current-account/create.
\nAfter this, prompt the customer to enter the code they received, then confirm via POST /onboarding/otp/confirm.
\nRequest Body:
\n{\n \"request_id\": \"CB-20260628-EMK001\",\n \"otp_type\": \"EMAIL\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"OTP Sent successfully\",\n \"data\": {\n \"application_id\": \"APP-20260628-OTP001\",\n \"status\": \"SUCCESS\"\n }\n}\n\nError Responses:
\n// 400 β Missing request_id\n{\n \"success\": false,\n \"message\": \"request_id is required\",\n \"data\": null\n}\n// 400 β Missing otp_type\n{\n \"success\": false,\n \"message\": \"otp_type is required\",\n \"data\": null\n}\n\nDescription:
\nValidates the OTP the customer received. Call this after the customer enters the code in your app.
\nThe type field must match the otp_type used when sending \"EMAIL\".
\nOn success, status returns \"VERIFIED\" and onboarding advances to the next stage. If the code is wrong or expired, you get a 400 β prompt the customer to request a new OTP via POST /onboarding/otp/resend.
\nRequest Body:
\n{\n \"request_id\": \"CB-20260628-EMK001\",\n \"otp_code\": \"847291\",\n \"type\": \"SMS\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"OTP Confirm successfully\",\n \"data\": {\n \"application_id\": \"APP-20260628-OTP001\",\n \"status\": \"VERIFIED\",\n \"message\": \"OTP verified successfully\"\n }\n}\n\nError Responses:
\n// 400 β Wrong or expired code\n{\n \"success\": false,\n \"message\": \"Invalid or expired OTP\",\n \"data\": null\n}\n// 400 β Missing type\n{\n \"success\": false,\n \"message\": \"type is required\",\n \"data\": null\n}\n\nDescription:
\nSends a fresh OTP if the customer didn't receive the previous one or if it expired. Identical to POST /onboarding/otp/send β same fields, same response shape.
\nUse this any time the customer reports not receiving their code or says the code is no longer working.
\nRequest Body:
\n{\n \"request_id\": \"CB-20260628-EMK001\",\n \"otp_type\": \"SMS\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"OTP Sent successfully\",\n \"data\": {\n \"application_id\": \"APP-20260628-OTP002\",\n \"status\": \"SUCCESS\"\n }\n}\n\nDescription:
\nKicks off the onboarding journey for a new individual customer. Submit the customer's personal details, ID document scans (as base64 strings), and a live selfie. Choice Bank runs KYC checks and opens a multi-currency account in the background.
\nThis is always the first call in the individual onboarding flow. The merchant_id is derived automatically from your API key β do not send it.
\nAfter this call:
β Poll GET /onboarding/status until status changes from PROCESSING
β Trigger OTP via POST /onboarding/otp/send
β Confirm OTP via POST /onboarding/otp/confirm
β Poll GET /onboarding/status until status = 7 (account opened)
Field notes:
birthday β YYYY-MM-DD format only
gender β 0 = Female, 1 = Male, 2 = Other
id_type β PASSPORT
employment_status β EMPLOYED | SELF_EMPLOYED | UNEMPLOYED | STUDENT | RETIRED
document_front / document_back / selfie β base64-encoded image strings
document_type / selfie_content_type β MIME type e.g. \"image\" of \"pdf\"
Request Body:
\n{\n \"first_name\": \"Chukwuemeka\",\n \"middle_name\": \"Obiora\",\n \"last_name\": \"Nwosu\",\n \"birthday\": \"1992-03-14\",\n \"address\": \"12 Admiralty Way, Lekki Phase 1, Lagos\",\n \"gender\": 1,\n \"country\": \"Nigeria\",\n \"country_code\": \"234\",\n \"mobile\": \"+2348031234567\",\n \"email\": \"emeka.nwosu@example.ng\",\n \"id_type\": \"PASSPORT\",\n \"id_number\": \"12345678901\",\n \"tin\": \"A000000000B\",\n \"employment_status\": \"EMPLOYED\",\n \"monthly_income\": \"60000_TO_84999\",\n \"business_industry\": \"Technology\",\n \"specify_industry\": \"Fintech\",\n \"document_front\": \"<base64_encoded_image>\",\n \"document_back\": \"<base64_encoded_image>\",\n \"selfie\": \"<base64_encoded_image>\",\n \"document_type\": \"PASSPORT\",\n \"document_content_type\": \"image\", // image pr pdf\n \"selfie_content_type\": \"image\" // image or pdf\n}\n\nSuccess Response (201):
\n{\n \"success\": true,\n \"message\": \"Current account onboarding initiated successfully\",\n \"data\": {\n \"job_id\": \"CB-20260628-EMK001\",\n \"status\": \"PROCESSING\"\n }\n}\n\nError Responses:
\n// 400 β Missing or invalid field\n{\n \"success\": false,\n \"message\": \"invalid birthday date format β expected YYYY-MM-DD\",\n \"data\": null\n}\n// 500 β Upstream error\n{\n \"success\": false,\n \"message\": \"An unexpected error occurred. Please retry.\",\n \"data\": null\n}\n\nOpen a new currency-specific account for an onboarded customer. Each account is tied to a single currency (KES, USD, EUR, etc.). A customer can have multiple accounts in different currencies.
\nThe customer must have passed onboarding (status 7 -- account opened) before calling this.
\n","urlObject":{"path":["account","individual","open"],"host":["{{baseUrl}}"],"query":[],"variable":[]}},"response":[{"id":"d95183f2-644a-492d-a774-732ca514429b","name":"Account opening initiated.","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: bearer","key":"Authorization","value":"BearerDescription:
\nKicks off the onboarding journey for a new individual customer. Submit the customer's personal details, ID document scans (as base64 strings), and a live selfie. Choice Bank runs KYC checks and opens a multi-currency account in the background.
\nThis is always the first call in the individual onboarding flow. The merchant_id is derived automatically from your API key β do not send it.
\nAfter this call:
β Poll GET /onboarding/status until status changes from PROCESSING
β Trigger OTP via POST /onboarding/otp/send
β Confirm OTP via POST /onboarding/otp/confirm
β Poll GET /onboarding/status until status = 7 (account opened)
Field notes:
birthday β YYYY-MM-DD format only
gender β 0 = Female, 1 = Male, 2 = Other
id_type β PASSPORT
employment_status β EMPLOYED | SELF_EMPLOYED | UNEMPLOYED | STUDENT | RETIRED
document_front / document_back / selfie β base64-encoded image strings
document_type / selfie_content_type β MIME type e.g. \"image\" of \"pdf\"
Request Body:
\n{\n \"user_id\": \"usr_ng_7f3a2b1c\",\n \"first_name\": \"Chukwuemeka\",\n \"middle_name\": \"Obiora\",\n \"last_name\": \"Nwosu\",\n \"birthday\": \"1992-03-14\",\n \"address\": \"12 Admiralty Way, Lekki Phase 1, Lagos\",\n \"gender\": 1,\n \"country\": \"Nigeria\",\n \"country_code\": \"234\",\n \"mobile\": \"+2348031234567\",\n \"email\": \"emeka.nwosu@example.ng\",\n \"id_type\": \"NATIONAL_ID\",\n \"id_number\": \"12345678901\",\n \"tin\": \"A000000000B\",\n \"employment_status\": \"EMPLOYED\",\n \"monthly_income\": \"200001-500000\",\n \"business_industry\": \"Technology\",\n \"specify_industry\": \"Fintech\",\n \"document_front\": \"<base64_encoded_image>\",\n \"document_back\": \"<base64_encoded_image>\",\n \"selfie\": \"<base64_encoded_image>\",\n \"document_type\": \"image\",\n \"document_content_type\": \"image/jpeg\",\n \"selfie_content_type\": \"image/jpeg\"\n}\n\nSuccess Response (201):
\n{\n \"success\": true,\n \"message\": \"Current account onboarding initiated successfully\",\n \"data\": {\n \"job_id\": \"CB-20260628-EMK001\",\n \"status\": \"PROCESSING\"\n }\n}\n\nError Responses:
\n// 400 β Missing or invalid field\n{\n \"success\": false,\n \"message\": \"invalid birthday date format β expected YYYY-MM-DD\",\n \"data\": null\n}\n// 500 β Upstream error\n{\n \"success\": false,\n \"message\": \"An unexpected error occurred. Please retry.\",\n \"data\": null\n}\n\nDescription:
\nRetrieves all KYC information submitted for a customer β personal details, document type, verification status, profile check result, and timestamps.
\nUseful for compliance reviews, support queries, or confirming submitted data matches what's expected.
\nstatus values:
PENDING β not yet reviewed
PROCESSING β being verified
VERIFIED β passed all checks
REJECTED β failed one or more checks
FAILED β system error during verification
create_time and update_time are Unix timestamps in seconds.
\nQuery Parameters:
\nonboarding_request_id=CB-20260628-EMK001\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"User KYC retrieved successfully\",\n \"data\": {\n \"onboarding_request_id\": \"CB-20260628-EMK001\",\n \"first_name\": \"Chukwuemeka\",\n \"middle_name\": \"Obiora\",\n \"last_name\": \"Nwosu\",\n \"gender\": \"MALE\",\n \"nationality\": \"Nigerian\",\n \"id_type\": \"NATIONAL_ID\",\n \"id_number\": \"12345678901\",\n \"birthday\": \"1992-03-14\",\n \"address\": \"12 Admiralty Way, Lekki Phase 1, Lagos\",\n \"country_code\": \"NG\",\n \"mobile\": \"+2348031234567\",\n \"employment_status\": \"EMPLOYED\",\n \"monthly_income\": \"200001-500000\",\n \"tin\": \"A000000000B\",\n \"business_industry\": \"Technology\",\n \"specify_industry\": \"Fintech\",\n \"profile_check\": \"1\",\n \"profile_check_result_code\": \"PC-200\",\n \"profile_check_result_text\": \"Profile check passed\",\n \"create_time\": 1751068800,\n \"update_time\": 1751072400,\n \"status\": \"VERIFIED\"\n }\n}\n\nError Responses:
\n// 400 β Missing ID\n{\n \"success\": false,\n \"message\": \"onboarding_request_id is required\",\n \"data\": null\n}\n// 404 β Not found\n{\n \"success\": false,\n \"message\": \"KYC verification not found\",\n \"data\": null\n}\n\nDescription:
\nReturns all documents uploaded so far for a specific onboarding request. Use this to confirm that all required documents have been received before triggering verification.
\nPass onboarding_request_id as a query parameter.
\nQuery Parameters:
\nonboarding_request_id=CB-20260628-EMK001\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"KYC media list retrieved successfully\",\n \"data\": {\n \"media_list\": [\n {\n \"media_type\": \"ID_FRONT\",\n \"file_type_id\": \"FT-001\",\n \"media_url\": \"https://cdn.choicebank.com/uploads/emeka-id-front.jpg\"\n },\n {\n \"media_type\": \"ID_BACK\",\n \"file_type_id\": \"FT-002\",\n \"media_url\": \"https://cdn.choicebank.com/uploads/emeka-id-back.jpg\"\n },\n {\n \"media_type\": \"SELFIE\",\n \"file_type_id\": \"FT-003\",\n \"media_url\": \"https://cdn.choicebank.com/uploads/emeka-selfie.jpg\"\n }\n ]\n }\n}\n\nError Responses:
\n// 400 β Missing identifier\n{\n \"success\": false,\n \"message\": \"onboardingRequestId is required\",\n \"data\": null\n}\n\nDescription:
\nUploads a single identity document for a customer's onboarding β one call per document. Encode the file as a base64 string before sending.
\nmedia_type values:
ID_FRONT β front of the ID card or passport
ID_BACK β reverse of the ID (skip if document has no reverse)
SELFIE β live selfie photo for facial comparison
KRAPIN β tax ID / KRA PIN certificate scan
content_type is optional but recommended: \"image\" or \"pdf\"
\nOn success the response returns code: \"0000\". Any other code means the upload failed β check msg for details.
\nRequest Body:
\n{\n \"onboarding_request_id\": \"CB-20260628-EMK001\",\n \"media_type\": \"ID_FRONT\",\n \"media_base64\": \"<base64_encoded_image_string>\",\n \"content_type\": \"image\" //image or pdf\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"KYC media uploaded successfully\",\n \"data\": {\n \"code\": \"0000\",\n \"msg\": \"SUCCESS\"\n }\n}\n\nError Responses:
\n// 400 β Missing onboarding_request_id\n{\n \"success\": false,\n \"message\": \"onboarding_request_id is required\",\n \"data\": null\n}\n// 400 β Missing media data\n{\n \"success\": false,\n \"message\": \"media_base64 is required\",\n \"data\": null\n}\n\nDescription:
\nUploads a single identity document for a customer's onboarding β one call per document. Encode the file as a base64 string before sending.
\nmedia_type values:
ID_FRONT β front of the ID card or passport
ID_BACK β reverse of the ID (skip if document has no reverse)
SELFIE β live selfie photo for facial comparison
KRAPIN β tax ID / KRA PIN certificate scan
content_type is optional but recommended: \"image\" or \"pdf\"
\nOn success the response returns code: \"0000\". Any other code means the upload failed β check msg for details.
\nRequest Body:
\n{\n \"onboarding_request_id\": \"CB-20260628-EMK001\",\n \"media_type\": \"ID_FRONT\",\n \"media_base64\": \"<base64_encoded_image_string>\",\n \"content_type\": \"image\" // image or pdf\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"KYC media uploaded successfully\",\n \"data\": {\n \"code\": \"0000\",\n \"msg\": \"SUCCESS\"\n }\n}\n\nError Responses:
\n// 400 β Missing onboarding_request_id\n{\n \"success\": false,\n \"message\": \"onboarding_request_id is required\",\n \"data\": null\n}\n// 400 β Missing media data\n{\n \"success\": false,\n \"message\": \"media_base64 is required\",\n \"data\": null\n}\n\nDescription:
\nCheck where a customer's onboarding application currently stands. Provide any one of: onboarding_request_id, user_id, or mobile as a query parameter.
\nPoll this after submitting an onboarding request and after OTP confirmation. Keep polling until status reaches 7 (account opened) or 4 (rejected).
\nStatus codes:
0 = Not submitted
1 = Submitted
2 = Processing (bank reviewing documents)
3 = Passed (documents OK, account opening triggered)
4 = Rejected β read rejection_reason_msg for details
5 = Account closed
6 = Waiting for account to finalise
7 = Account opened β account_id is now the live account number
8 = Failed to open account
9 = Manual review in progress (a human is checking β takes longer)
Query Parameters:
\nonboarding_request_id=CB-20260628-EMK001\n OR\nuser_id=usr_ng_7f3a2b1c\n OR\nmobile=+2348031234567\n\n{\n \"success\": true,\n \"message\": \"Onboarding status retrieved successfully\",\n \"data\": {\n \"onboarding_request_id\": \"CB-20260628-EMK001\",\n \"onboarding_status\": \"7\",\n \"rejection_reason_id\": \"\",\n \"rejection_reason_msg\": \"\",\n \"account_id\": \"1009876543\",\n \"account_type\": \"C001\"\n }\n}\n\nError Responses:
\n// 400 β No identifier provided\n{\n \"success\": false,\n \"message\": \"Provide at least one of: onboarding_request_id, user_id, or mobile\",\n \"data\": null\n}\n// 404 β Not found\n{\n \"success\": false,\n \"message\": \"No onboarding record found for the provided identifier\",\n \"data\": null\n}\n\nDescription:
\nRetrieves the onboarding_request_id for a customer using their user_id or phone number. Use this if you didn't store the request ID after the initial onboarding call, or if a support agent needs to look up a case.
\nProvide either user_id or mobile as a query parameter β only one is needed.
\nQuery Parameters:
\nuser_id=usr_ng_7f3a2b1c\n OR\nmobile=+2348031234567\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"Onboarding request ID retrieved successfully\",\n \"data\": {\n \"onboarding_request_id\": \"CB-20260628-EMK001\"\n }\n}\n\nError Responses:
\njson
\n// 400 β No identifier provided\n{\n \"success\": false,\n \"message\": \"Provide at least one of: user_id or mobile\",\n \"data\": null\n}\n// 404 β Not found\n{\n \"success\": false,\n \"message\": \"No onboarding record found for the provided user_id or mobile\",\n \"data\": null\n}\n\nDescription:
\nKicks off the onboarding journey for a new individual customer. Submit the customer's personal details, ID document scans (as base64 strings), and a live selfie. Choice Bank runs KYC checks and opens a multi-currency account in the background.
\nThis is always the first call in the individual onboarding flow. The merchant_id is derived automatically from your API key β do not send it.
\nAfter this call:
β Poll GET /onboarding/status until status changes from PROCESSING
β Trigger OTP via POST /onboarding/otp/send
β Confirm OTP via POST /onboarding/otp/confirm
β Poll GET /onboarding/status until status = 7 (account opened)
Field notes:
birthday β YYYY-MM-DD format only
gender β 0 = Female, 1 = Male, 2 = Other
id_type β NATIONAL_ID | PASSPORT | DRIVERS_LICENSE | ALIEN_CARD
employment_status β EMPLOYED | SELF_EMPLOYED | UNEMPLOYED | STUDENT | RETIRED
document_front / document_back / selfie β base64-encoded image strings
document_type / selfie_content_type β MIME type e.g. \"image/jpeg\"
Description:
\nCheck where a customer's onboarding application currently stands. Provide any one of: onboarding_request_id, user_id, or mobile as a query parameter.
\nPoll this after submitting an onboarding request and after OTP confirmation. Keep polling until status reaches 7 (account opened) or 4 (rejected).
\nStatus codes:
0 = Not submitted
1 = Submitted
2 = Processing (bank reviewing documents)
3 = Passed (documents OK, account opening triggered)
4 = Rejected β read rejection_reason_msg for details
5 = Account closed
6 = Waiting for account to finalise
7 = Account opened β account_id is now the live account number
8 = Failed to open account
9 = Manual review in progress (a human is checking β takes longer)
Query Parameters:
\nonboarding_request_id=CB-20260628-EMK001\n OR\nuser_id=usr_ng_7f3a2b1c\n OR\nmobile=+2348031234567\n\n{\n \"success\": true,\n \"message\": \"Onboarding status retrieved successfully\",\n \"data\": {\n \"onboarding_request_id\": \"CB-20260628-EMK001\",\n \"onboarding_status\": \"7\",\n \"rejection_reason_id\": \"\",\n \"rejection_reason_msg\": \"\",\n \"account_id\": \"1009876543\",\n \"account_type\": \"C001\"\n }\n}\n\nError Responses:
\n// 400 β No identifier provided\n{\n \"success\": false,\n \"message\": \"Provide at least one of: onboarding_request_id, user_id, or mobile\",\n \"data\": null\n}\n// 404 β Not found\n{\n \"success\": false,\n \"message\": \"No onboarding record found for the provided identifier\",\n \"data\": null\n}\n\nDescription:
\nRetrieves the onboarding_request_id for a customer using their user_id or phone number. Use this if you didn't store the request ID after the initial onboarding call, or if a support agent needs to look up a case.
\nProvide either user_id or mobile as a query parameter β only one is needed.
\nQuery Parameters:
\nuser_id=usr_ng_7f3a2b1c\n OR\nmobile=+2348031234567\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"Onboarding request ID retrieved successfully\",\n \"data\": {\n \"onboarding_request_id\": \"CB-20260628-EMK001\"\n }\n}\n\nError Responses:
\njson
\n// 400 β No identifier provided\n{\n \"success\": false,\n \"message\": \"Provide at least one of: user_id or mobile\",\n \"data\": null\n}\n// 404 β Not found\n{\n \"success\": false,\n \"message\": \"No onboarding record found for the provided user_id or mobile\",\n \"data\": null\n}\n\nDescription:
\nGenerates a QR code that a payer can scan with their M-PESA or banking app to send money directly into a specified FX account.
\nqr_code in the response is a base64-encoded PNG image. Decode it and display it in your app or on a payment screen for the customer to scan.
\nThe reference field is your idempotency key β reusing the same reference returns the original QR code without generating a new one.
\nRequest Body:
\n{\n \"account_id\": \"2001234567\",\n \"amount\": 50000,\n \"reference\": \"QR-20260628-001\",\n \"environment\": \"production\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"QR code generated successfully\",\n \"data\": {\n \"reference\": \"QR-20260628-001\",\n \"status\": 1,\n \"qr_code\": \"/9j/4AAQSkZJRgABAQAAAQABAAD...base64encodedimage...\",\n \"markup\": {\n \"markup_rate\": 0.005,\n \"markup_amount\": 250.0,\n \"currency\": \"KES\",\n \"total_with_markup\": 50250.0\n }\n }\n}\n\nDescription:
\nInitiates a reversal of a previously completed transfer. The original transaction must belong to your merchant account.
\nReversals are not guaranteed β they depend on the receiving bank's ability to return the funds. The status in the response tells you whether the reversal was accepted.
\noriginal_reference β the reference of the transfer you want to reverse (the reference field from the original initiate response).
\nAlways include a reason for audit trail purposes. The response gives you a new reversal reference β save it for tracking.
\nRequest Body:
\n{\n \"original_reference\": \"TXN-20260628-001\",\n \"reason\": \"Customer requested reversal β duplicate payment\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"Transaction reversal applied successfully\",\n \"data\": {\n \"reference\": \"REV-20260628-001\",\n \"status\": 1,\n \"status_desc\": \"SUCCESS\"\n }\n}\n\nError Responses:
\n// 400 β Missing original_reference\n{\n \"success\": false,\n \"message\": \"original_reference is required\",\n \"data\": null\n}\n// 403 β Not your transaction\n{\n \"success\": false,\n \"message\": \"transaction does not belong to your merchant\",\n \"data\": null\n}\n// 404 β Reference not found\n{\n \"success\": false,\n \"message\": \"transaction not found with the given reference\",\n \"data\": null\n}\n\nDescription:
\nSends money from an FX account to another account β either an internal FX account or an external bank account via Pesalink or EFT. This is the standard transfer endpoint for most bank-to-bank payments.
\nAlways call POST /transfer/hakikisha first to confirm the recipient.
\nKey fields:
payer_account_id β your FX account (source of funds)
payee_bank_code β recipient's bank code β use GET /lookup/bank-codes to find the right one
payee_account_id β recipient's account number
currency β 3-letter code (KES, USD, EUR, etc.)
amount β how much to send (minimum 1)
reference β your idempotency key (UUID recommended). Auto-generated if omitted.
If otp_status in the response is \"REQUIRED\", the transfer is pending OTP confirmation before it processes.
\nRequest Body:
\n{\n \"payer_account_id\": \"1009876543\",\n \"payee_bank_code\": \"011\",\n \"payee_account_id\": \"0123456789\",\n \"payee_account_name\": \"Adaeze Obi\",\n \"currency\": \"NGN\",\n \"payment_purpose\": \"Supplier payment β Invoice INV-2026-047\",\n \"amount\": 250000,\n \"remark\": \"INV-2026-047\",\n \"payee_mobile_for_notification\": \"+2348044556677\",\n \"reference\": \"TXN-20260628-001\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"Transfer initiated successfully\",\n \"data\": {\n \"reference\": \"TXN-20260628-001\",\n \"status\": \"PROCESSING\",\n \"otp_status\": \"NOT_REQUIRED\"\n }\n}\n\nError Responses:
\n// 403 β Account doesn't belong to your merchant\n{\n \"success\": false,\n \"message\": \"account does not belong to your merchant\",\n \"data\": null\n}\n// 409 β Duplicate reference\n{\n \"success\": false,\n \"message\": \"reference already exists\",\n \"data\": null\n}\n\nDescription:
\nSends money via RTGS or EFT β typically used for higher-value inter-bank transfers or when the recipient's bank isn't on the Pesalink network.
\npayment_channel:
RTGS β Real-Time Gross Settlement. Immediate settlement, used for large high-priority transfers.
EFT β Electronic Funds Transfer. Batch-processed, usually settles overnight. Lower cost.
amount is a numeric string (e.g. \"250000.00\").
\nRequest Body:
\n{\n \"payer_account_id\": \"1009876543\",\n \"payee_account_no\": \"0123456789\",\n \"payee_bank_code\": \"058\",\n \"amount\": \"1500000.00\",\n \"currency\": \"NGN\",\n \"payment_channel\": \"RTGS\",\n \"payee_account_name\": \"Zenith Property Investments Ltd\",\n \"remark\": \"Property acquisition deposit β Ref ZPI-2026-03\",\n \"reference\": \"RTGS-20260628-001\",\n \"environment\": \"production\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"Bank transfer initiated successfully\",\n \"data\": {\n \"reference\": \"RTGS-20260628-001\",\n \"status\": 1,\n \"status_desc\": \"SUBMITTED\",\n \"markup\": {\n \"markup_rate\": 0.005,\n \"markup_amount\": 7500.0,\n \"currency\": \"NGN\",\n \"total_with_markup\": 1507500.0\n }\n }\n}\n\nDescription:
\nReturns the full list of supported bank codes and their corresponding bank names. Use this to find the correct payee_bank_code value before initiating a general or bank transfer.
\nCall this once and cache the result β the list changes infrequently.
\nQuery Parameters:
\n(none required β user_id is optional)\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"Bank codes list retrieved successfully\",\n \"data\": {\n \"items\": [\n { \"bank_code\": \"011\", \"bank_name\": \"FIRST BANK OF NIGERIA\" },\n { \"bank_code\": \"058\", \"bank_name\": \"GUARANTY TRUST BANK\" },\n { \"bank_code\": \"033\", \"bank_name\": \"UNITED BANK FOR AFRICA\" },\n { \"bank_code\": \"044\", \"bank_name\": \"ACCESS BANK\" },\n { \"bank_code\": \"057\", \"bank_name\": \"ZENITH BANK\" },\n { \"bank_code\": \"070\", \"bank_name\": \"FIDELITY BANK\" },\n { \"bank_code\": \"221\", \"bank_name\": \"STANBIC IBTC BANK\" },\n { \"bank_code\": \"035\", \"bank_name\": \"WEMA BANK\" }\n ]\n }\n}\n\nDescription:
\nReturns the current buy and sell exchange rates for a currency pair β both Telegraphic Transfer (TT / electronic) and Cash rates.
\nSupported pairs:
USD/KES, EUR/KES, GBP/KES, KES/TZS, KES/UGX, KES/RWF,
GBP/USD, EUR/GBP, EUR/USD, USD/CNY
Rate interpretation:
tt.sell β rate at which Finecore/Choice Bank sells the base currency
(e.g. you're buying USD with KES β use this)
tt.buy β rate at which they buy the base currency
(e.g. you're selling USD for KES β use this)
Rates change throughout the trading day. Always query fresh rates immediately before initiating a conversion. 503 means rates are temporarily unavailable for that pair β retry after a short delay.
\nRequest Body:
\n{\n \"currency_pair\": \"USD/KES\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"FX rate retrieved successfully\",\n \"data\": {\n \"unit_amount\": 1,\n \"currency_pair\": \"USD/KES\",\n \"tt\": {\n \"sell\": \"131.50\",\n \"buy\": \"129.00\"\n },\n \"cash\": {\n \"sell\": \"133.00\",\n \"buy\": \"127.50\"\n },\n \"timestamp\": \"2026-06-28T10:00:00Z\"\n }\n}\n\nError Responses:
\n// 400 β Missing pair\n{\n \"success\": false,\n \"message\": \"currency pair is required\",\n \"data\": null\n}\n// 400 β Unsupported pair\n{\n \"success\": false,\n \"message\": \"invalid or unsupported currency pair\",\n \"data\": null\n}\n// 400 β Rates unavailable\n{\n \"success\": false,\n \"message\": \"FX rate not available for the requested currency pair\",\n \"data\": null\n}\n\nDescription:
\nPolls the current status of a foreign exchange conversion initiated via POST /initiate. Keep polling until status is COMPLETED or FAILED.
\nPass transaction_id as a query parameter.
\nWhen COMPLETED:
source_amount / target_amount β actual amounts debited and credited
fx_rate β exact rate applied (may differ slightly from the quoted rate due to market movement)
out_tx_id / in_tx_id β debit and credit transaction IDs for reconciliation
If FAILED or REJECTED, check error_code and error_msg for the reason.
\nQuery Parameters:
\ntransaction_id=FX-20260628-001\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"FX request status retrieved successfully\",\n \"data\": {\n \"transaction_id\": \"FX-20260628-001\",\n \"source_account_id\": \"1009876543\",\n \"target_account_id\": \"2001234567\",\n \"source_currency\": \"KES\",\n \"target_currency\": \"USD\",\n \"source_amount\": 500000.0,\n \"target_amount\": 3803.42,\n \"out_tx_id\": \"OUT-TX-20260628-001\",\n \"in_tx_id\": \"IN-TX-20260628-001\",\n \"status\": \"COMPLETED\",\n \"fx_rate\": \"0.007607\",\n \"error_code\": \"\",\n \"error_msg\": \"\"\n }\n}\n\nDescription:
\nConverts money from one currency account to another at the current exchange rate.
\nSpecify either source_amount (how much to send) OR target_amount (how much to receive) β not both. The system calculates the other side.
\nBoth accounts must already exist and belong to your merchant.
\nA 0.5% markup fee applies to all conversions β shown in the markup object of the response.
\nreference is required and must be unique β use a UUID or your internal transaction ID.
\nConversion status lifecycle:
INIT β PROCESSING β APPROVED β COMPLETED
β REJECTED
β FAILED
After initiating, poll GET /status with the transaction_id until COMPLETED or FAILED.
\nRequest Body (convert KES β USD by source amount):
\n{\n \"source_currency\": \"KES\",\n \"target_currency\": \"USD\",\n \"source_account\": \"1009876543\",\n \"target_account\": \"2001234567\",\n \"source_amount\": 500000,\n \"reference\": \"FX-20260628-001\",\n \"environment\": \"production\"\n}\n\nRequest Body (receive exactly 1000 USD):
\n{\n \"source_currency\": \"KES\",\n \"target_currency\": \"USD\",\n \"source_account\": \"1009876543\",\n \"target_account\": \"2001234567\",\n \"target_amount\": 1000,\n \"reference\": \"FX-20260628-002\",\n \"environment\": \"production\"\n}\n\nSuccess Response (200):
\n{\n \"success\": true,\n \"message\": \"FX exchange initiated successfully\",\n \"data\": {\n \"reference\": \"FX-20260628-001\",\n \"status\": \"PROCESSING\",\n \"markup\": {\n \"markup_rate\": 0.005,\n \"markup_amount\": 2500.0,\n \"currency\": \"KES\",\n \"total_with_markup\": 502500.0\n }\n }\n}\n\nThis collection covers the full lifecycle of Finecore's FX infrastructure. Use these endpoints to onboard individual customers and SME businesses, manage KYC verification, open multi-currency accounts, query live FX rates, convert between currencies, and initiate transfers via bank, M-PESA, or QR code.
\nBase URL (Production): https://api.finecore.com/v1/fx
\nEndpoints that trigger financial actions accept a reference field. Send the same reference twice and the API will return the original result instead of processing a duplicate β use a UUID or your internal transaction ID.
\nIndividual and SME accounts can be opened in any of the following currencies:
\nKES Kenyan Shilling
USD US Dollar
GBP British Pound Sterling
EUR Euro
CNY Chinese Yuan (Renminbi)
TZS Tanzanian Shilling
UGX Ugandan Shilling
RWF Rwandan Franc
Supported FX Conversion Pairs
The following currency pairs are available for rate queries and FX conversions:
USD/KES US Dollars β Kenyan Shillings
EUR/KES Euros β Kenyan Shillings
GBP/KES British Pounds β Kenyan Shillings
KES/TZS Kenyan Shillings β Tanzanian Shillings
KES/UGX Kenyan Shillings β Ugandan Shillings
KES/RWF Kenyan Shillings β Rwandan Francs
GBP/USD British Pounds β US Dollars
EUR/GBP Euros β British Pounds
EUR/USD Euros β US Dollars
USD/CNY US Dollars β Chinese Yuan
Current Account Onboarding
\nCreate current account
\nonboarding status
\nSend OTP
\nConfirm OTP
\nResend OTP
\nGet onboarding request ID
\nGet account opening status
\nKYC Verification (5 requests)
\nUpload KYC media
\nList KYC media
\nGet KYC user details
\nGet KYC status
\nSME Onboarding
\nApply for SME onboarding
\nSubmit SME business details
\nGet SME onboarding info
\nSubmit / pull back SME application
\nGet SME onboarding status
\nCancel SME onboarding
\nUpload SME document
\nRemove SME document
\nSME Shareholder Management
\nAdd shareholder (individual or organisation)
\nRemove shareholder
\nTransfers
\nInitiate general transfer
\nInitiate M-PESA B2B transfer
\nInitiate bank transfer (RTGS / EFT)
\nGenerate payment QR code
\nReverse a transfer
\nLookup
\nFX Rates & Exchange
\nQuery FX rate
\nInitiate FX conversion
\nGet FX conversion status
\n