# API reference

Every public endpoint, grouped by area. All paths are relative to the versioned base URL.

```text
https://sandbox-api.baxpay.com/v1   # sandbox: bx_test_… keys (live keys are refused here)
https://api.baxpay.com/v1           # live: bx_live_… keys
```

Each endpoint below names its credential:

| Label | Credential |
| --- | --- |
| **key** | Your API key, `Bearer bx_test_…` / `Bearer bx_live_…` (server-side only) |
| **bxc** | A [connection credential](https://developers.baxpay.com/connections), `Bearer bxc_…` (tills, pumps, ERP links) |
| **public** | None: payer and shopper pages, rate-limited per IP |
| **dashboard** | A signed-in Business dashboard user; not callable with an API key |

Read [API conventions](https://developers.baxpay.com/conventions) first: the response envelope, pagination, idempotency keys
and rate limits apply everywhere.

## Developer

- `GET /ping` — key · which business and mode a key belongs to
- `POST /connections` — key · create a bxc_ connection (till, pump, ERP link)
- `GET /connections` — key · list this mode's connections
- `DELETE /connections/{id}` — key · revoke
- `GET /sessions` — key · recent in-store sessions in this mode

## Webhooks

- `POST /webhooks` — key · register an endpoint (secret returned once)
- `GET /webhooks` — key · list
- `GET /webhooks/{id}` — key · retrieve
- `POST /webhooks/{id}/test` — key · send a signed webhook.test
- `DELETE /webhooks/{id}` — key · delete

## Payment links

- `POST /payment-links` — key · charge anyone online
- `GET /payment-links` — key · list (status, storeId)
- `GET /payment-links/{id}` — key · retrieve
- `POST /payment-links/{id}/cancel` — key · cancel an open link
- `GET /pay/link/{token}` — public · payer view
- `POST /pay/link/{token}/card` — public · guest card payment (sandbox / acquirer)
- `POST /pay/link/{token}/card/3ds` — public · test links: finish simulated 3D Secure
- `POST /pay/link/{token}/simulate` — public · test links: pay with another active method, simulated
- `POST /business/payment-links/{id}/resend` — dashboard · email the link again

## Clients

- `POST /clients` — key · create
- `GET /clients` — key · list / search (search, kind, includeArchived)
- `GET /clients/{id}` — key · retrieve
- `PUT /clients/{id}` — key · update (invoices keep their snapshot)
- `POST /clients/{id}/archive` — key · hide from pickers, keep history
- `POST /clients/{id}/unarchive` — key · restore
- `DELETE /clients/{id}` — key · delete

## E-invoicing (France)

- `POST /einvoices` — key · create an EN 16931-validated draft
- `PUT /einvoices/{id}` — key · update a draft
- `GET /einvoices` — key · list sent + received
- `GET /einvoices/{id}` — key · detail and lifecycle trail
- `POST /einvoices/{id}/send` — key · deposit + emit as Factur-X
- `POST /einvoices/{id}/lifecycle` — key · approve / refuse / dispute / collect
- `POST /einvoices/{id}/payment-link` — key · create the hosted pay link
- `GET /einvoices/ereporting/periods` — key · legal periods for your VAT regime
- `POST /einvoices/ereporting/generate` — key · build a period submission
- `POST /einvoices/ereporting/{id}/submit` — key · transmit it
- `GET /einvoices/ereporting` — key · list submissions
- `GET /pay/einvoice/{token}` — public · payer view
- `POST /pay/einvoice/{token}/card` — public · guest card payment
- `POST /pay/einvoice/{token}/card/3ds` — public · test invoices: finish simulated 3D Secure

## Products & catalog

- `POST /products` — key · create (image optional)
- `GET /products` — key · list active products (search, channel)
- `GET /products/{id}` — key · retrieve
- `PATCH /products/{id}` — key · update
- `GET /products/{id}/label` — key · shelf-label payload
- `GET /products/export/catalog` — key · baxpay.catalog.v1
- `GET /products/export/intrastat` — key · HS code rows (from, to)
- `POST /products/export/push-erp` — key · push to every active accounting link

## In-store sessions

All under `/integration`. See [Terminal & Session API](https://developers.baxpay.com/terminal-api).

- `POST /integration/sessions` — bxc · open a SALE or PREAUTH
- `GET /integration/sessions/{id}` — bxc · poll until final
- `GET /integration/sessions/by-reference/{saleReferenceId}` — bxc · find by your reference
- `POST /integration/sessions/{id}/void` — bxc · void before capture
- `POST /integration/sessions/{id}/simulate` — bxc · sandbox outcome
- `POST /integration/sessions/{id}/fuel/capture` — bxc · capture the dispensed amount
- `POST /integration/sessions/{id}/fuel/release` — bxc · release a pre-auth
- `POST /integration/nexo/saleToPOI` — bxc · nexo adapter
- `POST /integration/ifsf/reservation` — bxc · IFSF pre-auth
- `POST /integration/ifsf/completion` — bxc · IFSF capture
- `POST /integration/opi/cardServiceRequest` — bxc · OPI adapter

## Settlement & reconciliation

- `POST /integration/reconciliation/close` — bxc · close a business day (Paris date)
- `GET /integration/reconciliation/batches` — bxc · list this mode's batches
- `GET /integration/reconciliation/batches/{id}` — bxc · batch + sessions
- `GET /integration/reconciliation/batches/{id}/export.csv` — bxc · per-session CSV
- `GET /integration/reconciliation/batches/{id}/export.camt053` — bxc · camt.053-style JSON

## Online shop (storefront)

See [Storefront API](https://developers.baxpay.com/online-shop/storefront-api).

- `GET /shop/resolve` — public · ?host=
- `GET /shop/{slug}/catalog` — public · online products
- `GET /shop/{slug}/products/{productId}` — public · one product + related
- `POST /shop/{slug}/quote` — public · price a cart
- `POST /shop/{slug}/checkout` — public · create the order → payUrl
- `GET /shop/{slug}/orders/{token}` — public · order page
- `POST /shop/{slug}/orders/{token}/cancel` — public · drop an unpaid order
- `GET /shop/{slug}/products/{productId}/slots` — public · free booking slots
- `GET /shop/{slug}/bookings/{token}` — public · booking page
- `GET /shop/{slug}/bookings/{token}/ics` — public · calendar file
- `POST /shop/{slug}/bookings/{token}/cancel` — public · cancel a paid booking in its window
- `POST /shop/{slug}/bookings/{token}/reschedule` — public · move a paid booking

## Dashboard only

These exist for the Business dashboard and need a signed-in user:
`/merchant-integrations` (accounting OAuth links), `/webhooks` (the dashboard's own webhook
screens), `/payments`, `/business/theme-studio/*` and `/business/products/import`.