Overview

A payment address is a reusable deposit destination for a customer. Deposits automatically create invoices with source: static; they use the same invoice acceptance and webhook model as hosted payments.

Create an address# #

Send a supported crypto currency and network, an optional label, and a unique idempotency key. Save the returned address ID with your customer ID. The label is a human-readable annotation, not a unique external identifier.

Display both address and address_tag when a tag is returned. Omitting a required tag can prevent a deposit from being attributed correctly. There is no address external_id, metadata field, update endpoint, or deletion endpoint in the merchant API.

Match a deposit to a customer# #

1. Register for the relevant invoice.* events before accepting deposits.
2. Verify the signature and deduplicate the event by id.
3. Read the invoice identified by data.invoice_id or subject_id.
4. Use the invoice's static_address_id to find your customer mapping.
5. Apply your deposit policy using the current invoice and accepted amount.

The webhook payload does not currently contain the static address ID. invoice.created and invoice.detected are not a balance credit. There is no balance.credited event.

Deposit lifecycle# #

Each unique transfer creates one invoice for the actual gross amount received. Repeated observations do not create another deposit. Static deposits have no payment deadline and do not use ordinary invoice minimum/maximum amount limits or the invoice dust cutoff.

The deposit still needs a usable valuation and the required blockchain confirmations. If rates are temporarily unavailable, processing retries. Fees reduce the net credit; a small deposit can have zero net after fees. Creating an invoice alone is not proof of acceptance. Handle dropped observations and reversals, and do not count multiple invoice events as separate credits. See business processes.

Address totals and history# #

total_received is an address-level received total; invoice_count counts associated invoices. These values are not the customer's spendable balance.

The merchant API provides create, get, and list address operations. To retrieve an address's invoices, use list invoices with the exact static_address_id. There is no separate address-invoice history endpoint. Keep your local address-to-customer mapping and process invoice events for updates.