Glossary

The terms the API and these docs use, from actor to webhook endpoint.

The words these docs and the API use, in one place. Each one links to the page that covers it in full.

A

Actor: Who caused an event: user for a person in the dashboard, api_key, customer at checkout, or system for 402pay itself, such as a payment confirming. See event fields.
API payment: A payment your server creates with POST /payments, for an exact amount, with your reference and metadata and a hosted checkout of its own. Every checkout opened on it is one attempt at the same payment. See accept a payment.

Business: One merchant account, with its own wallet, keys, payments and settings. One person can own several, and a secret key acts as exactly one. IDs start with biz_. See core concepts.

Checkout: One attempt to pay a payment or link, in one rail, coin and network. A crypto checkout reserves a fresh address in your wallet and locks a quote. IDs start with chk_. See hosted checkout.
Checkout address: The fresh address in your wallet that one crypto checkout pays to, so every transfer matches one payment. Every EVM network shares it. See wallet and deposits.
Confirmation: A block added on top of the one holding a transfer. Each network needs a set number before a payment succeeds. See supported networks.
Customer: A person grouped by email, with their payment count and totals, added as soon as checkout has their email. You can block one from paying. IDs start with cst_. See list customers.

Deposit: Where a paid payment's funds landed: a wallet transaction into your wallet, in the coin and network paid, for the whole amount that arrived. The payment's settlement field shows it, or that the payment was collected as fees instead. See wallet and deposits.

Event: A record of something that happened, such as payment.succeeded, with a snapshot of its subject as it was then. Webhooks deliver events. IDs start with evt_. See list events.
External wallet: A wallet you already use, connected by its public keys, so 402pay never sees its recovery phrase. Payments land in it, and sends happen in its own app. See wallet and deposits.

Fee statement: What your business owes 402pay in fees, and the entries behind it. Once you owe enough, 402pay collects it by sending whole payments to its own address, whose settlement.destination is fees. Entry IDs start with fee_. See fees and billing.

Idempotency key: A random value sent in a header that makes a POST safe to retry: the same key returns the first response instead of doing the work twice. See idempotency.

Main address: The first address on each network in your wallet, the one to share for deposits. Sends draw on whichever of the wallet's addresses hold the coin, largest first.
Metadata: Your own key-value strings on a payment, returned with it and with every event about it. See metadata.
Mode: test or live, for the kind of key behind an event. Always live during the beta, when test and live keys share data. See test and live keys.

Payment link: A reusable hosted checkout with a fixed price. Every customer who pays it makes a new payment that carries its link_id. IDs start with lnk_. See payment links.

Quote: The coin amount a crypto checkout asks for, at a rate locked for a window, 15 minutes by default. A transfer after it expires needs your review. See underpayments and overpayments.

Rail: How the customer pays: crypto or card. Card payments arrive in the coin and network selected for that checkout. See card payments.
Reference: Your own ID for an API payment, such as an order number. It names one live payment, so a retried create returns the payment that already exists. See create the payment.
Remainder: A checkout for exactly what's left of an underpaid payment, in the same coin and network and attached to the same payment, so no second payment is made. See request the rest.
Request ID: The req_ ID in every response's 402pay-Request-Id header, repeated in every error as request_id. Include it when you contact support.
Restricted key: A secret key with none, read or write on each resource, rather than full access. See restricted keys.
Review reason: Why a checkout's funds need your decision: late, wrong_network or claimed. It's on the checkout, in review_reason. See needs review.

Tolerance: How far short a crypto transfer can fall and still count as paid in full, 0.5% unless you change it in Settings, under Checkout. See underpaid.

Webhook endpoint: A URL on your server that receives signed events of the types you choose, retried until it answers. IDs start with whk_. See webhooks.