Skip to main content
Send funds from your Syncgram Pay balance to an external destination. You can reference a saved payout destination by ID or supply the destination details inline. Every withdrawal requires a unique reference — use idempotency_key to safely retry requests without creating duplicate payouts.

​
Request

POST /api/v1/payouts/withdrawals
Authentication: API key or JWT (Authorization: Bearer <token>)
​
from_currency
string
required
The currency to debit from your balance. Example: USD, NGN.
​
to_currency
string
required
The currency the recipient will receive. Example: NGN, USDT_TRC20.
​
amount
number
required
The amount to send, denominated in from_currency.
​
payment_method
string
required
Payout method. One of: BANK_TRANSFER, MOBILE_MONEY, CRYPTO.
​
reference
string
required
A unique reference for this withdrawal in your system. Must be unique per organization. Used as a fallback idempotency key.
​
email
string
required
Email address associated with this withdrawal for notification and record purposes.
​
idempotency_key
string
An explicit idempotency key. If provided, this key takes precedence over the auto-derived key built from reference. Use this to safely retry requests — duplicate requests with the same key return the original response without creating a second withdrawal.
​
quote_id
string
A quote ID from POST /api/v1/payouts/quotes. If provided, the locked exchange rate from that quote is used for this withdrawal.
​
payout_destination_id
string
The ID of a saved payout destination. If provided, the destination fields below are not required.
​
account_number
string
Bank account number. Required for BANK_TRANSFER if not using payout_destination_id.
​
bank_code
string
Bank code. Required for BANK_TRANSFER if not using payout_destination_id.
​
phone_number
string
Phone number. Required for MOBILE_MONEY if not using payout_destination_id.
​
wallet_address
string
Crypto wallet address. Required for CRYPTO if not using payout_destination_id.
​
network
string
Blockchain network, e.g., TRC20, ERC20. Required for CRYPTO when the network is not implied by to_currency.
​
memo
string
Optional memo or tag for crypto transfers that require one (e.g., XRP, EOS).
​
description
string
Optional human-readable description for the withdrawal.
​
payment_rail
string
Optional override for the payment rail. Leave unset to let Syncgram Pay select the appropriate rail automatically.
​
metadata
object
Arbitrary key-value pairs you want to attach to the withdrawal for your own tracking.

​
Response

​
withdrawal_id
string
The unique identifier for the withdrawal created by Syncgram Pay.
​
status
string
Current status of the withdrawal. Common values: PENDING, PROCESSING, COMPLETED, FAILED.
​
provider_reference
string
The reference returned by the downstream payout provider. May be null if the provider has not yet assigned one.
{
  "withdrawal_id": "wd_01j9kxp4q8m2r3t5v6w7y8z9",
  "status": "PENDING",
  "provider_reference": "KRA-20240115-00432"
}

​
Error codes

StatusDescription
400 Bad RequestMissing required fields, unsupported currency, or invalid destination details
409 ConflictA withdrawal with this idempotency key is currently being processed — retry after a short delay
422 Unprocessable EntityValidation error on one or more fields

​
Example

curl -X POST https://api.syncgrampay.com/api/v1/payouts/withdrawals \
  -H "Authorization: Bearer sk_live_01j..." \
  -H "Content-Type: application/json" \
  -d '{
    "from_currency": "USD",
    "to_currency": "NGN",
    "amount": 500,
    "payment_method": "BANK_TRANSFER",
    "reference": "payout-2024-00123",
    "email": "recipient@example.com",
    "account_number": "0123456789",
    "bank_code": "033"
  }'
If you retry a failed request, pass the same idempotency_key (or the same reference if you did not supply one). Syncgram Pay will return the cached response for up to 30 minutes rather than creating a second withdrawal.