> For the complete index of the 402pay docs, see [llms.txt](https://developer.402pay.co/llms.txt).

# Introduction

The base URL, how requests and responses are shaped, and every endpoint.

The 402pay API is organized around resources, with predictable URLs, JSON bodies and standard HTTP status codes. Requests use your [secret key](https://developer.402pay.co/authentication.md), except the public checkout, exchange rate, event type and health endpoints, and the ones only the dashboard can call, such as sending from your wallet and changing your business's profile.

## Base URL

Base URL: `https://dash.402pay.co/api/v1`

[API v1](https://developer.402pay.co/changelog.md)

`GET /health` answers without a key, so it's a quick way to check that your server can reach the API.

## Conventions

- Send and receive JSON. A request with a body needs `Content-Type: application/json`, or it returns 415 `unsupported_media_type`. Fields and query parameters are snake_case.
- Every object has a `kind`, such as `payment` or `checkout`, and an ID whose prefix says what it is.
- Timestamps are ISO 8601 in UTC.
- Money is an integer in minor units with its `currency`: `4900` with `USD` is $49.00. USD totals for reporting live under `reporting`.
- Coin amounts are decimal strings, such as `"49.00"`, so no precision is lost.
- A single object comes back as `{ data }`, a create returns 201, and a delete returns the object's `id` and `kind` with `deleted: true`.
- A path that doesn't exist returns 404 `not_found` in the same [error envelope](https://developer.402pay.co/api/errors.md) as every other error. A method a path doesn't take, such as `DELETE /payments/{id}`, returns a bare 405 instead, with no body.
- Every response except a 405 has a `402pay-Request-Id` header, and every error repeats it as `request_id`. Include it when you contact support.

## ID prefixes

| Prefix | Object |
| --- | --- |
| `biz_` | Business, as in the 402pay-Business header |
| `pmt_` | Payment |
| `chk_` | Checkout |
| `lnk_` | Payment link |
| `cst_` | Customer |
| `evt_` | Event |
| `whk_` | Webhook endpoint |
| `dlv_` | Webhook delivery |
| `wal_` | Wallet |
| `wtx_` | Wallet transaction |
| `key_` | API key, and an event's `actor.id` when a key made the change |
| `usr_` | A person on your team, as an event's `actor.id` |
| `req_` | Request, in errors and the request ID header |

## Versioning

- The version is part of the base URL, `/api/v1`. There's no version header, and nothing to pin per request.
- Every event carries `api_version`, `v1` today: the version of its shape, so a webhook handler knows which fields to expect.
- New fields and event types can appear within a version, so ignore the ones your code doesn't know rather than refusing them.
- Every change is in the [changelog](https://developer.402pay.co/changelog.md).

## Endpoints

Payments

- [POST](https://developer.402pay.co/api/payments/create.md): /payments
- [GET](https://developer.402pay.co/api/payments/retrieve.md): /payments/{id}
- [GET](https://developer.402pay.co/api/payments/list.md): /payments
- [PATCH](https://developer.402pay.co/api/payments/update.md): /payments/{id}
- [POST](https://developer.402pay.co/api/payments/cancel.md): /payments/{id}/cancel
- [POST](https://developer.402pay.co/api/payments/accept.md): /payments/{id}/accept
- [POST](https://developer.402pay.co/api/payments/request-remainder.md): /payments/{id}/request-remainder

Checkouts

- [POST](https://developer.402pay.co/api/checkouts/create.md): /checkouts
- [GET](https://developer.402pay.co/api/checkouts/retrieve.md): /checkouts/{id}
- [POST](https://developer.402pay.co/api/checkouts/cancel.md): /checkouts/{id}/cancel
- [POST](https://developer.402pay.co/api/checkouts/supersede.md): /checkouts/{id}/supersede
- [POST](https://developer.402pay.co/api/checkouts/claim.md): /checkouts/{id}/claim
- [POST](https://developer.402pay.co/api/checkouts/card/retry.md): /checkouts/{id}/card/retry
- [POST](https://developer.402pay.co/api/checkouts/mark-sent.md): /checkouts/{id}/mark-sent
- [GET](https://developer.402pay.co/api/checkouts/public-link.md): /public/links/{code}
- [GET](https://developer.402pay.co/api/checkouts/receipt.md): /public/receipts/{id}

Links

- [POST](https://developer.402pay.co/api/links/create.md): /links
- [GET](https://developer.402pay.co/api/links/list.md): /links
- [GET](https://developer.402pay.co/api/links/retrieve.md): /links/{id}
- [PATCH](https://developer.402pay.co/api/links/update.md): /links/{id}
- [DELETE](https://developer.402pay.co/api/links/delete.md): /links/{id}

Customers

- [POST](https://developer.402pay.co/api/customers/create.md): /customers
- [GET](https://developer.402pay.co/api/customers/list.md): /customers
- [GET](https://developer.402pay.co/api/customers/retrieve.md): /customers/{id}
- [PATCH](https://developer.402pay.co/api/customers/update.md): /customers/{id}

Events

- [GET](https://developer.402pay.co/api/events/list.md): /events
- [GET](https://developer.402pay.co/api/events/retrieve.md): /events/{id}
- [GET](https://developer.402pay.co/api/events/types.md): /event-types

Webhooks

- [POST](https://developer.402pay.co/api/webhooks/create.md): /webhooks
- [GET](https://developer.402pay.co/api/webhooks/list.md): /webhooks
- [GET](https://developer.402pay.co/api/webhooks/retrieve.md): /webhooks/{id}
- [PATCH](https://developer.402pay.co/api/webhooks/update.md): /webhooks/{id}
- [DELETE](https://developer.402pay.co/api/webhooks/delete.md): /webhooks/{id}
- [POST](https://developer.402pay.co/api/webhooks/test.md): /webhooks/{id}/test
- [POST](https://developer.402pay.co/api/webhooks/rotate-secret.md): /webhooks/{id}/rotate-secret
- [GET](https://developer.402pay.co/api/webhooks/deliveries.md): /webhook-deliveries
- [GET](https://developer.402pay.co/api/webhooks/deliveries/retrieve.md): /webhook-deliveries/{id}
- [GET](https://developer.402pay.co/api/webhooks/endpoint-deliveries.md): /webhooks/{id}/deliveries
- [POST](https://developer.402pay.co/api/webhooks/resend.md): /webhook-deliveries/{id}/resend

Wallet

- [GET](https://developer.402pay.co/api/wallet/retrieve.md): /wallet
- [PATCH](https://developer.402pay.co/api/wallet/update.md): /wallet
- [GET](https://developer.402pay.co/api/wallet/transactions.md): /wallet/transactions
- [GET](https://developer.402pay.co/api/wallet/transactions/retrieve.md): /wallet/transactions/{id}
- [PATCH](https://developer.402pay.co/api/wallet/transactions/update.md): /wallet/transactions/{id}
- [GET](https://developer.402pay.co/api/wallet/fee-estimates.md): /wallet/fee-estimates
- [GET](https://developer.402pay.co/api/wallet/send-context.md): /wallet/send-context
- [POST](https://developer.402pay.co/api/wallet/transactions/create.md): /wallet/transactions
- [DELETE](https://developer.402pay.co/api/wallet/delete.md): /wallet
- [POST](https://developer.402pay.co/api/wallet/changes/cancel.md): /wallet/changes/{id}/cancel

Businesses

- [GET](https://developer.402pay.co/api/businesses/retrieve.md): /businesses/{id}
- [PATCH](https://developer.402pay.co/api/businesses/update.md): /businesses/{id}
- [POST](https://developer.402pay.co/api/businesses/alert-email/confirm.md): /businesses/{id}/alert-email/confirm
- [POST](https://developer.402pay.co/api/businesses/alert-email/resend.md): /businesses/{id}/alert-email/resend
- [POST](https://developer.402pay.co/api/businesses/alert-email/cancel.md): /businesses/{id}/alert-email/cancel

Settings

- [GET](https://developer.402pay.co/api/settings/retrieve.md): /settings/checkout
- [PATCH](https://developer.402pay.co/api/settings/update.md): /settings/checkout

Billing

- [GET](https://developer.402pay.co/api/billing/fees.md): /billing/fees
- [GET](https://developer.402pay.co/api/billing/fees/entries.md): /billing/fees/entries

Metrics

- [GET](https://developer.402pay.co/api/metrics.md): /metrics

Search

- [GET](https://developer.402pay.co/api/search.md): /search

Exchange rates

- [GET](https://developer.402pay.co/api/exchange-rates.md): /exchange-rates