API Reference

Payouts

Automatic fund distribution after invoice confirmation. Configure payout destinations and manage withdrawals.

How Payouts Work

Invoice Confirmed

After 5 blockchain confirmations, the invoice status changes to CONFIRMED

Processing Payout

System calculates amounts: total received minus gateway fee (configurable percentage)

Funds Transferred

USDT automatically sent from custody wallet to your configured destination address

Paid Out

Invoice status updated to PAID_OUT, webhook notification sent

Payout Calculation

FromChain automatically deducts a gateway fee from each successful payment. The fee percentage is defined in your contract.

payout-example.js

// Example: Customer pays 100 USDT
const customerPayment = 100.00;
const gatewayFeePercent = 1.5;  // Your contracted fee rate

// Calculation
const gatewayFee = customerPayment * (gatewayFeePercent / 100);
const merchantPayout = customerPayment - gatewayFee;

console.log({
  received: "100.00 USDT",
  gatewayFee: "1.50 USDT",     // 1.5% deducted
  merchantPayout: "98.50 USDT"  // Amount sent to your wallet
});

// The invoice response includes these values:
// {
//   "amountReceived": "100.00",
//   "gatewayFee": "1.50",
//   "payoutAmount": "98.50"
// }

📋 Fee Rate: Your gateway fee percentage is defined in your service contract and set by FromChain during account setup. Contact support if you need information about your current rate.

Configure Payout Destination

Set the wallet address where you want to receive funds from confirmed payments.

PUT/v1/tenants/payout-address

Update your tenant's payout destination address

update-payout-address.js

const response = await fetch('https://api.fromchain.io/v1/tenants/payout-address', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer gw_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payoutAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
  })
});

const tenant = await response.json();
// {
//   "id": "tenant_abc123",
//   "name": "My Company",
//   "payoutAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
//   "updatedAt": "2025-12-18T10:00:00Z"
// }

Security Warning: Ensure this address is correct. Funds sent to incorrect addresses cannot be recovered. Only use BSC (BEP-20) compatible wallet addresses.

View Payout History

Track all payouts associated with your invoices.

GET/v1/payouts

Retrieve paginated list of all payouts

list-payouts.js

const response = await fetch('https://api.fromchain.io/v1/payouts?page=1&pageSize=20', {
  headers: {
    'Authorization': 'Bearer gw_live_...'
  }
});

const data = await response.json();
// {
//   "data": [
//     {
//       "id": "payout_xyz789",
//       "invoiceId": "inv_abc123",
//       "amount": "98.50",
//       "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
//       "txHash": "0x9876543210...",
//       "status": "COMPLETED",
//       "createdAt": "2025-12-18T10:15:00Z",
//       "completedAt": "2025-12-18T10:16:30Z"
//     }
//   ],
//   "pagination": {
//     "page": 1,
//     "pageSize": 20,
//     "total": 45,
//     "totalPages": 3
//   }
// }

Get Payout Details

GET/v1/payouts/:id

Retrieve detailed information about a specific payout

get-payout.js

const response = await fetch('https://api.fromchain.io/v1/payouts/payout_xyz789', {
  headers: {
    'Authorization': 'Bearer gw_live_...'
  }
});

const payout = await response.json();
// {
//   "id": "payout_xyz789",
//   "invoiceId": "inv_abc123",
//   "amount": "98.50",
//   "gatewayFee": "1.50",
//   "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
//   "txHash": "0x9876543210abcdef...",
//   "blockNumber": 12345678,
//   "status": "COMPLETED",
//   "invoice": {
//     "id": "inv_abc123",
//     "externalId": "order_12345",
//     "amountExpected": "100.00",
//     "amountReceived": "100.00"
//   },
//   "createdAt": "2025-12-18T10:15:00Z",
//   "completedAt": "2025-12-18T10:16:30Z"
// }

Payout Status

PENDING

Payout transaction submitted to blockchain, waiting for confirmation

COMPLETED

Funds successfully transferred and confirmed on blockchain

FAILED

Transaction failed (insufficient gas, invalid address, etc.)

PROCESSING

Payout is being prepared and will be sent shortly

Handling Failed Payouts

If a payout fails, you'll receive a webhook notification and can retry manually.

Common Failure Reasons:

Insufficient Gas: Custody wallet doesn't have enough BNB to pay gas fees
Invalid Address: Payout address is not a valid BSC address
Network Congestion: BSC network is overloaded (will auto-retry)

💡 Tip: When a payout fails, the funds remain in the custody wallet. Contact support to manually trigger a retry or update your payout address.

Best Practices

Verify Payout Address

Always double-check your payout address before updating. Send a small test transaction first.

Monitor Webhooks

Listen to invoice.paid_out and invoice.failed webhooks for real-time updates.

Track Transaction Hashes

Store payout txHash values to verify transactions on BSCScan.

Use Hot & Cold Wallets

Consider receiving payouts to a hot wallet and periodically transferring to cold storage for security.