> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iterapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Collect Funds from Paid Invoices

> Learn how to sweep paid invoice funds into your merchant balance by previewing fees, initializing collection, and monitoring collection status.

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.

<Warning>
  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.
</Warning>

## Prerequisites

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

***

## Collection flow

<Steps>
  <Step title="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.

    ```bash theme={null}
    curl --request GET \
      --url 'https://api.iterapay.com/merchants/{merchantID}/collect/invoices' \
      --header 'Authorization: Bearer YOUR_JWT_TOKEN'
    ```

    **Expected response:**

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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:**

    ```json theme={null}
    {
      "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"
        }
      ]
    }
    ```

    <Note>
      The `net` amount is what will be credited to your merchant balance after fees are deducted. Review this carefully before proceeding.
    </Note>
  </Step>

  <Step title="Initialize collection">
    Once you're satisfied with the fee preview, initialize the collection. Use the same `invoiceIDs` query parameter.

    ```bash theme={null}
    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:**

    ```json theme={null}
    {
      "id": "col_c3d4e5f6-a7b8-9012-cdef-123456789012",
      "transactionIDs": [1001, 1002, 1003]
    }
    ```

    Save the collection `id` and `transactionIDs`. You'll use them to monitor progress.
  </Step>

  <Step title="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.

    ```bash theme={null}
    curl --request GET \
      --url 'https://api.iterapay.com/merchants/{merchantID}/collect/state' \
      --header 'Authorization: Bearer YOUR_JWT_TOKEN'
    ```

    **Expected response:**

    ```json theme={null}
    {
      "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.
  </Step>
</Steps>

***

## 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.

| Field   | Description                                     |
| ------- | ----------------------------------------------- |
| `gross` | Total amount paid across all selected invoices  |
| `fee`   | IteraPay collection fee deducted from the gross |
| `net`   | Amount 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](/guides/withdrawals) to learn how to withdraw your balance.