The Futurapay REST API enables seamless and secure integration for merchants to process deposits, payments, and related financial operations. It is designed with simplicity and reliability in mind, ensuring that merchants can easily onboard, authenticate, and perform transactions with minimal complexity.
\nEach merchant is provided with a Merchant Key, Site ID, and API Key, which serve as unique credentials for authentication and request validation. These credentials can be retrieved from the merchant dashboard under:
\nMerchant > My Profile → Merchant Key
\nMerchant > Settings > Services → Site ID & API Key
\nAll requests must include these credentials to ensure secure communication and prevent unauthorized access.
\nFuturapay supports multiple currencies and countries. The allowed currency codes (e.g., XAF, USD, BTC) and country codes (ISO 2-digit format, e.g., CM, NG, US) can be dynamically retrieved using the endpoint:/restapi/v1/public/merchant/currencies
This ensures that merchants always use valid and up-to-date codes when initiating transactions.
\nMerchants initiate a deposit by submitting essential customer and transaction details, such as:
\nCustomer Information: First name, last name, phone number, and email.
\nTransaction Details: Unique transaction ID (provided by the merchant), amount, currency, and country.
\nThe customer_transaction_id must be unique for every request, enabling both Futurapay and the merchant to track and reconcile payments accurately.
All requests should be made over HTTPS to ensure data encryption.
\nAPI keys and merchant credentials must be kept confidential.
\nInput validation is strictly enforced to prevent errors and fraudulent activities.
\nFuturapay provides standardized error responses to help merchants quickly diagnose and resolve issues. Errors may occur due to invalid credentials, incorrect parameter values, or unsupported currencies/countries. Always refer to the error code and message returned in the response for debugging.
\nGenerate and store unique transaction IDs for each deposit.
\nValidate customer inputs (phone, email, amount format) before sending to the API.
\nRegularly refresh available currencies and country codes from the public endpoint to avoid rejections.
\nMonitor error responses to fine-tune integration and improve reliability.
\nDescription:
\nThis endpoint allows a merchant to initiate a deposit payment on behalf of a customer. It requires the merchant’s credentials (merchant key, site ID, API key) along with the customer’s payment details.
\nThe API request must be authenticated using a valid Bearer Token (generated via the Merchant Token Generate endpoint).
\nOnce initiated, the API returns transaction details including payment gateway configuration, transaction reference, and other metadata required for processing the deposit.
\nAuthorization:
\nAuthorization: Bearer {{rest_api_token}}) obtained from the Merchant Token Generate API.Body Parameters (form-data):
\nExample Request (form-data):
\n{\n \"merchant_key\": \"662a38a6ee29d\",\n \"site_id\": \"318071116\",\n \"api_key\": \"apiKey67863cc0727d6\",\n \"currency_code\": \"XAF\",\n \"country_code\": \"CM\",\n \"customer_first_name\": \"Sandip\",\n \"customer_last_name\": \"\",\n \"customer_phone\": \"9876543210\",\n \"customer_email\": \"sandip@yopmail.com\",\n \"customer_transaction_id\": \"TXN123456789\",\n \"amount\": 55000\n}\n\nExample Response (200 OK):
\n{\n \"success\": true,\n \"message\": \"Payment initiated successfully.\",\n \"data\": {\n \"currency\": {\n \"id\": 9,\n \"name\": \"CFA Franc (BEAC)\",\n \"code\": \"XAF\",\n \"symbol\": \"XAF\",\n \"usd_exchange_rate\": 573.903191,\n \"minimum_deposite\": 100,\n \"maximum_deposite\": 10000000000,\n \"country\": {\n \"id\": 39,\n \"name\": \"Cameroon\",\n \"code\": \"CM\",\n \"dial_code\": \"237\",\n \"flag\": \"https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/CM.svg\"\n }\n },\n \"gateway_configuration\": [\n {\n \"id\": 188,\n \"primary_key\": \"XXXXXXXXXXXXXXXXXXX\",\n \"type\": \"collection\",\n \"api_key\": \"XXXXXXXXXXXXXXXXXXXXX\",\n \"api_user\": \"At lorem dolorem lab\",\n \"payment_server_url\": \"https://www.paymentserverurl.com\",\n \"minimum_fees\": 0,\n \"fee_in_percentage\": 0,\n \"comments\": \"Amet mollit laboris\",\n \"awaiting_comments\": \"Est explicabo Culpa\",\n \"status\": \"active\",\n \"gateway\": {\n \"id\": 15,\n \"name\": \"FuturaPay(No fee)\",\n \"logo\": \"/img/icons/logo.png\",\n \"payment_method\": \"FuturaPay\",\n \"is_crypto\": 0,\n \"comments\": \".\",\n \"lookup_currency\": [\n {\n \"currency_code\": \"AFN\",\n \"country\": {\n \"id\": 1,\n \"name\": \"Afghanistan\",\n \"code\": \"AF\",\n \"dial_code\": \"93\",\n \"flag\": \"https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/AF.svg\"\n }\n }\n ]\n }\n }\n ],\n \"merchant_service\": {\n \"id\": 100,\n \"site_id\": \"3XXXXXXX6\",\n \"item_name\": \"johndoe\",\n \"service_name\": \"johndoe\",\n \"service_type\": \"default\",\n \"success_url\": \"https://stage-merchant.futurapay.com/wallet-management\",\n \"faild_url\": \"https://stage-merchant.futurapay.com/wallet-management\",\n \"notification_url\": \"https://stage-merchant.futurapay.com/wallet-management\",\n \"description\": \"default_service_name\",\n \"logo_url\": \"https://stage-payment-widget.futurapay.com/widget/withdrawal/assets/img/logo.png\",\n \"city\": \"Kolkata\",\n \"email\": \"john.doe@yopmail.com\",\n \"service_status\": \"approved\",\n \"status\": \"active\",\n \"desposit_status\": true,\n \"withdraw_status\": true,\n \"who_pays_for_fee\": \"user\"\n },\n \"has_token\": \"76a8********************************************************25cd\",\n \"amount\": \"55000\",\n \"customer_email\": \"john.doe@yopmail.com\",\n \"customer_transaction_id\": \"6**********5\",\n \"country\": {\n \"id\": 39,\n \"name\": \"Cameroon\",\n \"code\": \"CM\",\n \"dial_code\": \"237\",\n \"flag\": \"https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/CM.svg\"\n }\n }\n}\n\nError Responses:
\n401 Unauthorized – Invalid or missing Bearer Token.
403 Forbidden – Invalid merchant credentials (merchant_key, site_id, or api_key).
422 Unprocessable Entity – Missing or invalid request parameters.
500 Internal Server Error – Unexpected system error.
✅ Use Cases:
\nInitiating customer deposit payments for fiat or crypto.
\nLinking customer and merchant details to a secure payment gateway.
\nEstablishing the transaction record before further processing (e.g., updating status, confirming wallet address).
\nProcesses a payment request using a valid hash_token.
This endpoint allows initiating a payment transaction with an associated phone number.
\nThe receiver_email field is optional and can be included if the payment confirmation should also be sent via email.
This route is protected and requires Bearer Token Authentication (auth:sanctum middleware).
Type: Bearer Token
\nHeader Key: Authorization
Value: Bearer {{rest_api_token}}
{\n \"success\": false,\n \"message\": \"Transaction status is not initiated.\",\n \"errors\": []\n}\n\n{\n \"status\": false,\n \"message\": \"Validation failed.\",\n \"errors\": {\n \"hash_token\": [\n \"The selected hash token is invalid.\"\n ]\n }\n}\n\nThe Deposit APIs allow merchants to initiate and manage customer deposits into their Futurapay account. These endpoints ensure smooth and secure payment processing across multiple channels such as mobile money, cards, and cryptocurrency.
\nEach deposit request requires authentication using your Merchant Key, Site ID, and API Key, ensuring that only authorized merchants can perform transactions. A unique Customer Transaction ID must be provided for every deposit request, enabling seamless reconciliation and tracking on both the merchant and Futurapay platforms.
\nKey highlights of the Deposit APIs:
\n🔑 Secure Authentication using merchant credentials.
\n💱 Multi-Currency Support (e.g., XAF, USD, BTC).
\n🌍 Global Coverage with ISO-standard country codes.
\n📲 Customer-Centric Data such as phone number, email, and name for verification.
\n🧾 Detailed Transaction Tracking with unique references for every deposit.
\nThese APIs are designed for real-time deposit initiation and ensure that merchants can provide customers with a fast, reliable, and transparent payment experience.
\n","_postman_id":"5b9be496-4bba-434e-9608-cc42ee633008"},{"name":"Withdraw","item":[{"name":"Withdraw Payment Initiate","event":[{"listen":"test","script":{"id":"2f82d52f-6e94-4218-a36f-4a21e7b0cef4","exec":["// Check if the response is successful\r","if (pm.response.code === 200) {\r"," // Parse the response JSON\r"," const responseJson = pm.response.json();\r"," \r"," // Store the token in a global or environment variable\r"," pm.globals.set(\"rest_api_has_token\", responseJson.data.has_token);\r"," \r"," // Log to console for debugging\r"," console.log(\"RestAPI token stored:\", responseJson.data.has_token);\r","} else {\r"," console.log(\"Failed to generate token. Response code:\", pm.response.code);\r","}\r",""],"type":"text/javascript","packages":{}}}],"id":"2b18991f-c027-4012-a8b6-e92dd2dc3893","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"body":{"mode":"formdata","formdata":[]},"url":"https://stage-api.futurapay.com/restapi/v1/payments/withdraw/initiate","description":"Description:
\nThis endpoint allows a merchant to initiate a withdraw payment on behalf of a customer. It requires the merchant’s credentials (merchant key, site ID, API key) along with the customer’s payment details.
\nThe API request must be authenticated using a valid Bearer Token (generated via the Merchant Token Generate endpoint).
\nOnce initiated, the API returns transaction details including payment gateway configuration, transaction reference, and other metadata required for processing the deposit.
\nAuthorization:
\nAuthorization: Bearer {{rest_api_token}}) obtained from the Merchant Token Generate API.Body Parameters (form-data):
\nExample Request (form-data):
\n{\n \"merchant_key\": \"662a38a6ee29d\",\n \"site_id\": \"318071116\",\n \"api_key\": \"apiKey67863cc0727d6\",\n \"currency_code\": \"XAF\",\n \"country_code\": \"CM\",\n \"customer_first_name\": \"Sandip\",\n \"customer_last_name\": \"\",\n \"customer_phone\": \"9876543210\",\n \"customer_email\": \"sandip@yopmail.com\",\n \"customer_transaction_id\": \"TXN123456789\",\n \"amount\": 55000\n}\n\nError Responses:
\n401 Unauthorized – Invalid or missing Bearer Token.
403 Forbidden – Invalid merchant credentials (merchant_key, site_id, or api_key).
422 Unprocessable Entity – Missing or invalid request parameters.
500 Internal Server Error – Unexpected system error.
✅ Use Cases:
\nInitiating customer deposit payments for fiat or crypto.
\nLinking customer and merchant details to a secure payment gateway.
\nEstablishing the transaction record before further processing (e.g., updating status, confirming wallet address).
\nWithdraw Processes a payment request using a valid hash_token.
This endpoint allows initiating a payment transaction with an associated phone number.
\nThe receiver_email field is optional and can be included if the payment confirmation should also be sent via email.
This route is protected and requires Bearer Token Authentication (auth:sanctum middleware).
Type: Bearer Token
\nHeader Key: Authorization
Value: Bearer {{rest_api_token}}
{\n \"success\": false,\n \"message\": \"Transaction status is not initiated.\",\n \"errors\": []\n}\n\n{\n \"status\": false,\n \"message\": \"Validation failed.\",\n \"errors\": {\n \"hash_token\": [\n \"The selected hash token is invalid.\"\n ]\n }\n}\n\nThe Withdraw API allows merchants to initiate secure payouts from their Futurapay account to customers. This ensures seamless transfer of funds while maintaining compliance, transparency, and traceability.
\nThrough this API, merchants can:
\nInitiate withdrawals to customer bank accounts or mobile money wallets.
\nValidate requests using their Merchant Key, Site ID, and API Key for authentication.
\nTrack each withdrawal request with a unique customer_transaction_id.
Specify withdrawal details such as amount, currency, and customer payout information.
\nReceive structured responses confirming success or failure with relevant status codes.
\nAuthentication Required: Every request must contain valid merchant credentials (merchant_key, site_id, api_key).
Customer Information: Basic customer details (name, phone, email) are required for identification and transaction traceability.
\nAmount & Currency: Withdrawals must be requested in supported currencies as configured for the merchant’s account.
\nStatus Tracking: The response includes transaction references that can be used to query withdrawal status later.
\nUse this API to manage outgoing transactions in a reliable and auditable way, ensuring that funds are transferred securely to your customers.
\n","_postman_id":"67832518-320b-4235-ad88-abe4ac64ab16"},{"name":"Health Check Endpoint","id":"ac5f034b-06e3-4cbd-8946-482da52d5d93","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://127.0.0.1:8888/restapi/health","description":"Description:
\nThis endpoint is used to verify the availability and status of the API service. It acts as a heartbeat check to confirm that the server is up and running.
\nUseful for monitoring tools, uptime checks, and ensuring that the API gateway is healthy before making further requests.
\nUse Case:
\nSystem monitoring and uptime validation
\nPre-check before executing other API requests
\nDescription:
\nRetrieves a list of all active currencies supported by the platform. Each currency entry includes its code, name, and other relevant details required for transactions.
\nUse Case:
\nDisplay available currencies in a dropdown for deposits, withdrawals, or checkout flows
\nValidate whether a requested currency is supported before processing payments
\nDescription:
\nRetrieves a list of countries supported by the system for transactions and services. Each entry typically includes country code and name.
\nUse Case:
\nPopulate a country selection dropdown during onboarding or checkout
\nValidate user country eligibility for services or payment processing
\nDescription:
\nThis endpoint is used to authenticate a merchant by generating an access token.
\nThe merchant must provide a valid merchant_key (issued by the platform). Upon success, the API returns an authentication token that must be used as a Bearer Token for all subsequent merchant requests.
Body Parameters (form-data):
\nmerchant_key (string, required) – The unique key assigned to the merchant.Use Case:
\nAuthenticate a merchant before accessing protected APIs.
\nGenerate a secure access token to include in the Authorization header for subsequent requests.
Example Response (200 OK):
\n{\n \"status\": \"success\",\n \"message\": \"Token generated successfully\",\n \"data\": {\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5...\"\n }\n}\n\nDescription:
\nRetrieves the list of currencies, balances, and services available to an authenticated merchant.
\nThis endpoint requires a valid Bearer Token obtained from the Merchant Token Generate API.
\nAuthorization:
\nBearer Token – Use the token returned from /auth/merchant/token/generate.Use Case:
\nGet all currencies a merchant can transact with.
\nFetch current balances in different currencies.
\nRetrieve supported services available for the merchant.
\nExample Response (200 OK):
\n{\n \"success\": true,\n \"message\": \"Merchant currencies fetched successfully.\",\n \"data\": [\n {\n \"id\": 9,\n \"name\": \"CFA Franc (BEAC)\",\n \"code\": \"XAF\",\n \"symbol\": \"XAF\",\n \"type\": \"Flat\",\n \"usd_equivalence\": 105857.8,\n \"freemium_amount\": 1000,\n \"usd_exchange_rate\": 573.903191,\n \"minimum_deposite\": 100,\n \"maximum_deposite\": 10000000000,\n \"weckly_deposite\": 100000000000,\n \"min_withdraw\": 1000,\n \"max_withdraw\": 10000000000,\n \"weekly_withdraw\": 100000000000,\n \"transfer_fee\": 0,\n \"swap_min_fee\": 0,\n \"swap_rate\": 0,\n \"deposite\": false,\n \"withdraw\": true,\n \"is_display\": true,\n \"status\": \"active\",\n \"swap_status\": false,\n \"merchant_status\": \"active\",\n \"total_balance\": 8270180.16,\n \"country\": {\n \"id\": 39,\n \"name\": \"Cameroon\",\n \"code\": \"CM\",\n \"dial_code\": \"237\",\n \"flag\": \"https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/CM.svg\"\n },\n \"service\": {\n \"id\": 502,\n \"site_id\": \"3XXXXXXX6\",\n \"item_name\": \"johndoe\",\n \"service_name\": \"johndoe\",\n \"service_type\": \"default\",\n \"success_url\": \"https://stage-merchant.futurapay.com/wallet-management\",\n \"faild_url\": \"https://stage-merchant.futurapay.com/wallet-management\",\n \"notification_url\": \"https://stage-merchant.futurapay.com/wallet-management\",\n \"description\": \"default_service_name\",\n \"logo_url\": \"https://stage-payment-widget.futurapay.com/widget/withdrawal/assets/img/logo.png\",\n \"city\": \"Kolkata\",\n \"email\": \"john.doe@yopmail.com\",\n \"service_status\": \"approved\",\n \"status\": \"active\",\n \"desposit_status\": true,\n \"withdraw_status\": true,\n \"who_pays_for_fee\": \"user\"\n },\n \"getway_configuration\": [\n {\n \"id\": 162,\n \"primary_key\": null,\n \"type\": \"disbursement\",\n \"api_key\": \"b0faXXXXXXXXXXXXXXXXXXXXXXXaf02\",\n \"api_user\": \"seXXXXXXXXXXXXd9\",\n \"payment_server_url\": \"https://sandbox.momodeveloper.mtn.com/\",\n \"minimum_fees\": 2,\n \"fee_in_percentage\": 2,\n \"comments\": null,\n \"awaiting_comments\": \"NA\",\n \"status\": \"active\",\n \"gateway\": {\n \"id\": 1,\n \"name\": \"MTN Money\",\n \"logo\": \"/img/getway/MTN-Logo.png\",\n \"payment_method\": \"MTN Money\",\n \"is_crypto\": 0,\n \"comments\": \"NA\",\n \"lookup_currency\": null\n }\n }\n ]\n }\n ]\n}\n\nDescription:
\nThis endpoint allows merchants to update the status of an existing payment transaction. The update is secured through a hash_token and requires Bearer Token authentication.
Typical statuses include:
\ninitiated – Transaction has been created and is awaiting processing.
pending – Transaction is in progress and awaiting confirmation.
success – Transaction completed successfully.
failed – Transaction failed due to an error or rejection.
cancelled – Transaction was cancelled by the merchant or system.
This endpoint is essential for synchronizing the merchant’s system with the latest transaction state.
\nAuthorization:
\nAuthorization: Bearer {{rest_api_token}}) obtained from the Merchant Token Generate API.Body Parameters (form-data):
\nhash_token (string, required) – Unique token provided during payment initiation to validate the update request.
status (string, required) – New status of the transaction. Allowed values: initiated, pending, success, failed, cancelled.
gateway_id (integer, required) – Identifier for the payment gateway used. Must match the value returned in the /payments/initiate API under data.gateway_configuration.gateway.id.
Example Gateway IDs:
\n1 => MTN Money
2 => Bitcoin (BTC)
3 => Orange Money
Use Case:
\nUpdate a transaction’s state after receiving confirmation from a payment gateway.
\nEnsure the merchant’s system reflects the latest payment progress (success, failed, cancelled).
\nKeep records synchronized across services.
\nDescription:
\nThis endpoint allows merchants to update the crypto wallet address of an existing transaction.
\nIt ensures that users can provide a new wallet address in case the initially provided one is invalid, expired, or needs to be changed before payment completion.
\nThe request must include a valid hash_token associated with the transaction. This route is protected and requires Bearer Token authentication via the auth:sanctum middleware.
Authorization:
\nAuthorization: Bearer {{rest_api_token}}) obtained from the Merchant Token Generate API.Body Parameters (form-data):
\nhash_token (string, required) – Unique token generated during payment initiation. It validates and links the update request to a specific transaction.
gateway_id (integer, required) – Identifier for the crypto payment gateway. Must match the id returned in the /payments/initiate API under data.gateway_configuration.gateway.id.
Example Gateway IDs:
\n2 => Bitcoin (BTC)
4 => Ethereum (ETH)
5 => USDT (Tether)
Use Cases:
\nCorrect or replace an incorrect crypto wallet address provided during payment initiation.
\nEnsure payment is routed to the right crypto wallet for settlement.
\nUpdate wallet address before transaction confirmation for security or operational reasons.
\nExample Request:
\n{\n \"hash_token\": \"64853XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX9c03d\",\n \"gateway_id\": 2\n}\n\nExample Response (200 OK):
\n{\n \"success\": true,\n \"message\": \"Payment crypto wallet address has been updated successfully.\",\n \"data\": {\n \"country_id\": 39,\n \"gateway_id\": 2,\n \"currency_code\": \"XAF\",\n \"wallet_address\": \"bc1*********************************yyvj\",\n \"code\": \"BTC\",\n \"network\": \"BITCOIN\",\n \"status\": \"active\"\n }\n}\n\nError Responses:
\n401 Unauthorized – Invalid or missing Bearer Token.
403 Forbidden – Invalid hash_token or token expired.
422 Unprocessable Entity – Missing or invalid parameters (e.g., unsupported gateway_id).
404 Not Found – Transaction not found for the given hash_token.