Skip to main content
Payout destinations let you save recipient details once and reuse them across withdrawals by passing payout_destination_id. Three destination types are supported: bank_account, mobile_money, and crypto_wallet.

​
List destinations

GET /api/v1/payouts/destinations
Authentication: API key or JWT Returns all active destinations for your organization.

​
Response

​
destinations
array
Array of payout destination objects.
​
total
integer
Total number of active destinations.
Each destination object contains:
​
id
string
Unique destination ID. Pass this as payout_destination_id when creating a withdrawal.
​
organization_id
string
The organization this destination belongs to.
​
env
string
Environment the destination was created in: test or live.
​
destination_type
string
One of: bank_account, mobile_money, crypto_wallet.
​
currency
string
Currency code for this destination, e.g., NGN, USDT_TRC20.
​
label
string
Display name for the destination. Auto-generated if not provided on creation.
​
account_number
string
Bank account number. Present for bank_account type.
​
account_name
string
Account holder name. Present for bank_account type.
​
bank_code
string
Bank code. Present for bank_account type.
​
bank_name
string
Bank name. Present for bank_account type.
​
phone_number
string
Mobile phone number. Present for mobile_money type.
​
mobile_provider
string
Mobile money provider, e.g., MTN, Vodafone. Present for mobile_money type.
​
wallet_address
string
Crypto wallet address. Present for crypto_wallet type.
​
network
string
Blockchain network, e.g., TRC20. Present for crypto_wallet type.
​
is_active
boolean
Whether the destination is active. Deleted destinations have is_active: false and are not returned by list.
​
metadata
object
Additional provider-resolved metadata, if any.
​
created_at
string
ISO 8601 timestamp when the destination was created.
​
updated_at
string
ISO 8601 timestamp when the destination was last updated.
{
  "destinations": [
    {
      "id": "dst_01j9kxp4q8m2r3t5v6w7y8z9",
      "organization_id": "org_01j8abc...",
      "env": "live",
      "destination_type": "bank_account",
      "currency": "NGN",
      "label": "Emeka Okafor",
      "account_number": "0123456789",
      "account_name": "Emeka Okafor",
      "bank_code": "033",
      "bank_name": "United Bank for Africa",
      "phone_number": null,
      "mobile_provider": null,
      "wallet_address": null,
      "network": null,
      "is_active": true,
      "metadata": null,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 1
}

​
Example

curl https://api.syncgrampay.com/api/v1/payouts/destinations \
  -H "Authorization: Bearer sk_live_01j..."

​
Create a destination

POST /api/v1/payouts/destinations
Authentication: API key or JWT

​
Request

​
destination_type
string
required
Type of destination. One of: bank_account, mobile_money, crypto_wallet.
​
currency
string
required
Currency code for this destination. Examples: NGN, GHS, USDT_TRC20.
​
label
string
A friendly name for this destination. Auto-generated from account details if omitted.
​
account_number
string
Bank account number. Required for bank_account.
​
account_name
string
Account holder name. Required for bank_account.
​
bank_code
string
Bank code. Required for bank_account.
​
bank_name
string
Bank name. Optional for bank_account.
​
phone_number
string
Phone number in international format. Required for mobile_money.
​
mobile_provider
string
Mobile money provider. Required for mobile_money. Examples: MTN, Vodafone, Airtel.
​
wallet_address
string
Crypto wallet address. Required for crypto_wallet.
​
network
string
Blockchain network. Required for crypto_wallet when not implied by the currency code (e.g., TRC20 for plain USDT).
​
metadata
object
Arbitrary key-value pairs to attach to the destination.

​
Example — bank account

curl -X POST https://api.syncgrampay.com/api/v1/payouts/destinations \
  -H "Authorization: Bearer sk_live_01j..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination_type": "bank_account",
    "currency": "NGN",
    "label": "Emeka Okafor",
    "account_number": "0123456789",
    "account_name": "Emeka Okafor",
    "bank_code": "033"
  }'

​
Example — crypto wallet

curl -X POST https://api.syncgrampay.com/api/v1/payouts/destinations \
  -H "Authorization: Bearer sk_live_01j..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination_type": "crypto_wallet",
    "currency": "USDT_TRC20",
    "wallet_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

​
Update a destination

PUT /api/v1/payouts/destinations/{destination_id}
Authentication: API key or JWT Replaces all fields on the destination with the values you provide. The request body accepts the same fields as POST /api/v1/payouts/destinations.

​
Example

curl -X PUT https://api.syncgrampay.com/api/v1/payouts/destinations/dst_01j9kxp4q8m2r3t5v6w7y8z9 \
  -H "Authorization: Bearer sk_live_01j..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination_type": "bank_account",
    "currency": "NGN",
    "label": "Emeka Okafor (Updated)",
    "account_number": "0123456789",
    "account_name": "Emeka Okafor",
    "bank_code": "033"
  }'

​
Delete a destination

DELETE /api/v1/payouts/destinations/{destination_id}
Authentication: API key or JWT Soft-deletes the destination by setting is_active to false. Deleted destinations are not returned by the list endpoint and cannot be used in new withdrawals.

​
Response

{
  "success": true,
  "message": "Payout destination deleted"
}

​
Example

curl -X DELETE https://api.syncgrampay.com/api/v1/payouts/destinations/dst_01j9kxp4q8m2r3t5v6w7y8z9 \
  -H "Authorization: Bearer sk_live_01j..."

​
Resolve a bank account

POST /api/v1/payouts/resolve-account
Authentication: API key or JWT Validates a bank account number and returns the registered account holder name before you create a destination or initiate a withdrawal. Use this to confirm you have the right account details.

​
Request

​
bank_code
string
required
The bank code, e.g., 033 for UBA Nigeria.
​
account_number
string
required
The account number to resolve.

​
Response

​
status
boolean
true if the account was resolved successfully.
​
message
string
Human-readable status message.
​
data
object
Account details returned by the bank. Typically includes account_name and account_number.
{
  "status": true,
  "message": "Account resolved successfully",
  "data": {
    "account_name": "EMEKA OKAFOR",
    "account_number": "0123456789"
  }
}

​
Example

curl -X POST https://api.syncgrampay.com/api/v1/payouts/resolve-account \
  -H "Authorization: Bearer sk_live_01j..." \
  -H "Content-Type: application/json" \
  -d '{
    "bank_code": "033",
    "account_number": "0123456789"
  }'

​
List banks

GET /api/v1/payouts/banks?country_code=NG
Authentication: Optional Returns a list of supported banks for a given country. Use the code field as bank_code in destination and withdrawal requests.

​
Query parameters

​
country_code
string
ISO 3166-1 alpha-2 country code. Defaults to NG (Nigeria).

​
Response

​
status
boolean
true if the request succeeded.
​
data
array
Array of bank objects, each containing name, slug, code, nibss_bank_code, and country.
{
  "status": true,
  "message": "Banks retrieved successfully",
  "data": [
    {
      "name": "United Bank for Africa",
      "slug": "united-bank-for-africa",
      "code": "033",
      "nibss_bank_code": "000004",
      "country": "NG"
    },
    {
      "name": "Guaranty Trust Bank",
      "slug": "guaranty-trust-bank",
      "code": "058",
      "nibss_bank_code": "000013",
      "country": "NG"
    }
  ]
}

​
Example

curl "https://api.syncgrampay.com/api/v1/payouts/banks?country_code=NG" \
  -H "Authorization: Bearer sk_live_01j..."