Pré-autorisation

Ce que Nirio appelle sur votre serveur avant d'encaisser une facture, et comment y répondre.

Activation par produit

La pré-autorisation n'est active que pour les produits qui la demandent. Elle est configurée par Nirio avec l'URL de rappel, le mode d'authentification et le secret de signature de votre produit.

Avant d'encaisser un paiement, Nirio appelle votre serveur pour vérifier que la facture peut être réglée. Vous répondez « autorisé » ou « refusé ». Nirio n'encaisse que si vous autorisez.

Ce sens est l'inverse de l'API : c'est Nirio qui appelle votre serveur, sur l'URL de rappel configurée pour votre produit.

Appel reçu par votre serveur

POST {votre authorizationCallbackUrl}
Authorization: Bearer <accessToken>
x-nirio-signature: <hmac-sha256 hex du corps>
x-nirio-authorization-id: <authorizationId>
Content-Type: application/json

Authorization : jeton obtenu par Nirio auprès de votre serveur d'autorisation, selon le mode du produit (voir Authentification). En OAuth2 + mTLS, Nirio présente aussi son certificat client.
x-nirio-signature : HMAC-SHA256 en hexadécimal, calculé sur le corps brut de la requête avec le secret partagé de votre produit. Vérifiez-la avant de traiter la requête.
x-nirio-authorization-id : identifiant de la demande d'autorisation, identique à authorizationId du corps. Utilisez-le pour rapprocher vos journaux.

Corps de la requête

Exemple

{
  "id": "evt_01",
  "authorizationId": "auth_01",
  "occurredAt": "2026-11-02T10:15:00+01:00",
  "data": {
    "invoice": {
      "id": "7f1c2d3e-0000-4000-8000-000000000001",
      "productId": "prod_01",
      "partnerInvoiceReference": "CMD-2026-0042",
      "status": "OPEN",
      "amount": {"value": 1500, "currency": "EUR"},
      "customer": {"...": "identité du client, selon son type"},
      "qrCode": {
        "format": "datamatrix",
        "content": "...",
        "expiresAt": "2026-11-09T10:15:00+01:00"
      }
    },
    "paymentAttempt": {
      "id": "3b9e8a10-0000-4000-8000-000000000002",
      "terminalId": "T-0001",
      "paymentMethod": "CASH",
      "amount": {"value": 1500, "currency": "EUR"},
      "initiatedAt": "2026-11-02T10:15:00+01:00",
      "expiresAt": "2026-11-02T10:20:00+01:00"
    }
  }
}

amount.value est un entier. currency vaut EUR ou XPF.
paymentAttempt.amount ne dépasse jamais le montant de la facture et utilise la même devise. Il peut couvrir la totalité de la facture ou une seule échéance.
paymentMethod vaut CASH ou BANK_CARD.

Réponses attendues

Réponse de votre serveur	Décision Nirio	Ce que voit le client
`200`	Autorisé	Le paiement se poursuit
`400` avec un corps `{"reason": "..."}`	Refusé, motif précis	Le paiement est refusé avec ce motif
Autre statut, erreur ou délai dépassé	Refusé, motif générique	Le paiement est refusé

Le délai de réponse maximal est de 45 secondes. Au-delà, la demande est considérée comme refusée.

Motifs de refus (`reason`)

Motif	Quand l'utiliser
`AMOUNT_INCORRECT`	Le montant ne correspond pas à la facture.
`BILL_ALREADY_SETTLED`	La facture a déjà été réglée.
`BILL_DELETED_FROM_APP`	La facture n'existe plus dans votre système.
`BILL_EXPIRED`	L'échéance de la facture est dépassée.
`PAYER_ACCOUNT_KO`	Le compte du payeur ne permet pas le paiement.
`PARTNER_PAYABLE_NOT_OPEN`	Votre système ne considère pas la facture comme ouverte.
`QR_UNRECOGNIZED`	Le QR code n'est pas reconnu par votre système.

Réponse de refus

{"reason": "BILL_ALREADY_SETTLED", "message": "Facture déjà réglée"}

message est facultatif et limité à 140 caractères.

Bonnes pratiques

Vérifiez toujours la signature avant tout traitement. Rejetez la requête si elle ne correspond pas.
Répondez vite. Le délai maximal est de 45 secondes pour l'ensemble de l'appel.
Utilisez authorizationId pour rapprocher la demande de vos propres journaux.