Api Reference

Invoices

Endpoints to create and manage payment invoices

List Invoices

Retrieves a paginated list of all your invoices.

Endpoint

GET /api/invoices

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/invoices?page=1&perPage=20" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Accept: application/json"

Successful Response

Code: 200 OK

{
  "data": [
    {
        "id": "01kbn701vx6ha6402995kc9a0x",
        "external_id": null,
        "amount_fiat": "5.00",
        "usd_rate": "3125.16675365",
        "status": "pending",
        "expires_at": null,
        "paid_at": null,
        "created_at": "2025-12-04T17:36:41.000000Z",
        "amount": "0.001599914626686819",
        "asset": {
            "id": 2,
            "name": "Ethereum",
            "symbol": "ETH",
            "chain": "ethereum",
            "type": "native",
            "decimals": 18,
            "usd_rate": "3125.16675365",
            "network_fee": "0.000000042162288",
            "min_confirmations": 5
        }
    }
  ]
}

Create Invoice

Creates a new payment invoice for a customer to pay.

Endpoint

POST /api/invoices

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`, `SOL`, `USDC_ERC20`)
`amount`	number	Yes	Amount in USD (minimum: 5)
`expires_in`	integer	No	Expiration time in minutes (1-120)
`external_id`	string	No	Your internal order/reference ID (max 255 chars)
`succeed_url`	string	No	URL to redirect after successful payment
`timeout_url`	string	No	URL to redirect if invoice expires

Example Request

curl -X POST https://api.flow-payments.com/api/invoices \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "BTC",
    "amount": 100,
    "expires_in": 120,
    "external_id": "order_456",
    "succeed_url": "https://example.com/success",
    "timeout_url": "https://example.com/timeout"
  }'

Successful Response

Code: 201 Created

{
  "message": "Invoice created successfully",
  "data": {
        "id": "01kbn76s9a9jmxpqpdqfc517qp",
        "external_id": null,
        "amount_fiat": "10.00",
        "usd_rate": "3125.16675365",
        "status": "pending",
        "expires_at": null,
        "paid_at": null,
        "created_at": "2025-12-04T17:40:22.000000Z",
        "amount": "0.003199829253373639",
        "pending_amount": "0",
        "paid_amount": "0",
        "url": "https://flow-payments.io/i/01kbn76s9a9jmxpqpdqfc517qp",
        "asset": {
            "id": 2,
            "name": "Ethereum",
            "symbol": "ETH",
            "chain": "ethereum",
            "type": "native",
            "decimals": 18,
            "usd_rate": "3125.16675365",
            "network_fee": "0.000000042162288",
            "min_confirmations": 5
        },
        "address": {
            "address": "0xb76d1da2029f868ba5edf4838ce6fd776f5e90c3"
        },
        "payments": []
  }
}

Validation Errors

Code: 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "asset": ["The selected asset is invalid."],
    "amount": ["The amount must be at least 5."]
  }
}

Get Invoice

Retrieves details of a specific invoice.

Endpoint

GET /api/invoices/{id}

Headers

Authorization: Bearer {token}
Accept: application/json

Path Parameters

Parameter	Type	Description
`id`	integer	Invoice ID

Example Request

curl -X GET https://api.flow-payments.com/api/invoices/123 \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Accept: application/json"

Successful Response

Code: 200 OK

{
    "id": "01kbn7d5wmqswkavsetmg347a9",
    "external_id": null,
    "amount_fiat": "10.00",
    "usd_rate": "3125.16675365",
    "status": "pending",
    "expires_at": null,
    "paid_at": null,
    "created_at": "2025-12-04T17:43:51.000000Z",
    "amount": "0.003199829253373639",
    "pending_amount": "0",
    "paid_amount": "0",
    "url": "http://127.0.0.1:3000/i/01kbn7d5wmqswkavsetmg347a9",
    "asset": {
        "id": 2,
        "name": "Ethereum",
        "symbol": "ETH",
        "chain": "ethereum",
        "type": "native",
        "decimals": 18,
        "usd_rate": "3125.16675365",
        "network_fee": "0.000000042162288",
        "min_confirmations": 5
    },
    "address": {
        "address": "0x0a7bbad178930971ec580a4d7ef8b2244dad66d5"
    },
    "payments": []
}

Error Responses

Code: 403 Forbidden - Invoice does not belong to you

{
  "message": "This action is unauthorized."
}

Code: 404 Not Found - Invoice does not exist

{
  "message": "No query results for model [Invoice]."
}

Invoice Fields

Field	Type	Description
`id`	string	Unique invoice identifier
`external_id`	string\|null	Your internal reference ID
`usd_rate`	string	Exchange rate at invoice creation
`status`	string	Invoice status (see below)
`expires_at`	string\|null	Expiration timestamp
`paid_at`	string\|null	Payment timestamp
`created_at`	string	Creation timestamp (ISO 8601)
`amount_fiat`	string	Amount in fiat currency (USD)
`amount`	string	Amount in cryptocurrency units
`pending_amount`	string	Pending amount in cryptocurrency units
`paid_amount`	string	Paid amount in cryptocurrency units
`url`	string	Invoice URL
`asset`	object	Cryptocurrency information
`address`	object	Payment address information
`payments`	array	Payment information

Invoice Statuses

Status	Description
`pending`	Waiting for payment
`confirmed`	Payment detected, awaiting confirmations
`partially_paid`	Partial payment received
`paid`	Payment confirmed and completed
`expired`	Invoice expired without payment

Use Cases

1. Create a Payment Page

async function createInvoice(orderId, amount) {
  const response = await fetch('https://api.flow-payments.com/api/invoices', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_abc123...',
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      asset: 'BTC',
      amount: amount,
      external_id: orderId,
      expires_in: 30,
      succeed_url: `https://mysite.com/order/${orderId}/success`,
      timeout_url: `https://mysite.com/order/${orderId}/timeout`
    })
  });

  const data = await response.json();
  
  // Display payment address to customer
  console.log(`Go to ${data.url}`);
  
  return data;
}

2. Check Invoice Status

<?php

function getInvoiceStatus($invoiceId) {
    $ch = curl_init("https://api.flow-payments.com/api/invoices/{$invoiceId}");
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer sk_live_abc123...',
        'Accept: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $data = json_decode($response, true);
    curl_close($ch);
    
    return $data['status'];
}

// Check if paid
if (getInvoiceStatus(123) === 'paid') {
    fulfillOrder('order_456');
}

Webhooks

Invoices trigger the following webhook events:

invoice.created - Invoice created
invoice.confirmed - First blockchain confirmation received
invoice.paid - Payment completed
invoice.expired - Invoice expired

See the webhooks documentation for implementation details.

Important Notes

!IMPORTANT
Invoices are automatically assigned a unique payment address
The exchange rate is locked at invoice creation
Expired invoices cannot be paid

!TIP Use external_id to link invoices to your internal order system for easy reconciliation.

Balances

Endpoint to check your cryptocurrency balances

Payouts

Endpoints to create and manage cryptocurrency payouts