Core concepts

1. 01

   You ask for money

   Your server creates a payment, or you share a payment link.

2. 02

   The customer opens checkout

   Each attempt is a checkout. For crypto, it reserves a fresh address in your wallet and locks the rate.

3. 03

   Funds arrive

   A transfer lands on chain, or a card payment is approved. Checkout follows it until it confirms.

4. 04

   You hear about it

   The payment succeeds, an event is recorded, and your webhook endpoint gets it.

5. 05

   It lands in your wallet

   The money is a transaction in your wallet, and the payer is a customer you can look up.

A business is one merchant account, with its own wallet, keys, payments and settings, and one person can own several. A secret key belongs to one business and acts only as it. Each business has exactly one wallet, which receives every payment. IDs start with biz_.

A payment is money you're owed for one thing, at an exact amount in a currency you choose, with a status that moves from pending to succeeded and room for your own metadata. One you create through the API has a hosted checkout at its url and your own reference. One made through a link has its link_id instead, and a url of null. IDs start with pmt_.

A checkout is one attempt to pay a payment or link, in one rail, coin and network. A payment can have several, if the customer changes their mind, but only one can pay it: when the transfer lands on a quote the customer had left, the sibling they moved to closes with replaced_by naming the paid one, so open that one instead. IDs start with chk_.

When less than the amount due arrives, the payment becomes underpaid. A remainder is a checkout for exactly what's left, in the same coin and network, attached to the same payment. When the rest arrives, that payment succeeds, and no second payment is made.

A link is a reusable checkout with a fixed price. Every customer who pays it creates a new payment that carries the link's link_id. IDs start with lnk_.

A customer is a person grouped by email, with their payment count and totals. One is added as soon as checkout collects an email, so a customer can have no payments yet. You can block a customer from paying you. IDs start with cst_.

An event records something that happened, such as payment.succeeded, with a snapshot of the object as it was. Webhooks deliver events, and you can list them any time. IDs start with evt_.

Your wallet is self-custody: its recovery phrase is encrypted in your browser and never reaches 402pay. It keeps a balance per coin and network, and every payment's deposit is a wallet transaction. IDs start with wal_ and wtx_.