Home page

REST API Documentation

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.

Authentication & Credentials

Each 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:

Merchant > My Profile → Merchant Key
Merchant > Settings > Services → Site ID & API Key

All requests must include these credentials to ensure secure communication and prevent unauthorized access.

Currency & Country Support

Futurapay 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/currencies

This ensures that merchants always use valid and up-to-date codes when initiating transactions.

Transaction Flow

Merchants initiate a deposit by submitting essential customer and transaction details, such as:

Customer Information: First name, last name, phone number, and email.
Transaction Details: Unique transaction ID (provided by the merchant), amount, currency, and country.

The customer_transaction_id must be unique for every request, enabling both Futurapay and the merchant to track and reconcile payments accurately.

Security Considerations

All requests should be made over HTTPS to ensure data encryption.
API keys and merchant credentials must be kept confidential.
Input validation is strictly enforced to prevent errors and fraudulent activities.

Error Handling

Futurapay 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.

Best Practices

Generate and store unique transaction IDs for each deposit.
Validate customer inputs (phone, email, amount format) before sending to the API.
Regularly refresh available currencies and country codes from the public endpoint to avoid rejections.
Monitor error responses to fine-tune integration and improve reliability.

Endpoints

Stage Host: https://stage-api.futurapay.com/
Live Host: https://api.futurapay.com/

📄 API Documentation

Swagger Documentation:
https://api.futurapay.com/restapi/documentation

Postman Documentation:
https://documenter.getpostman.com/view/33364285/2sB3HgNNTd

Currency List

Method: GET

Endpoint:

/restapi/v1/public/currencies

Description

Retrieves a list of all active currencies supported by the platform. Each currency entry includes its code, name, and other relevant details required for transactions.

Use Case

Display available currencies in a dropdown for deposits, withdrawals, or checkout flows.
Validate whether a requested currency is supported before processing payments.

Example Response

{
  "success": true,
  "message": "Currencies fetched successfully",
  "data": [
    {
      "id": 1,
      "name": "Afghani",
      "code": "AFN",
      "symbol": "AFN",
      "usd_exchange_rate": 69.000227,
      "minimum_deposite": 500,
      "maximum_deposite": 10000,
      "country": {
        "id": 1,
        "name": "Afghanistan",
        "code": "AF",
        "dial_code": "93",
        "flag": "https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/AF.svg"
      }
    }
  ]
}

Error Response

{
  "success": false,
  "message": "Failed to fetch currencies. Please try again later.",
  "error_code": 500
}

Country List

Method: GET

Endpoint:

/restapi/v1/public/countries

Description

Retrieves a list of countries supported by the system for transactions and services. Each entry typically includes country code and name.

Use Case

Populate a country selection dropdown during onboarding or checkout.
Validate user country eligibility for services or payment processing.

Example Response

{
  "success": true,
  "message": "Countries fetched successfully",
  "data": [
    {
      "id": 1,
      "name": "Afghanistan",
      "code": "AF",
      "dial_code": "93",
      "flag": "https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/AF.svg"
    }
  ]
}

Error Response

{
  "success": false,
  "message": "Failed to fetch countries. Please try again later.",
  "error_code": 500
}

Merchant Token Generate

Method: POST

Endpoint:

/restapi/v1/auth/merchant/token/generate

Description

This endpoint is used to authenticate a merchant by generating an access token.

The 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)

merchant_key (string, required) – The unique key assigned to the merchant.

Use Case

Authenticate a merchant before accessing protected APIs.
Generate a secure access token to include in the Authorization header for subsequent requests.

Example Response

{
  "success": true,
  "message": "Merchant token generated successfully.",
  "data": {
    "token": "2818|bcD3**********************************f0ed"
  }
}

Error Response

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "merchant_key": [
      "The selected merchant key is invalid."
    ]
  }
}

Merchant Currency List

Method: GET

Endpoint:

/restapi/v1/merchant/currencies

Description

Retrieves the list of currencies, balances, and services available to an authenticated merchant.

