Api Reference

Payouts

Endpoints to create and manage cryptocurrency payouts

List Payouts

Retrieves a paginated list of all your payouts (transactions).

Endpoint

GET /api/payouts

Headers

Authorization: Bearer {token}
Accept: application/json

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`perPage`	integer	10	Number of items per page (max: 100)

Example Request

curl -X GET "https://api.flow-payments.com/api/payouts?page=1&perPage=20" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Accept: application/json"

Successful Response

Code: 200 OK

{
  "data": [
    {
      "id": 789,
      "type": "payout",
      "amount": "100",
      "tx_hash": "0xabc123def456...",
      "to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "status": "mined",
      "failed_reason": "",
      "created_at": "2024-12-04T17:00:00.000000Z",
      "completed_at": "2024-12-04T17:05:00.000000Z",
      "asset": {
        "id": 2,
        "symbol": "ETH",
        "name": "Ethereum",
        "decimals": 18
      },
    }
  ]
}

Create Payout

Creates a new payout to send cryptocurrency to an external address.

Endpoint

POST /api/payouts

Headers

Authorization: Bearer {token}
Accept: application/json
Content-Type: application/json

Request Body

Field	Type	Required	Description
`asset`	string	Yes	Cryptocurrency symbol (e.g., `BTC`, `ETH`, `USDC_ERC20`)
`amount`	number	Yes	Amount to send in standard units (minimum: 0)
`address`	string	Yes	Recipient cryptocurrency address

Example Request

curl -X POST https://api.flow-payments.com/api/payouts \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "ETH",
    "amount": 0.5,
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  }'

Successful Response

Code: 201 Created

{
  "message": "Payout created successfully"
}

!NOTE The payout is created and queued for processing. You will receive a payout.completed webhook when the transaction is confirmed on the blockchain.

Validation Errors

Code: 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "asset": ["The selected asset is invalid."],
    "amount": ["The amount field is required."],
    "address": ["The address field is required."]
  }
}

Insufficient Balance Error

Code: 400 Bad Request

{
  "message": "Insufficient balance"
}

This error occurs when:

Your balance is less than the requested amount
Your balance is less than the amount + network fees

Payout Fields

Field	Type	Description
`id`	integer	Unique payout identifier
`type`	string	Transaction type (always `payout`)
`amount`	string	Amount in standard units (e.g., `0.5`)
`tx_hash`	string\|null	Blockchain transaction hash
`to_address`	string	Recipient cryptocurrency address
`status`	string	Payout status (see below)
`failed_reason`	string	Payout failure reason (if any)
`asset`	object	Cryptocurrency information
`created_at`	string	Creation timestamp (ISO 8601)

Payout Statuses

Status	Description
`pending`	Payout created, awaiting blockchain submission
`mined`	Payout confirmed on the blockchain
`failed`	Payout failed

Network Fees

Network fees are automatically deducted from your balance when creating a payout.

Total deduction:

total_deducted = amount + network_fee

Example:

Payout amount: 0.5 ETH
Network fee: 0.001 ETH
Total deducted from balance: 0.501 ETH

!IMPORTANT Make sure you have enough balance to cover both the payout amount AND the network fees.

Use Cases

1. Withdraw Funds

async function withdrawFunds(asset, amount, address) {
  const response = await fetch('https://api.flow-payments.com/api/payouts', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_abc123...',
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      asset: asset,
      amount: amount,
      address: address
    })
  });

  if (response.ok) {
    console.log('Payout created successfully');
  } else {
    const error = await response.json();
    console.error('Error:', error.message);
  }
}

// Withdraw 1 BTC
withdrawFunds('BTC', 1.0, 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh');

2. Check Balance Before Payout

<?php

function createPayoutWithCheck($asset, $amount, $address) {
    // Get balances
    $balances = getBalances();
    
    // Find asset balance
    $assetBalance = null;
    foreach ($balances['data'] as $item) {
        if ($item['asset']['symbol'] === $asset) {
            $assetBalance = floatval($item['balance']);
            $networkFee = floatval($item['asset']['network_fee']);
            break;
        }
    }
    
    // Check sufficient balance
    $totalNeeded = $amount + $networkFee;
    if ($assetBalance < $totalNeeded) {
        throw new Exception("Insufficient balance. Need {$totalNeeded} {$asset}, have {$assetBalance}");
    }
    
    // Create payout
    return createPayout($asset, $amount, $address);
}

3. Monitor Payout Completion

Use webhooks to monitor payout completion:

<?php

// webhook-handler.php

if ($event['event'] === 'payout.completed') {
    $payout = $event['data'];
    
    // Log completion
    logPayoutCompleted($payout['id'], $payout['tx_hash']);
    
    // Notify user
    sendEmail($userEmail, "Your withdrawal of {$payout['amount']} {$payout['asset']['symbol']} has been completed");
}

Address Validation

!CAUTION Always validate cryptocurrency addresses before creating a payout. Sending to an invalid address will result in permanent loss of funds.

Validation tips:

Verify the address format matches the cryptocurrency
Double-check the address with the recipient
Consider sending a small test amount first
Use address validation libraries in your application

Webhooks

Payouts trigger the following webhook event:

payout.completed - Payout confirmed on the blockchain

See the webhooks documentation for implementation details.

Important Notes

!IMPORTANT
Payouts are irreversible once submitted to the blockchain
Network fees are automatically deducted from your balance
You must have sufficient balance for amount + fees
Invalid addresses will result in permanent loss of funds

!TIP Monitor your payouts via webhooks rather than polling the API for status updates.

Error Handling

Common errors when creating payouts:

Error	Cause	Solution
`Insufficient balance`	Not enough funds	Check balance and ensure you have enough for amount + fees
`The selected asset is invalid`	Asset doesn't exist or is inactive	Use a valid asset symbol from the `/api/assets` endpoint
`The address field is required`	Missing recipient address	Provide a valid cryptocurrency address

Invoices

Endpoints to create and manage payment invoices