Crypto Payout

The Crypto Payout flow allows you to send USDC or USDT from your wallet to an external crypto wallet address. No external beneficiary creation is needed — a self-beneficiary is automatically created for crypto withdrawals.

Overview

1. Create a WITHDRAWAL Quote — Use stablecoin currencies and provide the destination network and wallet address
2. Accept the Quote — Execute the payout
3. Webhook Notification — Receive confirmation when the on-chain transfer completes

Step 1: Create a WITHDRAWAL Quote

Create a crypto withdrawal quote specifying the destination network and wallet address.

Endpoint

POST /api/v1/client/quotes

Authentication

x-api-key: <your-api-key>x-timestamp: <rfc3339-timestamp>x-signature: <hmac-sha256-signature>

Request Body

{  "source_currency": "USDC",  "target_currency": "USDC",  "source_amount": "500.00",  "quote_type": "WITHDRAWAL",  "payment_network": "ETH",  "payment_address": "0x1234abcd5678ef901234abcd5678ef90abcd1234",  "tz": "UTC",  "narration": "USDC withdrawal to external wallet",  "origin_reference": "CRYPTO-PAYOUT-2026-001",  "on_behalf_of": "660e8400-e29b-41d4-a716-446655440001"}

Required Parameters

Optional Parameters

Success Response (201 Created)

{  "quote_id": "abc12345-e89b-12d3-a456-426614174000",  "source": {    "currency": "USDC",    "amount": "500.00"  },  "target": {    "currency": "USDC",    "amount": "500.00"  },  "exchange_rate": "1.00",  "fees": {    "processing_fee": "2.00",    "deposit_fee": "0.00",    "payout_fee": "1.00",    "total_fees": "3.00",    "fee_currency": "USDC"  },  "total_payable": "503.00",  "valid_until": "2026-03-16T15:40:53Z",  "quote_status": "CREATED",  "type": "WITHDRAWAL"}

No beneficiary_id is required. The system automatically creates a self-beneficiary for crypto withdrawals.

Step 2: Accept the Quote

Accept the quote to initiate the on-chain transfer.

Endpoint

POST /api/v1/client/quotes/{id}/accept

Authentication

x-api-key: <your-api-key>x-timestamp: <rfc3339-timestamp>x-signature: <hmac-sha256-signature>

Success Response (200 OK)

{  "quote_id": "abc12345-e89b-12d3-a456-426614174000",  "transaction_id": "def67890-e21b-43d2-b456-426614174111",  "transaction_reference": "TXN-CRYPTO-78901",  "total_payable": "503.00",  "timeline": {    "created_at": "2026-03-16T15:10:53Z",    "accepted_at": "2026-03-16T15:12:30Z"  },  "status": "PROCESSING"}

Step 3: Webhook Notification

Once the on-chain transfer is confirmed, you'll receive a transaction webhook:

{  "event_type": "transaction",  "transaction_id": "def67890-e21b-43d2-b456-426614174111",  "transaction_type": "WITHDRAWAL",  "status": "COMPLETED",  "reference": "TXN-CRYPTO-78901",  "user_id": "660e8400-e29b-41d4-a716-446655440001",  "created_at": "2026-03-16T15:10:53Z",  "timestamp": "2026-03-16T15:20:00Z",  "source_currency": "USDC",  "source_amount": "500.00",  "target_currency": "USDC",  "target_amount": "500.00",  "amount_with_fees": "503.00",  "fee": "3.00",  "fee_currency": "USDC"}

Supported Networks and Tokens

Network availability may vary. Use the network identifier in the payment_network field (e.g., "ETH", "POLYGON", "SOLANA").

Example: Complete Crypto Payout Flow

cURL

Step 1: Create withdrawal quote

curl -X POST https://api.transfaar.com/api/v1/client/quotes \  -H "Content-Type: application/json" \  -H "x-api-key: your-api-key" \  -H "x-timestamp: 2026-03-16T10:30:00Z" \  -H "x-signature: your-hmac-signature" \  -d '{    "source_currency": "USDC",    "target_currency": "USDC",    "source_amount": "500.00",    "quote_type": "WITHDRAWAL",    "payment_network": "ETH",    "payment_address": "0x1234abcd5678ef901234abcd5678ef90abcd1234",    "tz": "UTC",    "origin_reference": "CRYPTO-PAYOUT-2026-001",    "on_behalf_of": "660e8400-e29b-41d4-a716-446655440001"  }'

Step 2: Accept the quote

curl -X POST https://api.transfaar.com/api/v1/client/quotes/abc12345-e89b-12d3-a456-426614174000/accept \  -H "Content-Type: application/json" \  -H "x-api-key: your-api-key" \  -H "x-timestamp: 2026-03-16T10:31:00Z" \  -H "x-signature: your-hmac-signature"

JavaScript

async function processCryptoPayout(apiKey, secretKey, payoutData) {  // Step 1: Create crypto withdrawal quote  const quote = await apiCall('POST', '/api/v1/client/quotes', apiKey, secretKey, {    source_currency: payoutData.token,    target_currency: payoutData.token,    source_amount: payoutData.amount,    quote_type: 'WITHDRAWAL',    payment_network: payoutData.network,    payment_address: payoutData.walletAddress,    tz: 'UTC',    narration: payoutData.narration,    origin_reference: payoutData.reference,    on_behalf_of: payoutData.customerId  });
  // Step 2: Accept the quote  const result = await apiCall('POST', `/api/v1/client/quotes/${quote.quote_id}/accept`, apiKey, secretKey);
  return {    transactionId: result.transaction_id,    transactionReference: result.transaction_reference,    status: result.status  };}

Best Practices

1. Verify Wallet Addresses — Double-check the destination wallet address before creating the quote. On-chain transactions are irreversible.
2. Choose the Right Network — Ensure the recipient can receive on the selected network. Sending USDC on Ethereum vs Polygon results in different destination addresses for some wallets.
3. Account for Gas Fees — Network fees are included in the quote's fee breakdown. The total_payable reflects the total cost.
4. Handle Confirmation Times — On-chain confirmations vary by network. Ethereum may take a few minutes; Polygon and Solana are typically faster.
5. Use Unique References — Each origin_reference must be unique to prevent duplicate payouts.