Introduction

The 402pay API is organized around resources, with predictable URLs, JSON bodies and standard HTTP status codes. Requests use your secret key, 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.

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

• 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 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.

• 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.