Créer une facture

POST /v3/products/{productId}/invoices — émettre une facture payable en espèces.

POST /v3/products/{productId}/invoices
Authorization: Bearer <token>
Content-Type: application/json

Crée une facture OPEN pour le produit productId et renvoie son QR code.

Requête

Champ	Type	Requis	Description
`partnerInvoiceReference`	chaîne	oui	Référence partenaire, 1 à 64 caractères `[A-Za-z0-9._:-]`. Clé d'idempotence unique pour tout le partenaire.
`amount`	objet	oui	Montant `{ value, currency }`.
`customer`	objet	oui	Client payeur, identité complète ou `{ externalId }` seul (voir ci-dessous).
`expiresAt`	date	non	Échéance ISO 8601 avec décalage. Défaut : maintenant + 1 h. Doit être dans le futur.

Client payeur

{
  "externalId": "CUST-987",
  "personType": "NATURAL",
  "firstName": "Jean",
  "lastName": "Dupont",
  "birthDate": "1980-01-01",
  "birthPlace": "Paris",
  "residenceCountryCode": "FR"
}

externalId est l'identifiant du client dans le système du partenaire ; residenceCountryCode est un code pays ISO 3166-1 alpha-2.

Exemple

curl -X POST $API_BASE_URL/v3/products/$PRODUCT_ID/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "partnerInvoiceReference": "INV-2025-0001",
    "amount": { "value": 2500, "currency": "EUR" },
    "customer": { "externalId": "CUST-987" },
    "expiresAt": "2025-03-02T18:00:00+01:00"
  }'

Réponses

Statut	Signification
`201`	Facture créée.
`200`	Rejeu idempotent : la facture existante portant cette référence est renvoyée.

201 Created

{
  "id": "0f8b7a3e-6c2d-4b1a-9e8f-5d4c3b2a1f0e",
  "productId": "2f8a9d1e-1c4b-4f37-9a55-6c0a9d3f1b02",
  "partnerInvoiceReference": "INV-2025-0001",
  "status": "OPEN",
  "amount": { "value": 2500, "currency": "EUR" },
  "customer": { "externalId": "CUST-987" },
  "createdAt": "2025-03-01T10:15:00.000Z",
  "paidAt": null,
  "cancelledAt": null,
  "qrCode": {
    "format": "datamatrix",
    "content": "8d6c1f0e-1d0b-4f8e-9f5a-3c1e2b4d5a6f;5d41402abc4b2a76b9719d911017c592",
    "expiresAt": "2025-03-02T17:00:00.000Z"
  }
}

Contrôles effectués

Les contrôles sont appliqués dans cet ordre ; le premier en échec détermine l'erreur.

Produit — il existe et appartient au partenaire (404 PRODUCT_NOT_FOUND), et il est actif (422 PRODUCT_NOT_AVAILABLE).

Montant — compris entre le minimum (au moins 1) et le maximum du produit (422 AMOUNT_BELOW_MINIMUM, 422 AMOUNT_ABOVE_MAXIMUM).

Idempotence — si la référence existe déjà, rejeu (200) ou conflit (409 REFERENCE_ALREADY_EXISTS), voir ci-dessous.

Client — résolution du client payeur (voir ci-dessous).

Échéance — expiresAt dans le futur (422 INVOICE_EXPIRED).

Frais et émission — calcul des frais de service (500 SERVICE_FEE_UNAVAILABLE), puis création de la facture et de son QR code.

Idempotence

Lorsqu'une facture existe déjà avec la même partnerInvoiceReference (pour le partenaire, quel que soit le produit), la requête est comparée à la facture existante :

productId, amount.value, amount.currency ;
expiresAt, uniquement s'il est fourni dans la requête ;
le client : identité complète comparée champ à champ, ou seulement externalId si la requête ne contient que { externalId }.

Si tout correspond, la facture existante est renvoyée avec 200 OK (quel que soit son statut). Sinon : 409 REFERENCE_ALREADY_EXISTS. Deux créations simultanées avec la même référence sont résolues de la même manière : une seule facture est créée.

Résolution du client

Si le partenaire est configuré en KYC délégué, le client est créé ou mis à jour à la volée à partir de l'identité transmise :

Code	Statut	Cause
`CUSTOMER_IDENTITY_REQUIRED`	`422`	Client inconnu (ou création précédente inachevée) et seul `externalId` est fourni.
`CUSTOMER_TYPE_CHANGED`	`422`	`personType` différent de celui du client existant.
`CREATION_ALREADY_IN_PROGRESS`	`409`	Création du même client en cours ; réessayez après quelques secondes.
`CUSTOMER_PROVISIONING_FAILED`	`500`	Échec de la création du client côté Nirio.

Erreurs

Statut	Codes
`400`	`INVALID_REQUEST`
`401`	`MISSING_PARTNER_ID`
`404`	`PRODUCT_NOT_FOUND`, `CUSTOMER_NOT_FOUND`
`409`	`REFERENCE_ALREADY_EXISTS`, `INVOICE_ALREADY_PAID`, `CREATION_ALREADY_IN_PROGRESS`
`422`	`PRODUCT_NOT_AVAILABLE`, `AMOUNT_BELOW_MINIMUM`, `AMOUNT_ABOVE_MAXIMUM`, `AMOUNT_MISMATCH`, `CUSTOMER_NOT_ONBOARDED`, `CUSTOMER_TYPE_CHANGED`, `CUSTOMER_IDENTITY_REQUIRED`, `INVOICE_EXPIRED`
`500`	`SERVICE_FEE_UNAVAILABLE`, `CUSTOMER_PROVISIONING_FAILED`

AMOUNT_MISMATCH et INVOICE_ALREADY_PAID protègent contre des accès concurrents sur la même référence ; ils ne devraient pas apparaître en usage normal. Détails dans le catalogue des erreurs.

Créer une facture

On this page