This endpoint requires a valid Bearer Token obtained from the /auth/merchant/token/generate API.

Authorization

Bearer Token – Use the token returned from /auth/merchant/token/generate.

Use Case

Get all currencies a merchant can transact with.
Fetch current balances in different currencies.
Retrieve supported services available for the merchant.

Example Response

{
  "success": true,
  "message": "Merchant currencies fetched successfully.",
  "data": [
    {
      "id": 9,
      "name": "CFA Franc (BEAC)",
      "code": "XAF",
      "symbol": "XAF",
      "type": "Flat",
      "usd_equivalence": 105857.8,
      "freemium_amount": 1000,
      "usd_exchange_rate": 573.903191,
      "minimum_deposite": 100,
      "maximum_deposite": 10000000000,
      "weckly_deposite": 100000000000,
      "min_withdraw": 1000,
      "max_withdraw": 10000000000,
      "weekly_withdraw": 100000000000,
      "transfer_fee": 0,
      "swap_min_fee": 0,
      "swap_rate": 0,
      "deposite": false,
      "withdraw": true,
      "is_display": true,
      "status": "active",
      "swap_status": false,
      "merchant_status": "active",
      "total_balance": 8270180.16,
      "country": {
        "id": 39,
        "name": "Cameroon",
        "code": "CM",
        "dial_code": "237",
        "flag": "https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/CM.svg"
      },
      "service": {
        "id": 502,
        "site_id": "3XXXXXXX6",
        "item_name": "johndoe",
        "service_name": "johndoe",
        "service_type": "default",
        "success_url": "https://stage-merchant.futurapay.com/wallet-management",
        "faild_url": "https://stage-merchant.futurapay.com/wallet-management",
        "notification_url": "https://stage-merchant.futurapay.com/wallet-management",
        "description": "default_service_name",
        "logo_url": "https://stage-payment-widget.futurapay.com/widget/withdrawal/assets/img/logo.png",
        "city": "Kolkata",
        "email": "john.doe@yopmail.com",
        "service_status": "approved",
        "status": "active",
        "desposit_status": true,
        "withdraw_status": true,
        "who_pays_for_fee": "user"
      },
      "getway_configuration": [
        {
          "id": 162,
          "primary_key": null,
          "type": "disbursement",
          "api_key": "b0faXXXXXXXXXXXXXXXXXXXXXXXaf02",
          "api_user": "seXXXXXXXXXXXXd9",
          "payment_server_url": "https://sandbox.momodeveloper.mtn.com/",
          "minimum_fees": 2,
          "fee_in_percentage": 2,
          "comments": null,
          "awaiting_comments": "NA",
          "status": "active",
          "gateway": {
            "id": 1,
            "name": "MTN Money",
            "logo": "/img/getway/MTN-Logo.png",
            "payment_method": "MTN Money",
            "is_crypto": 0,
            "comments": "NA",
            "lookup_currency": null
          }
        }
      ]
    }
  ]
}

Error Responses

401 – Unauthorized

{
  "status": false,
  "message": "UnAuthenticated User"
}

500 – Internal Server Error

{
  "success": false,
  "message": "Failed to fetch currencies. Please try again later.",
  "errors": []
}

Payment Status Update

Method: POST

Endpoint:

/restapi/v1/payments/status/update

Description

This 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:

initiated – 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.

Authorization

Requires Bearer Token (Authorization: Bearer {{rest_api_token}}) obtained from the /auth/merchant/token/generate API.

Body Parameters (form-data)

hash_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:

1 ⇒ MTN Money
2 ⇒ Bitcoin (BTC)
3 ⇒ Orange Money

Use Case

Update a transaction’s state after receiving confirmation from a payment gateway.
Ensure the merchant’s system reflects the latest payment progress (success, failed, cancelled).
Keep records synchronized across services.

Example Response

