Prefunded Quote (Internal Wallet)

This guide covers how to create a prefunded quote and settle it using your internal wallet balance. A prefunded quote is identical to a standard quote — the only difference is the sourceWallet field, which tells Mavapay to deduct the source amount directly from your internal wallet instead of expecting an external bank transfer or Lightning payment.

Prefunded Quote Flow

Performing a prefunded payout is a two-step process: Requesting a Quote and Accepting the Quote from your Wallet.

Step 1: Create a Prefunded Quote

The quote endpoint calculates the exchange rate and fees. The request is the same as a standard quote, with one addition: the sourceWallet field.

The sourceWallet field is the only difference between a prefunded quote and a regular quote. It specifies which internal wallet to debit for the source amount. The value must correspond to the sourceCurrency in the quote body (e.g. USDTCENT → USDT, BTCSAT → BTC, NGNKOBO → NGN).

curl --location 'https://api.mavapay.co/api/v1/quote' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '{
    "amount": "1000",
    "sourceCurrency": "USDTCENT",
    "targetCurrency": "NGNKOBO",
    "paymentMethod": "ONCHAIN",
    "paymentCurrency": "USDTCENT",
    "sourceWallet": "USDT",
    "autopayout": true,
    "beneficiary": {
        "bankAccountNumber": "7012345678",
        "bankAccountName": "Example Customer",
        "bankCode": "100004",
        "bankName": "OPAY"
    }
}'

Step 2: The Quote Response

Mavapay returns a quote object. Key field to note:

id — Use this when accepting the quote from your wallet.

Note: Quotes are typically valid for 5–10 minutes. You must accept before the expiry timestamp.

{
  "status": "ok",
  "data": {
    "id": "b01af569-7ad3-4803-ad3c-4aa368ee98bf",
    "exchangeRate": 109495302.39059484,
    "usdToTargetCurrencyRate": 1374.033506,
    "sourceCurrency": "USDTCENT",
    "targetCurrency": "NGNKOBO",
    "transactionFeesInSourceCurrency": 8,
    "transactionFeesInTargetCurrency": 10305,
    "amountInSourceCurrency": 1000,
    "amountInTargetCurrency": 1363041,
    "paymentMethod": "ONCHAIN",
    "expiry": "2026-08-27T11:16:41.564Z",
    "isValid": true,
    "invoice": "",
    "hash": "",
    "totalAmountInSourceCurrency": 1000,
    "customerInternalFee": 0,
    "invoiceRequired": false,
    "onchainAddress": "MPY_USDTCENT_1787828801564",
    "network": "trc20",
    "memo": "MAVAPAY_INTERNAL",
    "orderId": "260827-GDTV6-28K3N"
  }
}

Step 3: Accept and Settle from Wallet

To finalize the payout, call the accept endpoint. This will immediately deduct the totalAmountInSourceCurrency from your internal wallet and process the payout to the beneficiary.

Endpoint: POST .../wallet/payout/{quoteId}/accept
Payload: The sourceWallet value must match the one used in the original quote.

curl --location 'https://api.mavapay.co/api/v1/wallet/payout/b01af569-7ad3-4803-ad3c-4aa368ee98bf/accept' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '{
    "sourceWallet": "USDT"
}'

200 Response:

{
    "status": "ok",
    "message": "quote is being processed"
}

400 Response (Insufficient Balance):

{
    "status": "error",
    "message": "Error processing internal transfer: Insufficient balance in USDT wallet"
}

Key Considerations

Sufficient Balance: Ensure your internal wallet has enough funds to cover the totalAmountInSourceCurrency (which includes fees).
Rate Volatility: Because exchange rates change rapidly, the quote id is short-lived. If it expires, you must generate a new quote.
Denominations: All amounts are in the lowest denomination (cents for USDTCENT, kobo for NGNKOBO, satoshis for BTCSAT).

Create Quote API — Full quote endpoint reference
Accept Quote API — Wallet accept endpoint reference
Beneficiary Formats — Required beneficiary formats for each currency
Internal Currency Swap — Similar flow for swapping between internal wallets

Get Started

Payouts

Stablecoins

Webhooks

Guides

Prefunded Quote (Internal Wallet)

Prefunded Quote Flow

Step 1: Create a Prefunded Quote

Step 2: The Quote Response

Step 3: Accept and Settle from Wallet

Key Considerations

​Prefunded Quote Flow

​Step 1: Create a Prefunded Quote

​Step 2: The Quote Response

​Step 3: Accept and Settle from Wallet

​Key Considerations

​Related Resources

Prefunded Quote Flow

Step 1: Create a Prefunded Quote

Step 2: The Quote Response

Step 3: Accept and Settle from Wallet

Key Considerations

Related Resources