Payments

Clients

Create each counterparty once, reference them everywhere — payment links, invoices, reporting.

A client is a general-purpose counterparty record, not an e-invoicing artifact: use it to group payment links per customer, to prefill invoices, or simply as the customer book behind your own app. Clients are mode-scoped like everything else — test clients exist only for test keys.

Only name is required. The identifiers (siren, siret, vatId) matter when you invoice a French business under the e-invoicing mandate; a consumer or a non-French client simply doesn't have them.

Create a client

POST/clientsIdempotency-Key required

curl -X POST https://sandbox-api.baxpay.com/v1/clients \
  -H "Authorization: Bearer $BAXPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME SAS",
    "email": "[email protected]",
    "address": {
      "line1": "12 rue de la Paix",
      "city": "Paris",
      "postalCode": "75002",
      "countryCode": "FR"
    },
    "siren": "552100554",
    "vatId": "FR96552100554"
  }'

const res = await fetch('https://sandbox-api.baxpay.com/v1/clients', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BAXPAY_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  // A consumer: only the name is required.
  body: JSON.stringify({ name: 'Marie Dupont', email: '[email protected]', clientKind: 'B2C' }),
});
const body = await res.json();
if (!res.ok) throw new Error(JSON.stringify(body));
console.log(JSON.stringify(body, null, 2));

{
  "success": true,
  "data": {
    "id": "b7e1c2d0-…",
    "name": "…",
    "clientKind": "B2B",
    "email": "…",
    "livemode": false,
    "archivedAt": null,
    "createdAt": "2026-07-16T14:00:00.000Z"
  }
}

Field	Meaning
`name`	Required. The name you use day to day
`legalName`	Registered name when it differs (printed on invoices)
`clientKind`	`B2B` (default), `B2C` or `B2B_INTERNATIONAL`
`email`, `phone`	Contact; the email receives payment links and invoices
`address`	`line1`, `line2`, `city`, `postalCode`, `countryCode`
`siren`, `siret`, `vatId`	French identifiers, checked when present; a SIREN is unique per mode in your account
`electronicAddress`	The client's e-invoicing address, when it differs from its SIREN
`buyerReference`	Default purchase reference stamped on that client's invoices
`notes`	Free text for your team

Manage clients

GET/clients?search=acme&kind=B2B&includeArchived=false&page=1&limit=25

GET/clients/{id}

PUT/clients/{id}Idempotency-Key required

POST/clients/{id}/archiveIdempotency-Key required

POST/clients/{id}/unarchiveIdempotency-Key required

DEL/clients/{id}Idempotency-Key required

curl "https://sandbox-api.baxpay.com/v1/clients?search=acme&limit=25" \
  -H "Authorization: Bearer $BAXPAY_API_KEY"

{
  "success": true,
  "data": { "data": [{ "id": "b7e1c2d0-…", "name": "ACME SAS", "siren": "552100554" }], "total": 1, "page": 1, "limit": 25 }
}

search matches name, SIREN and email; kind filters by clientKind.

curl -X PUT https://sandbox-api.baxpay.com/v1/clients/b7e1c2d0-… \
  -H "Authorization: Bearer $BAXPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "buyerReference": "PO-ACME-2026" }'

{ "success": true, "data": { "id": "b7e1c2d0-…", "email": "[email protected]", "buyerReference": "PO-ACME-2026" } }

Archive hides a client from pickers while keeping its history; prefer it over delete.

curl -X POST https://sandbox-api.baxpay.com/v1/clients/b7e1c2d0-…/archive \
  -H "Authorization: Bearer $BAXPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Where clients plug in

Payment links — pass clientId at creation to group charges per customer; it's echoed in the payment_link.paid webhook.
E-invoicing — pass clientId instead of the inline buyer block; the client's SIREN, VAT id and address fill the invoice (inline fields override per invoice).