{
  "success": true,
  "message": "Payment status has been updated successfully.",
  "data": {
    "transaction_id": "txn46XXXXXXXXXXXX17",
    "customer_transaction_id": "58XXXXXXXX45",
    "type": "collection",
    "status": "initiated",
    "amount": 0.00091035,
    "initiate_amount": 55000,
    "usd_equivalence": 95.83,
    "currency_code": "BTC",
    "fee_amount": 2223.9,
    "payment_method": "Bitcoin (BTC)",
    "transaction_date": "2025-07-18",
    "transaction_time_utc": "2025-07-18 09:30:28"
  }
}

Error Responses

404 – Not Found or Status Mismatch

{
  "success": false,
  "message": "Transaction status is not initiated.",
  "errors": []
}

422 – Validation Error

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}

Payments Crypto Wallet Address Update

Method: POST

Endpoint:

/restapi/v1/payments/crypto/wallet/address/update

Description

This endpoint allows merchants to update the crypto wallet address of an existing transaction.

It 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.

The 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

Requires Bearer Token (Authorization: Bearer {{rest_api_token}}) obtained from the /auth/merchant/token/generate API.

Body Parameters (form-data)

hash_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:

2 ⇒ Bitcoin (BTC)
4 ⇒ Ethereum (ETH)
5 ⇒ USDT (Tether)

Use Cases

Correct or replace an incorrect crypto wallet address provided during payment initiation.
Ensure payment is routed to the right crypto wallet for settlement.
Update wallet address before transaction confirmation for security or operational reasons.

Example Response

{
  "success": true,
  "message": "Payment crypto wallet address has been updated successfully.",
  "data": {
    "country_id": 39,
    "gateway_id": 2,
    "currency_code": "XAF",
    "wallet_address": "bc1*********************************yyvj",
    "code": "BTC",
    "network": "BITCOIN",
    "status": "active"
  }
}

Error Responses

404 – Not Found or Status Mismatch

{
  "success": false,
  "message": "Transaction status is not initiated.",
  "errors": []
}

422 – Validation Error

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "hash_token": [
      "The selected hash token is invalid."
    ]
  }
}

Deposit Payment Initiate

Method: POST

Endpoint:

/restapi/v1/payments/initiate

Description

This 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.

The API request must be authenticated using a valid Bearer Token (generated via the Merchant Token Generate endpoint).

Once initiated, the API returns transaction details including payment gateway configuration, transaction reference, and other metadata required for processing the deposit.

Authorization

Requires Bearer Token (Authorization: Bearer {{rest_api_token}}) obtained from the Merchant Token Generate API.

Parameters

Parameter	Type	Required	Description
`merchant_key`	string	✅	Unique merchant identifier. 🔑 Obtain from: Merchant > My Profile > Merchant Key
`site_id`	integer	✅	Unique identifier for the merchant site/service. 🔑 Obtain from: Merchant > Settings > Services > Site ID
`api_key`	string	✅	API key associated with the merchant’s service/site. 🔑 Obtain from: Merchant > Settings > Services > API Key
`currency_code`	string	✅	Currency in which the transaction is initiated (e.g., `XAF`, `USD`, `BTC`). 🔑 Retrieve from: `/restapi/v1/public/merchant/currencies` under `data.currency.code`
`country_code`	string	✅	ISO 2-digit country code (e.g., `CM`, `NG`, `US`). 🔑 Retrieve from: `/restapi/v1/public/merchant/currencies` under `data.country.code`
`customer_first_name`	string	✅	First name of the customer making the deposit.
`customer_last_name`	string	❌	Last name of the customer.
`customer_phone`	string	✅	Customer’s phone number (international format recommended).
`customer_email`	string	✅	Email address of the customer.
`customer_transaction_id`	string	✅	Unique transaction reference provided by the merchant (must be unique per request).
`amount`	decimal	✅	Amount to be deposited, expressed in the specified `currency_code`.

Example Response

