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"}],"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.
\nThis endpoint is used to create a new customer profile required for initiating financial transactions on the platform. A customer must be created before performing operations such as onramp, offramp, transfers, or mobile money deposits.
\nIt stores essential customer identity and contact details, enabling compliance, transaction tracking, and settlement mapping.
\nOnce created, the customer record can be used across all supported payment flows.
\nThe customer name must match the bank account name prefix.
\nThe name provided must align with the beneficiary bank account name used for payouts or transfers.
\nThis ensures identity consistency between the customer profile and banking records.
\nCustomer Name: John Doe
\nBank Account Name: John Doe Akinwale
âś” Valid (prefix matches)
Customer Name: John Doe
\nBank Account Name: Michael John Doe
❌ Invalid (name does not match expected prefix rule)
Prevent fraud and mismatched payouts
\nEnsure KYC consistency
\nReduce transfer and settlement failures
\nThis endpoint is used to initiate a fiat-to-fiat transfer between accounts within the supported payment network.
\nThe transaction moves funds from a sender’s fiat source into a designated recipient bank account, enabling seamless internal fiat settlement.
\nTo complete an onramp fiat-to-fiat transfer, the user must ensure that an offramp bank account is added and verified.
This account will be used for settlement and payout processing where applicable.
Customer initiates a fiat transfer request
\nSystem validates sender and recipient details
\nTransaction is processed within the fiat network
\nFunds are settled into the configured bank account
\nFailure to configure an valid offramp bank account may result in transaction rejection or delayed settlement.
\n","urlObject":{"path":["stablecoin","transfers","ramp","initiate"],"host":["{{BASE_URL}}"],"query":[],"variable":[]}},"response":[{"id":"c66c7eda-dd31-4968-95a1-1623c9b2d160","name":"Initiate Ramp Transfer","originalRequest":{"method":"POST","header":[{"key":"X-API-Key","value":"{{X-API-Key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"from_currency\": \"NGN\",\r\n \"to_currency\": \"GHS\",\r\n \"from_amount\": \"2000\",\r\n \"reference\": \"onra145yyp_q1ngn7112re3e_1gq01\",\r\n \"customer_id\": \"441d5109-c72b-4tf9-ba86-fe0d85803f03\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/stablecoin/transfers/ramp/initiate"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text","uuid":"1a784d92-9ac3-4ee2-a3a7-cde8baa11e4f"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"Ramp transaction initiated successfully\",\n \"data\": {\n \"reference\": \"onra145yyp_q1ngn7112re3e_1gq01\",\n \"status\": \"PENDING\"\n }\n}"}],"_postman_id":"7cfa5649-17f4-45d0-90f3-6dbcaae915ac"},{"name":"Confirm Ramp Transfer","id":"1e43f5cd-1783-4d1f-a4c8-ec8765916a9f","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":"","options":{"raw":{"language":"json"}}},"url":"{{BASE_URL}}/stablecoin/transfers/ramp/:reference/confirm","description":"This endpoint is used to confirm the status of an initiated onramp transaction and complete settlement processing based on the transaction flow.
\nFor NGN to foreign currency conversions:
\nThe user will be provided with bank transfer details after initiation.
\nThe user is expected to make a bank transfer to the provided account details.
\nOnce payment is confirmed, the transaction is processed and the converted funds are credited to the recipient currency wallet or destination account.
\nFor foreign currency to NGN conversions:
\nThe transaction is processed after confirmation.
\nSettlement is made to the user’s linked NGN payout method, such as:
\nBank account
\nMobile Money (MoMo) account (if configured)
\nConfirmation ensures that funds have been received or payout has been successfully initiated.
\nTransactions may remain in a \"processing\" state until settlement is completed.
\nAccurate payment reference is required for successful reconciliation.
\nThis endpoint is used to add and verify a bank account that will be used for offramp (crypto-to-fiat or stablecoin-to-fiat) payouts.
\nThe added bank account is used as the destination account for receiving fiat settlements when users convert digital assets into local currency.
\nLink a valid bank account to the customer profile
\nEnable fiat payout for offramp transactions
\nEnsure settlement destination is properly configured before withdrawals
\nAccount holder name must match the customer name (or approved prefix rule)
\nBank account details must be valid and supported in the selected region
\nAccount must pass verification checks before it can be used for payouts
\nOnce added and verified, this bank account will automatically be used for:
\nOfframp withdrawals
\nFiat settlements from stablecoin conversions
\nPayout processing from completed transactions
\nThis endpoint retrieves a list of supported banks available for fiat transfers and payout operations within a specific country.
\nProvide merchants with valid bank options for customer payouts
\nSupport bank selection during account setup and offramp configuration
\nEnsure only verified and supported financial institutions are used for transactions
\nNG, GH, KE)The returned list is used when:
\nAdding a bank account for offramp payouts
\nInitiating fiat transfers
\nSelecting beneficiary banks for customer transactions
\nEach bank entry may include:
\nBank name
\nBank code
\nCountry code (based on filter)
\nOnly banks available in the specified country will be returned
\nInvalid or unsupported country codes will return an empty list or error
\nThis 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
\n