Withdrawals

Paid invoices are withdrawn to your payout address automatically. These endpoints let you see what is waiting, trigger a withdrawal immediately and track withdrawal transactions.

Auth: API key or request signature.

Prepare a withdrawal

GET /integration/invoices/withdraw/prepare?ownerAddress=0x…

Returns every invoice that can be withdrawn, across all chains: paid, not cancelled, not yet withdrawn. Balances come from the last on-chain check.

Signed payload: {}.

Response

{
  "chainsCount": 1,
  "totalInvoices": 2,
  "byChain": {
    "8453": [
      {
        "invoiceId": "1000456",
        "paymentAddress": "0x6c76fD5f0b5F7924A0b6b23223A8D2398fB00E72",
        "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "balance": 12.5,
        "balanceRaw": "12500000",
        "factoryVersion": 2,
        "factoryAddress": "0x8dAE900Fb6A1179A69b1E70A49b8399c6b9e4B19"
      }
    ]
  },
  "tokenTotalsUsd": [
    {
      "chainId": 8453,
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "invoiceCount": 2,
      "totalBalance": 25,
      "usdEquivalent": 24.99
    }
  ]
}

• tokenAddress is absent for the native token; usdEquivalent is absent when no price is available.
• factoryAddress is the PaymentFactory to call if you withdraw an invoice yourself with withdrawToken / withdrawEth (see Smart contracts).

Withdraw now

POST /integration/invoices/withdraw?ownerAddress=0x…

ownerAddress goes in the query string; the body holds only the chain.

Request body (also the signed payload)

{ "chainId": 8453 }

Every withdrawable invoice on that chain is withdrawn in batch transactions, grouped by token.

Response

{
  "chainId": 8453,
  "totalInvoices": 2,
  "totalTransactions": 1,
  "byToken": [
    {
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "invoiceCount": 2,
      "transactionCount": 1,
      "txHashes": ["0x9f…"]
    }
  ]
}

The response means the transactions were sent, not confirmed. Track them with withdrawal transactions. With nothing to withdraw you get totalInvoices: 0 and an empty byToken, not an error.

If you enabled owner-only withdrawals, the call returns 400 OWNER_ONLY_WITHDRAW: withdraw from your own contract instead.

curl -X POST "$BASE_URL/integration/invoices/withdraw?ownerAddress=$OWNER_ADDRESS" \
  -H 'Content-Type: application/json' \
  -H "x-depay-api-key: $SODAPOP_API_KEY" \
  -d '{ "chainId": 8453 }'

Withdrawal transactions

GET /integration/invoices/withdraw/transactions

Query param	Description
ownerAddress	Required.
page, limit	Default 1 and 20, max 100. Include them in the signed payload.
chainId	Filter by chain.
status	submitted, confirmed, failed or unknown.

Newest first. Returns { items, total, page, limit }:

Field	Description
txHash	Transaction hash.
status	submitted, confirmed, failed or unknown.
source	auto (automatic withdrawal) or manual (POST /withdraw).
chainId	Chain of the transaction.
tokenAddress	Absent for the native token.
invoiceIds	Invoices included in the batch.
createdAt, confirmedAt, failedAt	Unix ms.
errorMessage	Reason for failed.

unknown means the transaction was sent but its result is not known yet. It moves to confirmed or failed automatically; check again later.