{
  "success": true,
  "message": "Payment initiated successfully.",
  "data": {
    "currency": {
      "id": 9,
      "name": "CFA Franc (BEAC)",
      "code": "XAF",
      "symbol": "XAF",
      "usd_exchange_rate": 573.903191,
      "minimum_deposite": 100,
      "maximum_deposite": 10000000000,
      "country": {
        "id": 39,
        "name": "Cameroon",
        "code": "CM",
        "dial_code": "237",
        "flag": "https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/CM.svg"
      }
    },
    "gateway_configuration": [
      {
        "id": 188,
        "primary_key": "XXXXXXXXXXXXXXXXXXX",
        "type": "collection",
        "api_key": "XXXXXXXXXXXXXXXXXXXXX",
        "api_user": "At lorem dolorem lab",
        "payment_server_url": "https://www.paymentserverurl.com",
        "minimum_fees": 0,
        "fee_in_percentage": 0,
        "comments": "Amet mollit laboris",
        "awaiting_comments": "Est explicabo Culpa",
        "status": "active",
        "gateway": {
          "id": 15,
          "name": "FuturaPay(No fee)",
          "logo": "/img/icons/logo.png",
          "payment_method": "FuturaPay",
          "is_crypto": 0,
          "comments": ".",
          "lookup_currency": [
            {
              "currency_code": "AFN",
              "country": {
                "id": 1,
                "name": "Afghanistan",
                "code": "AF",
                "dial_code": "93",
                "flag": "https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/AF.svg"
              }
            }
          ]
        }
      }
    ],
    "merchant_service": {
      "id": 100,
      "site_id": "3XXXXXXX6",
      "item_name": "johndoe",
      "service_name": "johndoe",
      "service_type": "default",
      "success_url": "https://stage-merchant.futurapay.com/wallet-management",
      "faild_url": "https://stage-merchant.futurapay.com/wallet-management",
      "notification_url": "https://stage-merchant.futurapay.com/wallet-management",
      "description": "default_service_name",
      "logo_url": "https://stage-payment-widget.futurapay.com/widget/withdrawal/assets/img/logo.png",
      "city": "Kolkata",
      "email": "john.doe@yopmail.com",
      "service_status": "approved",
      "status": "active",
      "desposit_status": true,
      "withdraw_status": true,
      "who_pays_for_fee": "user"
    },
    "has_token": "76a8********************************************************25cd",
    "amount": "55000",
    "customer_email": "john.doe@yopmail.com",
    "customer_transaction_id": "6**********5",
    "country": {
      "id": 39,
      "name": "Cameroon",
      "code": "CM",
      "dial_code": "237",
      "flag": "https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/CM.svg"
    }
  }
}

Error Responses

401 – Unauthorized - Token missing or invalid.

{
  "status": false,
  "message": "UnAuthenticated User"
}

422 – Validation Error

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "currency_code": [
      "The currency code field is required."
    ]
  }
}

500 – Server Error - Payment could not be initiated.

{
  "success": false,
  "message": "An unexpected error occurred while initiating the payment. Please try again later or contact support.",
  "errors": []
}

Deposit Payment Processed

Method: POST

Endpoint:

/restapi/v1/payments/processed

Description

Processes a payment request using a valid hash_token. This endpoint allows initiating a payment transaction with an associated phone number.

The receiver_email field is optional and can be included if the payment confirmation should also be sent via email.

The API request must be authenticated using a valid Bearer Token (via the auth:sanctum middleware).

Authorization

Requires Bearer Token (Authorization: Bearer {{rest_api_token}}) obtained via the authentication system.

Parameters

Parameter	Type	Required	Description
`hash_token`	string	✅	A valid hash token generated for the transaction.
`phone_number`	string	✅	Customer’s phone number associated with the payment request.
`receiver_email`	string	❌	Email of the receiver (optional, for payment confirmation).

Example Responses

