# Zetus SPEI API - developer documentation

Collect SPEI transfers on your own CLABEs: create a CLABE per customer, get notified when money arrives, and confirm it before you apply it. Request outgoing SPEI payments that two people of your organisation approve.

Status: **the sandbox is the environment to integrate against now**: API `https://sandbox.zenit.zetuspay.com.mx`, token endpoint `https://auth.sandbox.zenit.zetuspay.com.mx/oauth2/token`, docs `https://docs.sandbox.zenit.zetuspay.com.mx` ([use the sandbox](how-to/use-the-sandbox.md)). Production is not live yet: API `https://api.zenit.zetuspay.com.mx` (to be confirmed), identity provider `https://idp.zetuspay.com.mx` (token endpoint `https://idp.zetuspay.com.mx/oauth2/token`, discovery `https://idp.zetuspay.com.mx/.well-known/openid-configuration`). At go-live you change the token URL, the API URL and the certificate.

## Map

| You want to... | Read |
|---|---|
| Make your first call | [tutorials/quickstart.md](tutorials/quickstart.md) |
| Use the sandbox (trigger deposits, approve payments, force outcomes) | [how-to/use-the-sandbox.md](how-to/use-the-sandbox.md) |
| Get a client certificate | [how-to/certificate-csr.md](how-to/certificate-csr.md) |
| Get and cache an access token | [how-to/get-a-token.md](how-to/get-a-token.md) |
| Retry safely after a timeout | [how-to/idempotency-and-retries.md](how-to/idempotency-and-retries.md) |
| Walk a list | [how-to/pagination.md](how-to/pagination.md) |
| Receive and verify webhooks | [how-to/verify-webhooks.md](how-to/verify-webhooks.md) |
| Handle errors | [how-to/errors.md](how-to/errors.md) |
| Send payments | [how-to/send-payments.md](how-to/send-payments.md) |
| Go to production | [how-to/go-live.md](how-to/go-live.md) |
| Understand when money is real | [explanation/incoming-transfer-lifecycle.md](explanation/incoming-transfer-lifecycle.md) |
| Understand the 18:00 cut | [explanation/operation-date-and-cutoff.md](explanation/operation-date-and-cutoff.md) |
| Understand when a payment is final | [explanation/payment-lifecycle.md](explanation/payment-lifecycle.md) |
| Look up an endpoint or field | [reference/README.md](reference/README.md) |

## Conventions in one minute

- Auth: mutual TLS (client certificate) **plus** `Authorization: Bearer <JWT>` bound to that certificate.
- Success: `{"data": ..., "meta": {"traceId": "..."}}`. Errors: `{"error": {"code", "message", "details", "traceId"}}`.
- Money is an integer in centavos with `currency: "MXN"` (`150050` = $1,500.50). Dates are UTC ISO 8601.
- Every write needs a `reference` (your idempotency key).

## Other artifacts

- `../openapi/openapi.json` - the OpenAPI 3.1 contract.
- `codes.json` - error catalogue.
- `bruno/` - Bruno collection generated from the contract.
- `sdk/` - TypeScript types generated from the contract.
- `llms.txt`, `llms-full.txt` - the docs for LLM tools.
- `scripts/` - generators ([scripts/README.md](scripts/README.md)).