Create Payout Destination

Overview

Add a withdrawal destination where you can receive payouts. Before withdrawing funds, you must first create at least one payout destination.

Destination types supported:

• Bank accounts (for fiat currencies)
• Mobile money wallets (for African regions)
• Cryptocurrency wallets (for USDT, BTC, ETH)

Once created, you can use the destination ID to initiate withdrawals.

Authentication

Type: API Key (required)

Required Headers

Request

Method & Path

POST /api/v1/payouts/destinations

Request Bodies by Destination Type

Bank Account

{
  "destination_type": "bank_account",
  "currency": "NGN",
  "label": "My GT Bank Account",
  "account_number": "0123456789",
  "account_name": "John Doe",
  "bank_code": "058",
  "bank_name": "Guaranty Trust Bank"
}

Mobile Money

{
  "destination_type": "mobile_money",
  "currency": "GHS",
  "label": "My MTN Wallet",
  "phone_number": "+233200123456",
  "mobile_provider": "MTN"
}

Crypto Wallet

{
  "destination_type": "crypto_wallet",
  "currency": "USDT_TRC20",
  "label": "My USDT Wallet",
  "wallet_address": "TXY7GhbJ9kLmN3oPqR5sTuV8wXyZ1aB2cD",
  "network": "TRC20"
}

Request Fields

Common Fields (All Types)

Bank Account Fields

Mobile Money Fields

Crypto Wallet Fields

Dependencies & Prerequisites

Before creating payout destinations:

1. Get supported currencies: Use List Supported Currencies
2. For bank accounts: Get valid bank codes using List Banks
3. Optionally verify bank account: Use Resolve Bank Account to verify before saving

Links:

• See: List Banks
• See: Resolve Bank Account

Example Use Case

Scenario: Your business needs to set up automated payouts to your bank account. You want to configure your GTBank account as a withdrawal destination so you can regularly transfer earnings from your SyncPay balance to your business account. The system should validate the account details before saving to prevent failed withdrawals.

Implementation:

// Step 1: Verify the bank account first (optional but recommended)
const verifyResponse = await fetch('https://api.usesyncpay.com/api/v1/payouts/resolve-account', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_abc123xyz...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    bank_code: '058',
    account_number: '0123456789'
  })
});

const verification = await verifyResponse.json();
console.log('Account name:', verification.account_name); // "JOHN DOE"

// Step 2: Create payout destination
const createResponse = await fetch('https://api.usesyncpay.com/api/v1/payouts/destinations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_abc123xyz...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    destination_type: 'bank_account',
    currency: 'NGN',
    label: 'My GTBank Savings',
    account_number: '0123456789',
    account_name: verification.account_name,
    bank_code: '058',
    bank_name: 'Guaranty Trust Bank'
  })
});

const destination = await createResponse.json();
console.log('Destination ID:', destination.id);
console.log('Now you can withdraw to this destination');

Response

200 – Success

Returns the created destination details.

{
  "id": "dest_1a2b3c4d5e6f",
  "organization_id": "org_abc123",
  "env": "live",
  "destination_type": "bank_account",
  "currency": "NGN",
  "label": "My GTBank Savings",
  "account_number": "0123456789",
  "account_name": "JOHN DOE",
  "bank_code": "058",
  "bank_name": "Guaranty Trust Bank",
  "phone_number": null,
  "mobile_provider": null,
  "wallet_address": null,
  "network": null,
  "is_active": true,
  "metadata": null,
  "created_at": "2026-01-24T14:30:00.000Z",
  "updated_at": "2026-01-24T14:30:00.000Z"
}

400 – Bad Request

Validation errors.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Bank account requires account_number, account_name, and bank_code",
    "details": {
      "account_name": "This field is required"
    }
  }
}

Common causes:

• Missing required fields for destination type
• Invalid currency code
• Invalid bank code
• Invalid wallet address format
• Network mismatch for crypto currency

401 – Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Important Notes

Auto-Generated Labels

If you don't provide a label, one is generated automatically:

• Bank account: "Bank Account" or account name if available
• Mobile money: Provider name + last 4 digits
• Crypto wallet: "USDT (TRC20)" or similar

Recommendation: Always provide descriptive labels to help identify destinations later.

Crypto Currency Networks

For crypto currencies:

• If currency includes network (USDT_TRC20), network is auto-detected
• You can still explicitly provide network field
• If network mismatch, you'll get 400 error

One Destination Per Currency

You can have multiple destinations, even for the same currency:

// Allowed: Multiple NGN bank accounts
await createDestination({ currency: 'NGN', account_number: '1111111111', ... });
await createDestination({ currency: 'NGN', account_number: '2222222222', ... });

Related Endpoints

• List Payout Destinations - View all your destinations
• Update Payout Destination - Modify existing destination
• Delete Payout Destination - Remove destination
• List Banks - Get valid bank codes
• Resolve Bank Account - Verify bank details

Next Steps

After creating a destination:

1. Save the destination ID for use in withdrawals
2. Create withdrawals using Create Withdrawal
3. Manage destinations as needed