{
  "success": true,
  "message": "Payment processed successfully.",
  "data": {
    "id": 13308,
    "uuid": "d63XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX52ed",
    "transaction_id": "txn6XXXXXXXXXXXXX83",
    "status": "pending",
    "amount": 0.00091035,
    "currency_code": "BTC",
    "net_amount": 55000,
    "fee_amount": 2223.9,
    "transaction_date": "2025-07-18",
    "transaction_datetime": "2025-07-18 12:39:52",
    "payment_method": "Bitcoin (BTC)",
    "gateway_response": null,
    "service": {
      "id": 502,
      "site_id": "3XXXXXXX6",
      "item_name": "johndoe",
      "service_name": "johndoe",
      "service_type": "default",
      "success_url": "https://stage-merchant.futurapay.com/wallet-management",
      "faild_url": "https://stage-merchant.futurapay.com/wallet-management",
      "notification_url": "https://stage-merchant.futurapay.com/wallet-management",
      "description": "default_service_name",
      "logo_url": "https://stage-payment-widget.futurapay.com/widget/withdrawal/assets/img/logo.png",
      "city": "Kolkata",
      "email": "john.doe@yopmail.com",
      "service_status": "approved",
      "status": "active",
      "desposit_status": true,
      "withdraw_status": true,
      "who_pays_for_fee": "user"
    },
    "gateway_config": {
      "id": 3,
      "primary_key": "NA",
      "type": "collection",
      "api_key": "keyXXXXXXXXXXXXfde",
      "api_user": "se6XXXXXXXXXXXXfdf",
      "payment_server_url": "https://www.mtn.bitcoin.com",
      "minimum_fees": 1,
      "fee_in_percentage": 3,
      "comments": "Send the exact Bitcoin amount with all decimals (Do not enter the USD amount).",
      "awaiting_comments": "Send the exact Bitcoin amount with all decimals (Do not enter the USD amount).",
      "status": "active",
      "gateway": {
        "id": 2,
        "name": "Bitcoin (BTC)",
        "logo": "/img/getway/btc.png",
        "payment_method": "BTC",
        "is_crypto": 1,
        "comments": "Send the exact Bitcoin amount with all decimals (Do not enter the USD amount).",
        "lookup_currency": null
      }
    }
  }
}

Example Error Responses

404 – Transaction status is not initiated

{
  "success": false,
  "message": "Transaction status is not initiated.",
  "errors": []
}

422 – Validation Error

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "hash_token": [
      "The selected hash token is invalid."
    ]
  }
}

Withdraw Payment Initiate

Method: POST

Endpoint:

/restapi/v1/payments/withdraw/initiate

Description

This 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.

The API request must be authenticated using a valid Bearer Token (generated via the Merchant Token Generate endpoint).

Once initiated, the API returns transaction details including payment gateway configuration, transaction reference, and other metadata required for processing the withdraw.

Authorization

Requires Bearer Token (Authorization: Bearer {{rest_api_token}}) obtained from the Merchant Token Generate API.

Parameters

Parameter	Type	Required	Description
`merchant_key`	string	✅	Unique merchant identifier. 🔑 Obtain from: Merchant > My Profile > Merchant Key
`site_id`	integer	✅	Unique identifier for the merchant site/service. 🔑 Obtain from: Merchant > Settings > Services > Site ID
`api_key`	string	✅	API key associated with the merchant’s service/site. 🔑 Obtain from: Merchant > Settings > Services > API Key
`currency_code`	string	✅	Currency in which the transaction is initiated (e.g., `XAF`, `USD`, `BTC`). 🔑 Retrieve from: `/restapi/v1/public/merchant/currencies` under `data.currency.code`
`country_code`	string	✅	ISO 2-digit country code representing the transaction’s origin country (e.g., `CM`, `NG`, `US`). 🔑 Retrieve from: `/restapi/v1/public/merchant/currencies` under `data.country.code`
`customer_first_name`	string	✅	First name of the customer making the withdraw.
`customer_last_name`	string	❌	Last name of the customer.
`customer_phone`	string	✅	Customer’s phone number (international format recommended).
`customer_email`	string	✅	Email address of the customer.
`customer_transaction_id`	string	✅	Unique transaction reference provided by the merchant for tracking (must be unique per request).
`amount`	decimal	✅	Amount to be withdrawn, expressed in the specified `currency_code`.

Body Request

