# 402pay

> 402pay is a non-custodial payments platform: businesses take cards, Apple Pay, Google Pay and crypto in one checkout, and every payment lands in a self-custody wallet only they control.

The REST API takes and returns JSON, uses standard HTTP status codes, and authenticates with a secret key. Every path in the docs is relative to the base URL, https://dash.402pay.co/api/v1.

Every page below is Markdown: add `.md` to any docs page's URL to get it. [llms-full.txt](https://developer.402pay.co/llms-full.txt) has every page in one file.

## Get started

- [Overview](https://developer.402pay.co/index.md): What you can build with the 402pay API, and where to start.
- [Quickstart](https://developer.402pay.co/quickstart.md): Take your first payment in five steps, from a new account to a fulfilled order.
- [Core concepts](https://developer.402pay.co/concepts.md): Payments, checkouts, links, customers, events and your wallet, and how they fit together.
- [Authentication](https://developer.402pay.co/authentication.md): Authenticate with a secret key, scope it per resource, and keep it safe.
- [Testing](https://developer.402pay.co/testing.md): Build with test keys and rehearse every way a payment can arrive.
- [Going live](https://developer.402pay.co/going-live.md): Everything to check before you take real payments, and after.
- [Security best practices](https://developer.402pay.co/guides/security.md): Narrow keys, rotations without downtime, a locked-down webhook endpoint and a secure account.

## Guides

- [Accept a payment](https://developer.402pay.co/guides/accept-a-payment.md): Create a payment on your server, send the customer to checkout, and fulfill on the webhook.
- [Fulfill orders reliably](https://developer.402pay.co/guides/order-fulfillment.md): Keep one payment per order, map each status to the order, and ship exactly once.
- [Framework recipes](https://developer.402pay.co/guides/frameworks.md): Create payments, handle the return and verify webhooks in Next.js, Express, Django and Laravel, without an SDK.
- [Payment links](https://developer.402pay.co/guides/payment-links.md): Reusable hosted checkouts with a fixed price that you can share anywhere.
- [Recurring and repeat payments](https://developer.402pay.co/guides/recurring-payments.md): Bill subscriptions and invoices with one payment per period, sent to the customer on your schedule.
- [Hosted checkout](https://developer.402pay.co/guides/hosted-checkout.md): Everything between choosing how to pay and the receipt, on one hosted page.
- [Card payments](https://developer.402pay.co/guides/card-payments.md): Accept cards, Apple Pay and Google Pay through hosted checkout.
- [Underpayments and overpayments](https://developer.402pay.co/guides/underpayments.md): What happens when a customer sends too little, too much, too late or on the wrong network.
- [Refunds, returns and disputes](https://developer.402pay.co/guides/refunds.md): Send refunds from your wallet, return funds you don't accept, and keep disputes rare.
- [Receipts](https://developer.402pay.co/guides/receipts.md): The hosted receipt every paid payment gets, and the same receipt as data.

## Platform

- [Webhooks](https://developer.402pay.co/guides/webhooks.md): Signed events for every change, retried until your server answers.
- [Webhook event catalog](https://developer.402pay.co/guides/webhook-events.md): Every event type, what its data holds, and the order a payment's events arrive in.
- [Wallet and deposits](https://developer.402pay.co/guides/settlement.md): The three kinds of wallet, how each payment lands in yours, and who holds the keys.
- [Solana checkout addresses](https://developer.402pay.co/guides/solana-checkout-addresses.md): How each Solana checkout gets a fresh address from a public key, the derivation to reproduce it, and moving the funds with only the recovery phrase.
- [Reporting and reconciliation](https://developer.402pay.co/guides/reconciliation.md): Which amounts to report, how payments match your wallet, and how to export a period.
- [Fees and billing](https://developer.402pay.co/guides/fees.md): How fees accrue, how 402pay collects them from your payments, and how to read your fee statement.
- [Supported networks](https://developer.402pay.co/guides/networks.md): Every coin and network checkout accepts, and the confirmations each one needs.
- [AI agents](https://developer.402pay.co/guides/ai-agents.md): An MCP server for Claude Code, Codex and other agents is coming soon. Until then, agents can use the API.

## Resources

- [Frequently asked questions](https://developer.402pay.co/faq.md): What businesses ask most about 402pay, grouped by payments, webhooks, wallet, keys and billing.
- [Troubleshooting](https://developer.402pay.co/troubleshooting.md): From what you're seeing to the error code behind it and the fix.
- [Glossary](https://developer.402pay.co/glossary.md): The terms the API and these docs use, from actor to webhook endpoint.

## API Reference: Basics

- [Introduction](https://developer.402pay.co/api.md): The base URL, how requests and responses are shaped, and every endpoint.
- [Errors](https://developer.402pay.co/api/errors.md): Status codes, the error envelope, and the codes to branch on.
- [Idempotency](https://developer.402pay.co/api/idempotency.md): Retry any request safely with an Idempotency-Key header.
- [Pagination](https://developer.402pay.co/api/pagination.md): Walk every list endpoint with limit and cursor.
- [Metadata](https://developer.402pay.co/api/metadata.md): Attach your own key-value data to payments and filter by it.
- [Amounts, currencies and exchange rates](https://developer.402pay.co/api/currencies.md): How prices, US dollar reporting and coin amounts are written, and how one becomes another.

## API Reference: Endpoints

- [Create a payment](https://developer.402pay.co/api/payments/create.md): `POST /payments` - Create a payment for an exact amount and get a hosted checkout URL for it.
- [Retrieve a payment](https://developer.402pay.co/api/payments/retrieve.md): `GET /payments/{id}` - Get a payment with its method, deposit and timeline.
- [List payments](https://developer.402pay.co/api/payments/list.md): `GET /payments` - List payments, filtered by status, rail, reference, customer, link, metadata or date.
- [Update a payment](https://developer.402pay.co/api/payments/update.md): `PATCH /payments/{id}` - Change a payment's metadata.
- [Cancel a payment](https://developer.402pay.co/api/payments/cancel.md): `POST /payments/{id}/cancel` - Stop a payment created through the API before any funds arrive.
- [Accept a payment](https://developer.402pay.co/api/payments/accept.md): `POST /payments/{id}/accept` - Count an underpaid payment, or one that needs review, as paid with what arrived.
- [Request the remainder](https://developer.402pay.co/api/payments/request-remainder.md): `POST /payments/{id}/request-remainder` - Ask the customer of an underpaid payment for exactly what's left, once its quote has expired.
- [Create a checkout](https://developer.402pay.co/api/checkouts/create.md): `POST /checkouts` - Start an attempt at paying a link or payment, and reserve a fresh address for crypto.
- [Retrieve a checkout](https://developer.402pay.co/api/checkouts/retrieve.md): `GET /checkouts/{id}` - Get a checkout's address, amounts and confirmations while the customer pays.
- [Cancel a checkout](https://developer.402pay.co/api/checkouts/cancel.md): `POST /checkouts/{id}/cancel` - Close a checkout the customer is leaving, before any funds are on the way.
- [Supersede a checkout](https://developer.402pay.co/api/checkouts/supersede.md): `POST /checkouts/{id}/supersede` - Set a quote aside when the customer steps back to choose another way to pay.
- [Claim a transfer](https://developer.402pay.co/api/checkouts/claim.md): `POST /checkouts/{id}/claim` - Let a customer report a transfer by its hash after their checkout closed.
- [Retry a card payment](https://developer.402pay.co/api/checkouts/card/retry.md): `POST /checkouts/{id}/card/retry` - Offer another card-payment attempt when checkout allows it.
- [Simulate a transfer](https://developer.402pay.co/api/checkouts/mark-sent.md): `POST /checkouts/{id}/mark-sent` - For testing: make a crypto checkout receive its transfer now, exact or not.
- [Retrieve a public link](https://developer.402pay.co/api/checkouts/public-link.md): `GET /public/links/{code}` - Get what a link's hosted checkout shows, without IDs, fees or internal settings.
- [Retrieve a receipt](https://developer.402pay.co/api/checkouts/receipt.md): `GET /public/receipts/{id}` - Get a payment's public receipt, the data behind its hosted receipt page.
- [Create a link](https://developer.402pay.co/api/links/create.md): `POST /links` - Create a reusable hosted checkout with a fixed price.
- [List links](https://developer.402pay.co/api/links/list.md): `GET /links` - List your payment links, newest first, with each one's payment count and volume.
- [Retrieve a link](https://developer.402pay.co/api/links/retrieve.md): `GET /links/{id}` - Get a payment link with its payment count and volume.
- [Update a link](https://developer.402pay.co/api/links/update.md): `PATCH /links/{id}` - Change a link's details or price, or archive it to stop taking payments.
- [Delete a link](https://developer.402pay.co/api/links/delete.md): `DELETE /links/{id}` - Delete a link that has never taken a payment.
- [Create a customer](https://developer.402pay.co/api/customers/create.md): `POST /customers` - Add a customer before they pay, such as an account from your own system.
- [List customers](https://developer.402pay.co/api/customers/list.md): `GET /customers` - List the people who have paid you or started to, with totals for each.
- [Retrieve a customer](https://developer.402pay.co/api/customers/retrieve.md): `GET /customers/{id}` - Get a customer with their payment count and totals.
- [Update a customer](https://developer.402pay.co/api/customers/update.md): `PATCH /customers/{id}` - Change a customer's details or note, or block them from paying.
- [List events](https://developer.402pay.co/api/events/list.md): `GET /events` - List everything that happened in your business, with a snapshot of each subject.
- [Retrieve an event](https://developer.402pay.co/api/events/retrieve.md): `GET /events/{id}` - Get one event with the snapshot of its subject.
- [List event types](https://developer.402pay.co/api/events/types.md): `GET /event-types` - Every event type, what it means, and whether webhooks can receive it.
- [Create a webhook endpoint](https://developer.402pay.co/api/webhooks/create.md): `POST /webhooks` - Add an endpoint for the events you choose and get its signing secret.
- [List webhook endpoints](https://developer.402pay.co/api/webhooks/list.md): `GET /webhooks` - List your webhook endpoints and the events each one receives.
- [Retrieve a webhook endpoint](https://developer.402pay.co/api/webhooks/retrieve.md): `GET /webhooks/{id}` - Get one endpoint with the events it receives.
- [Update a webhook endpoint](https://developer.402pay.co/api/webhooks/update.md): `PATCH /webhooks/{id}` - Change an endpoint's URL, events or description, or turn it off.
- [Delete a webhook endpoint](https://developer.402pay.co/api/webhooks/delete.md): `DELETE /webhooks/{id}` - Remove an endpoint and stop its deliveries, including pending retries.
- [Send a test event](https://developer.402pay.co/api/webhooks/test.md): `POST /webhooks/{id}/test` - Deliver a signed sample event to an endpoint to check your handler.
- [Rotate a signing secret](https://developer.402pay.co/api/webhooks/rotate-secret.md): `POST /webhooks/{id}/rotate-secret` - Replace an endpoint's signing secret, with the old one signing alongside for a day.
- [List deliveries](https://developer.402pay.co/api/webhooks/deliveries.md): `GET /webhook-deliveries` - Every delivery attempt with its signed request and your server's response.
- [Retrieve a delivery](https://developer.402pay.co/api/webhooks/deliveries/retrieve.md): `GET /webhook-deliveries/{id}` - Get one delivery with every attempt, its signed request and your server's response.
- [List an endpoint's deliveries](https://developer.402pay.co/api/webhooks/endpoint-deliveries.md): `GET /webhooks/{id}/deliveries` - List the deliveries to one endpoint, newest first.
- [Resend a delivery](https://developer.402pay.co/api/webhooks/resend.md): `POST /webhook-deliveries/{id}/resend` - Send a delivery again, now, with a fresh timestamp and signature.
- [Retrieve the wallet](https://developer.402pay.co/api/wallet/retrieve.md): `GET /wallet` - Get your wallet's balances per coin and network, and its main addresses.
- [Update the wallet](https://developer.402pay.co/api/wallet/update.md): `PATCH /wallet` - Rename your wallet.
- [List wallet transactions](https://developer.402pay.co/api/wallet/transactions.md): `GET /wallet/transactions` - List money in and out of your wallet, including every payment's deposit.
- [Retrieve a wallet transaction](https://developer.402pay.co/api/wallet/transactions/retrieve.md): `GET /wallet/transactions/{id}` - Get one transaction in or out of your wallet.
- [Update a wallet transaction](https://developer.402pay.co/api/wallet/transactions/update.md): `PATCH /wallet/transactions/{id}` - Add or change a transaction's note, such as what a send was for.
- [Retrieve fee estimates](https://developer.402pay.co/api/wallet/fee-estimates.md): `GET /wallet/fee-estimates` - Get what a send pays the network at each speed, and how long it takes.
- [Retrieve a send context](https://developer.402pay.co/api/wallet/send-context.md): `GET /wallet/send-context` - Get what the dashboard needs to sign a send: each funded address with its balance and nonce, and the fees.
- [Send from the wallet](https://developer.402pay.co/api/wallet/transactions/create.md): `POST /wallet/transactions` - Relay a send the dashboard signed in the browser, or record one made in an external wallet's app.
- [Delete the wallet](https://developer.402pay.co/api/wallet/delete.md): `DELETE /wallet` - Remove your wallet, right away during setup or after a 24-hour hold once you've been paid.
- [Cancel a wallet change](https://developer.402pay.co/api/wallet/changes/cancel.md): `POST /wallet/changes/{id}/cancel` - Stop a wallet deletion while it's still waiting out the hold.
- [Retrieve a business](https://developer.402pay.co/api/businesses/retrieve.md): `GET /businesses/{id}` - Get your business's profile, and where its email alerts go.
- [Update a business](https://developer.402pay.co/api/businesses/update.md): `PATCH /businesses/{id}` - Change your business's name, website and emails, and turn alert emails on or off.
- [Confirm an alert email](https://developer.402pay.co/api/businesses/alert-email/confirm.md): `POST /businesses/{id}/alert-email/confirm` - Enter the code sent to a new alert address, so payment alerts go there.
- [Resend an alert email code](https://developer.402pay.co/api/businesses/alert-email/resend.md): `POST /businesses/{id}/alert-email/resend` - Send a new code to the alert address waiting for one.
- [Cancel an alert email change](https://developer.402pay.co/api/businesses/alert-email/cancel.md): `POST /businesses/{id}/alert-email/cancel` - Drop the alert address waiting for its code, so alerts keep going where they go now.
- [Retrieve checkout settings](https://developer.402pay.co/api/settings/retrieve.md): `GET /settings/checkout` - Get the coins, networks and rails checkout offers, and how it quotes and redirects.
- [Update checkout settings](https://developer.402pay.co/api/settings/update.md): `PATCH /settings/checkout` - Turn coins and card payments on or off, and change the quote window, tolerance and redirect.
- [Retrieve the fee statement](https://developer.402pay.co/api/billing/fees.md): `GET /billing/fees` - Get what your business owes 402pay in fees, what's on its way to 402pay, and this month's totals.
- [List fee entries](https://developer.402pay.co/api/billing/fees/entries.md): `GET /billing/fees/entries` - List every fee, collection and adjustment behind your fee statement, newest first.
- [Retrieve metrics](https://developer.402pay.co/api/metrics.md): `GET /metrics` - Get revenue, payment counts, new customers and approval rate over time, with the period before.
- [Search](https://developer.402pay.co/api/search.md): `GET /search` - Find payments, customers and links with one query, best matches first.
- [Retrieve exchange rates](https://developer.402pay.co/api/exchange-rates.md): `GET /exchange-rates` - Get the coin prices and currency rates checkout quotes with.

## Changelog

- [Changelog](https://developer.402pay.co/changelog.md): What changed in the API, webhooks, checkout and these docs.