Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.iterapay.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

After a customer pays an invoice, the funds do not automatically move into your merchant balance — you need to collect them. Collection is the process of sweeping paid invoice funds from their on-chain addresses into your IteraPay balance. This guide walks you through each step of the collection flow, including how to preview fees before committing.
Always check fees with the /collect/info endpoint before initializing collection. Collection fees are deducted from the gross amount, and you cannot cancel a collection once it is initialized.

​
Prerequisites

  • At least one invoice with a paid status
  • Your merchantID
  • A valid API key or JWT bearer token

​
Collection flow

1

List invoices eligible for collection

Fetch the invoices that are ready to be collected. You can filter this list to narrow down which invoices you want to collect.
curl --request GET \
  --url 'https://api.iterapay.com/merchants/{merchantID}/collect/invoices' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'
Expected response:
{
  "invoices": [
    {
      "id": "inv_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": 100,
      "status": "paid",
      "paidAt": "2024-01-01T11:30:00Z"
    },
    {
      "id": "inv_b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "amount": 250,
      "status": "paid",
      "paidAt": "2024-01-01T14:15:00Z"
    }
  ]
}
Note the invoice IDs you want to collect. You’ll pass them as query parameters in the next steps.
2

Preview fees before collecting

Before initializing collection, check the gross amount, net amount, and applicable fees. Pass one or more invoice IDs as a comma-separated list.
curl --request GET \
  --url 'https://api.iterapay.com/merchants/{merchantID}/collect/info?invoiceIDs=inv_a1b2c3d4-e5f6-7890-abcd-ef1234567890,inv_b2c3d4e5-f6a7-8901-bcde-f12345678901' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'
Expected response:
{
  "gross": "350.000000",
  "fee": "3.500000",
  "net": "346.500000",
  "currency": "USD",
  "invoices": [
    {
      "id": "inv_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "gross": "100.000000",
      "fee": "1.000000",
      "net": "99.000000"
    },
    {
      "id": "inv_b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "gross": "250.000000",
      "fee": "2.500000",
      "net": "247.500000"
    }
  ]
}
The net amount is what will be credited to your merchant balance after fees are deducted. Review this carefully before proceeding.
3

Initialize collection

Once you’re satisfied with the fee preview, initialize the collection. Use the same invoiceIDs query parameter.
curl --request POST \
  --url 'https://api.iterapay.com/merchants/{merchantID}/collect/init?invoiceIDs=inv_a1b2c3d4-e5f6-7890-abcd-ef1234567890,inv_b2c3d4e5-f6a7-8901-bcde-f12345678901' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'
Expected response:
{
  "id": "col_c3d4e5f6-a7b8-9012-cdef-123456789012",
  "transactionIDs": [1001, 1002, 1003]
}
Save the collection id and transactionIDs. You’ll use them to monitor progress.
4

Monitor collection status

Poll the collection state endpoint to track the progress of your collection. This is especially important for large collections that may involve multiple on-chain transactions.
curl --request GET \
  --url 'https://api.iterapay.com/merchants/{merchantID}/collect/state' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'
Expected response:
{
  "status": "processing",
  "completedTransactions": 2,
  "totalTransactions": 3,
  "creditedAmount": "246.500000",
  "pendingAmount": "99.000000"
}
Continue polling until status returns completed. Once complete, the net amount will be available in your merchant balance.

​
Understanding collection fees

Fees are calculated as a percentage of the gross amount collected. The exact rate depends on your account plan and the payment methods involved.
FieldDescription
grossTotal amount paid across all selected invoices
feeIteraPay collection fee deducted from the gross
netAmount credited to your balance after fees
Use the /collect/info endpoint as often as you need — it’s a read-only preview that doesn’t trigger any transactions.

​
Next steps

Once your balance is funded, you can move funds to an external wallet. See Withdrawals to learn how to withdraw your balance.