{
  "merchant_key": "66*******9d",
  "site_id": "3********6",
  "api_key": "apiKey6XXXXXXXXXXd6",
  "currency_code": "XAF",
  "country_code": "CM",
  "customer_first_name": "John",
  "customer_last_name": "Doe",
  "customer_phone": "9876543210",
  "customer_email": "johndoe@yopmail.com",
  "customer_transaction_id": "TXN123456789",
  "amount": 55000
}

Example Response

{
  "success": true,
  "message": "Withdraw payment initiated successfully.",
  "data": {
    "currency": {
      "id": 10,
      "name": "Euro",
      "code": "EUR",
      "symbol": "EUR",
      "usd_exchange_rate": 0.876006,
      "minimum_deposite": 1,
      "maximum_deposite": 1000000,
      "country": {
        "id": 82,
        "name": "Germany",
        "code": "DE",
        "dial_code": "49",
        "flag": "https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/DE.svg"
      }
    },
    "gateway_configuration": [
      {
        "id": 187,
        "primary_key": "NA",
        "type": "disbursement",
        "api_key": "NA",
        "api_user": "NA",
        "payment_server_url": "NA",
        "minimum_fees": 0,
        "fee_in_percentage": 0,
        "comments": "NA",
        "awaiting_comments": "NA",
        "status": "active",
        "gateway": {
          "id": 15,
          "name": "FuturaPay(No fee)",
          "logo": "/img/icons/logo.png",
          "payment_method": "FuturaPay",
          "is_crypto": 0,
          "comments": ".",
          "lookup_currency": [
            {
              "currency_code": "EUR",
              "country": {
                "id": 82,
                "name": "Germany",
                "code": "DE",
                "dial_code": "49",
                "flag": "https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/DE.svg"
              }
            }
          ]
        }
      }
    ],
    "merchant_service": {
      "id": 502,
      "site_id": "3XXXXXXX6",
      "item_name": "johndoe",
      "service_name": "johndoe",
      "service_type": "default",
      "success_url": "https://stage-merchant.futurapay.com/wallet-management",
      "faild_url": "https://stage-merchant.futurapay.com/wallet-management",
      "notification_url": "https://stage-merchant.futurapay.com/wallet-management",
      "description": "default_service_name",
      "logo_url": "https://stage-payment-widget.futurapay.com/widget/withdrawal/assets/img/logo.png",
      "city": "Kolkata",
      "email": "john.doe@yopmail.com",
      "service_status": "approved",
      "status": "active",
      "desposit_status": true,
      "withdraw_status": true,
      "who_pays_for_fee": "user"
    },
    "has_token": "f3de***********************************************7d8a",
    "amount": "27",
    "customer_email": "john.doe@yopmail.com",
    "customer_transaction_id": "8************9",
    "country": {
      "id": 82,
      "name": "Germany",
      "code": "DE",
      "dial_code": "49",
      "flag": "https://cdn.jsdelivr.net/npm/country-flag-emoji-json@2.0.0/dist/images/DE.svg"
    }
  }
}

Error Responses

401 – Unauthorized (Invalid or missing Bearer Token)

403 – Forbidden (Invalid merchant credentials: merchant_key, site_id, or api_key)

412 – Currency not found

{
  "success": false,
  "message": "This currency is not exits",
  "data": []
}

422 – Validation Error

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "merchant_key": [
      "The selected merchant key is invalid."
    ],
    "site_id": [
      "The selected site id is invalid."
    ],
    "customer_transaction_id": [
      "The customer transaction id has already been taken."
    ]
  }
}

500 – Server Error (Unexpected system error)

{
  "success": false,
  "message": "An unexpected error occurred while initiating the withdraw payment. Please try again later or contact support.",
  "errors": []
}

Withdraw Payment Processed

Method: POST

Endpoint:

/restapi/v1/payments/withdraw/processed

Description

Processes a withdraw payment request using a valid hash_token. This endpoint allows initiating a payment transaction with an associated phone number.

The 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 authentication using a valid Bearer Token (via the auth:sanctum middleware).

Authorization

Requires Bearer Token (Authorization: Bearer {{rest_api_token}}) obtained via the authentication system.

Parameters

