Customers & static addresses
Give each of your customers permanent receive addresses and see every payment attributed to them.
A customer is one of your own users, saved under an id you choose. Give a customer a permanent
address on any supported network and they can pay into it as often as they like — every payment
is a payment to you (with your usual processing fee), credits your balance and arrives as a customer.payment.received webhook carrying the customer id,
so you know whose account to top up.
Use this for top-up wallets, exchange-style deposits or recurring payers. For a one-off amount, use a payment link or invoice; to top up your own balance, use your deposit addresses.
Before you start: writes need the customers:write scope and reads customers:read
(Authentication). Keys don't carry them unless you pick them when you create the key. Creating addresses needs a fully verified (level 2) account, because
a permanent address cannot be held to a per-payment limit.
Create a customer
The id is yours: 1-50 letters, digits, _ or - (it must not start with treasury_). Creating an id
that already exists returns the existing customer (200) instead of a duplicate, so retries are safe.
curl -X POST https://api.absolutepay.io/v1/customers \
-H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
-d '{"id":"user-1042","description":"Alice (premium)","type":"individual","email":"[email protected]"}'Optional fields: description, type (individual default, or corporate), email, and the customer's
own payout address withdrawAddress + withdrawChain (kept for paying them back). Change any of them
with PATCH /v1/customers/{id}; list with GET /v1/customers (q searches id, description and email);
delete with DELETE /v1/customers/{id} — that also deletes its addresses.
Give the customer an address
List the networks with GET /v1/customers/chains, then create an address on one:
curl -X POST https://api.absolutepay.io/v1/customers/user-1042/addresses \
-H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
-d '{"chain":"TRX"}'
# { "customerId": "user-1042", "chain": "TRX", "address": "T…", "currencies": ["USDT","TRX"], "evm": false, … }Asking again for the same network returns the same address. On memo networks the response carries a
memo the payer must include.
One address for all EVM networks
EVM networks can share one address. List the networks you want:
curl -X POST https://api.absolutepay.io/v1/customers/user-1042/addresses/evm \
-H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
-d '{"chains":["ETH","BSC","MATIC"]}'The response has one entry per network, all with the same address. A non-EVM network answers
400 not_evm_chain.
Manage addresses
GET /v1/customers/{id}/addresses— the customer's live addresses.GET /v1/customers/{id}/addresses/{chain}— one address with its live state:risk(the address was flagged; payments to it may be held) andexpired.DELETE /v1/customers/{id}/addresses/{chain}— the address stops receiving. For an EVM address this removes that one network.
Payments
A payment from a customer is a payment to you, like one through a payment link: it credits your balance
for the coin that was sent, carries the same processing fee as your checkout payments, is listed with your
payments (GET /v1/reconciliation/payments, merchantTradeNo = its paymentId) and fires:
{
"type": "customer.payment.received",
"data": {
"id": "evt_…",
"paymentId": "cp_79553757252681730",
"customerId": "user-1042",
"transactionId": "79553757252681730",
"chain": "TRX",
"address": "T…",
"amount": "25",
"currency": "USDT",
"txHash": "…",
"fromAddress": "T…"
}
}Use transactionId as your idempotency key — the same payment is never delivered as two events with
different ids. List a customer's payments with GET /v1/customers/{id}/payments (chain, from, to,
default the last 30 days; page with before).
Testing
With a test-mode key, simulate a payment on any address — it credits your test balance, shows up in the customer's payments and fires the webhook, exactly like a real one:
curl -X POST https://api.absolutepay.io/v1/customers/user-1042/addresses/TRX/simulate-payment \
-H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
-d '{"currency":"USDT","amount":"25"}'Live keys get 409 simulation_unavailable.
Gotchas
- Match coin to network. Only send coins the address lists in
currencies; a transfer on the wrong network is irrecoverable. - A deleted address stops receiving. Tell the customer before you delete it; payments that already arrived stay in your balance and history.
- Customer ids are permanent. Pick an id from your own system (user id, account number) — you can change everything else, not the id.
Next
- Webhooks — verify and process
customer.payment.received. - Receiving deposits — permanent addresses for your own balance.
- API reference — every field on the customer endpoints.