Skip to main content
A withdrawal moves funds from your Syncgram Pay balance to a payout destination. You can send same-currency payouts or cross-currency transfers — Syncgram Pay handles the FX conversion automatically when you provide a locked quote.

​
Withdrawal flow

1

Get a fee estimate

Preview the fee, exchange rate, and net amounts before creating the withdrawal. No funds are moved at this step.
2

Lock an exchange rate (cross-currency only)

For payouts where from_currency and to_currency differ, create a quote to lock the exchange rate for the duration of your transaction.
3

Create the withdrawal

Submit the withdrawal with your destination details, amount, and reference. Pass the quote_id if you created one in the previous step.

​
Get a fee estimate

Preview the full cost breakdown for a withdrawal before submitting it. 
GET /api/v1/payouts/fees?from_currency=USD&payout_method=BANK_TRANSFER
Query parameters
ParameterTypeDescription
from_currencystringThe currency you are paying out from, e.g. USD, NGN.
payout_methodstringThe payout method: BANK_TRANSFER, MOBILE_MONEY, or CRYPTO.
Response 
{
  "from_currency": "USD",
  "payout_method": "BANK_TRANSFER",
  "fee_type": "percentage",
  "fee_value": "1.5"
}

​
Estimate a withdrawal

Get a detailed breakdown including the exchange rate and the exact amount the recipient will receive. 
POST /api/v1/payouts/estimate
Request 
{
  "from_currency": "USD",
  "to_currency": "NGN",
  "amount": "500.00",
  "payout_method": "BANK_TRANSFER"
}
Response 
{
  "from_currency": "USD",
  "to_currency": "NGN",
  "amount": "500.00",
  "payout_method": "BANK_TRANSFER",
  "withdrawal_fee": "7.50",
  "net_from_amount": "492.50",
  "exchange_rate": "1540.00",
  "to_amount": "758450.00"
}
​
amount
string
The gross amount you are sending, in from_currency.
​
withdrawal_fee
string
The fee deducted from your balance, in from_currency.
​
net_from_amount
string
The amount after fees that is converted and sent, in from_currency.
​
exchange_rate
string
The indicative exchange rate at the time of the estimate. This rate is not locked — use Create a quote to lock it.
​
to_amount
string
The estimated amount the recipient receives, in to_currency.

​
Create a quote

Lock an exchange rate for a cross-currency payout. The quote expires after a short window — submit your withdrawal before it expires. 
POST /api/v1/payouts/quotes
Request 
{
  "from_currency": "USD",
  "to_currency": "NGN",
  "amount": "500.00",
  "payout_method": "BANK_TRANSFER"
}
Response 
{
  "quote_id": "q_01abc...",
  "from_currency": "USD",
  "to_currency": "NGN",
  "from_amount": "500.00",
  "to_amount": "758450.00",
  "exchange_rate": "1540.00",
  "expires_at": "2026-03-15T10:05:00Z"
}
Quotes expire quickly. Create your withdrawal immediately after receiving a quote_id. If the quote expires, create a new one before retrying.

​
Supported currencies

List the currencies supported for a given payout method. 
GET /api/v1/payouts/supported-currencies?method=BANK_TRANSFER
Response 
{
  "method": "BANK_TRANSFER",
  "currencies": ["NGN", "GHS", "KES", "USD"]
}

​
Create a withdrawal

Submit a withdrawal request to initiate a payout. 
POST /api/v1/payouts/withdrawals

​
Request fields

​
from_currency
string
required
The currency you are paying out from. Must match your available balance currency.
​
to_currency
string
required
The currency the recipient receives. Use the same value as from_currency for same-currency payouts.
​
amount
string
required
The gross amount to send, in from_currency.
​
payment_method
string
required
The payout method: BANK_TRANSFER, MOBILE_MONEY, or CRYPTO.
​
reference
string
required
Your unique reference for this payout. Used together with idempotency_key to deduplicate requests.
​
email
string
required
Notification email for this withdrawal.
​
idempotency_key
string
A unique key to prevent duplicate payouts. If you retry a request with the same key, Syncgram Pay returns the original response. Cached for 30 minutes.
​
quote_id
string
The ID of a locked quote. Required for cross-currency payouts to guarantee the exchange rate.
​
payout_destination_id
string
The ID of a saved destination. When provided, Syncgram Pay uses the stored payment details.
​
account_number
string
Bank account number. Required for BANK_TRANSFER payouts when payout_destination_id is not set.
​
bank_code
string
Bank routing code. Required for BANK_TRANSFER payouts when payout_destination_id is not set.
​
phone_number
string
Recipient phone number. Required for MOBILE_MONEY payouts when payout_destination_id is not set.
​
wallet_address
string
On-chain wallet address. Required for CRYPTO payouts when payout_destination_id is not set.
​
network
string
Blockchain network, e.g. TRC20, ERC20. Required for CRYPTO payouts when the network is not encoded in to_currency.
​
memo
string
Optional memo or tag for crypto transfers.
​
description
string
Optional internal note for your records.
​
metadata
object
Optional key-value pairs for your own use. Not processed by Syncgram Pay.

​
Examples

{
  "from_currency": "USD",
  "to_currency": "NGN",
  "amount": "500.00",
  "payment_method": "BANK_TRANSFER",
  "reference": "payout-2026-03-15-001",
  "email": "finance@example.com",
  "idempotency_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "quote_id": "q_01abc...",
  "payout_destination_id": "dest_01abc..."
}

​
Response

{
  "withdrawal_id": "wd_01abc...",
  "status": "PENDING",
  "provider_reference": "ext_ref_abc123"
}
​
withdrawal_id
string
The Syncgram Pay withdrawal ID. Use this to track the payout status.
​
status
string
Initial status of the withdrawal: PENDING, PROCESSING, COMPLETED, or FAILED.
​
provider_reference
string
The payment provider’s reference for this payout. May be null for asynchronous processors.

​
Error cases

ErrorCauseResolution
Insufficient balanceYour available balance is less than the withdrawal amount plus fees.Check your balance before initiating a withdrawal.
Unsupported currencyThe from_currency or to_currency is not supported for the selected payment_method.Call GET /api/v1/payouts/supported-currencies to verify supported currencies.
Expired quoteThe quote_id you provided has expired.Create a new quote and retry.
Duplicate requestA withdrawal with the same idempotency_key is already being processed.Wait briefly and retry — the original response will be returned once processing completes.
Do not create a new withdrawal if you receive a duplicate-processing error. Retry with the same idempotency_key to retrieve the original result.