Parameter	Type	Required	Description
`hash_token`	string	✅	A valid hash token generated for the transaction.
`phone_number`	string	✅	Customer’s phone number associated with the payment request.
`customer_email`	string	✅	Email of the customer (send otp code for payment confirmation).
`receiver_email`	string	❌	Email of the receiver (optional, for payment confirmation).
`otp`	numeric	❌	OTP (optional, for payment confirmation).

Example Success Responses

200 – OTP Sent

{
  "message": "OTP Sent Successfully to john.doe@yopmail.com",
  "success": true,
  "data": []
}

200 – Withdraw Payment Processed

{
  "success": true,
  "message": "Withdraw Payment processed successfully.",
  "data": {
    "id": 13308,
    "uuid": "d63XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX52ed",
    "transaction_id": "txn6XXXXXXXXXXXXX83",
    "status": "pending",
    "amount": 0.00091035,
    "currency_code": "BTC",
    "net_amount": 55000,
    "fee_amount": 2223.9,
    "transaction_date": "2025-07-18",
    "transaction_datetime": "2025-07-18 12:39:52",
    "payment_method": "Bitcoin (BTC)",
    "gateway_response": null,
    "service": {
      "id": 502,
      "site_id": "3XXXXXXX6",
      "item_name": "johndoe",
      "service_name": "johndoe",
      "service_type": "default",
      "success_url": "https://stage-merchant.futurapay.com/wallet-management",
      "faild_url": "https://stage-merchant.futurapay.com/wallet-management",
      "notification_url": "https://stage-merchant.futurapay.com/wallet-management",
      "description": "default_service_name",
      "logo_url": "https://stage-payment-widget.futurapay.com/widget/withdrawal/assets/img/logo.png",
      "city": "Kolkata",
      "email": "john.doe@yopmail.com",
      "service_status": "approved",
      "status": "active",
      "desposit_status": true,
      "withdraw_status": true,
      "who_pays_for_fee": "user"
    },
    "gateway_config": {
      "id": 3,
      "primary_key": "NA",
      "type": "collection",
      "api_key": "keyXXXXXXXXXXXXfde",
      "api_user": "se6XXXXXXXXXXXXfdf",
      "payment_server_url": "https://www.mtn.bitcoin.com",
      "minimum_fees": 1,
      "fee_in_percentage": 3,
      "comments": "Send the exact Bitcoin amount with all decimals (Do not enter the USD amount).",
      "awaiting_comments": "Send the exact Bitcoin amount with all decimals (Do not enter the USD amount).",
      "status": "active",
      "gateway": {
        "id": 2,
        "name": "Bitcoin (BTC)",
        "logo": "/img/getway/btc.png",
        "payment_method": "BTC",
        "is_crypto": 1,
        "comments": "Send the exact Bitcoin amount with all decimals (Do not enter the USD amount).",
        "lookup_currency": null
      }
    }
  }
}

Example Error Responses

404 – Transaction Not Initiated

{
  "success": false,
  "message": "Transaction status is not initiated.",
  "errors": []
}

422 – Validation Error

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "hash_token": [
      "The selected hash token is invalid."
    ]
  }
}

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "hash_token": [
      "Your payment is already done."
    ]
  }
}

412 – Invalid Currency

{
  "success": false,
  "message": "This currency is not exits",
  "data": []
}

500 – Internal Server Error

{
  "success": false,
  "message": "An unexpected error occurred while initiating the withdraw payment. Please try again later or contact support.",
  "errors": []
}

⚠️ Error Status Codes

Below are the possible error responses that may be returned by the API:

Status Code	Meaning	Description
400	Bad Request	The request was malformed or missing required parameters.
401	Unauthorized	Authentication failed. Bearer token is missing or invalid.
403	Forbidden	You do not have permission to access this resource.
404	Not Found	The requested resource could not be found on the server.
412	Precondition Failed	A required precondition for the request was not met.
422	Unprocessable Entity	Validation failed for one or more fields.
500	Internal Server Error	A server-side error occurred. Please try again later.