Modifications de paiement

Les modifications permettent d'opérer sur des paiements déjà finalisés (en ligne comme POS). Tous les endpoints de modification renvoient HTTP 202 Accepted car l'opération est traitée de manière asynchrone par le processeur de paiement.

Session vs paiement : rappel important

Les modifications ne s'appliquent pas à la session (sessionId), mais au paiement (paymentReference). La session est le conteneur créé par POST /payment/session ; le paiement est la transaction réelle créée lorsque le client paie avec succès. Une fois la session terminée, elle ne change plus : ce qui compte ensuite, c'est le paiement.

Pour plus de détails sur cette distinction, voir Session vs paiement.

Comment obtenir le paymentReference

Toutes les modifications nécessitent un paymentReference qui identifie le paiement réel :

• Pour les paiements en ligne : consultez la session avec GET /payment/session/{sessionId}. Lorsque la session est completed, le champ paymentReference contient la référence du paiement autorisé
• Pour les paiements POS : c'est le paymentReference renvoyé directement dans la réponse de POST /pos/payment (identique au posPaymentId)

Les deux types de référence fonctionnent indifféremment sur tous les endpoints de modification.

---

Remboursement (Refund)

Rembourse totalement ou partiellement le montant d'un paiement finalisé.

Live: POST https://aviratopayments.com/external/v1/payment/refund
Test: POST https://aviratopayments.com/external/v1/test/payment/refund

Paramètres du body

Valeurs autorisées pour reason

Important : Les valeurs sont sensibles à la casse et incluent un espace dans CUSTOMER REQUEST. Envoyer customer request ou Customer Request produira une erreur 400.

Exemple

curl -X POST https://aviratopayments.com/external/v1/payment/refund \
  -H "X-API-KEY: votre_cle_api_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-12345" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "reason": "CUSTOMER REQUEST"
  }'

Réponse (202)

{
  "success": true,
  "data": {
    "refundReference": "SHOP01-RFX-17195234567890",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "status": "pending",
    "createdAt": "2026-06-29 14:00:00"
  }
}

Le refundReference (format {webcode}-RFX-{timestamp} en Live, {webcode}-RFXT-{timestamp} en Test) identifie cette opération de remboursement. Utilisez-le pour le suivi dans la liste des modifications.

Remboursement partiel vs total

Vous pouvez rembourser tout montant inférieur ou égal au montant d'origine du paiement. Pour plusieurs remboursements partiels sur le même paiement, la somme totale ne doit pas dépasser le montant d'origine.

---

Capture (Capture)

Capture totalement ou partiellement une préautorisation (paiement créé avec isPreAuth: true).

Live: POST https://aviratopayments.com/external/v1/payment/capture
Test: POST https://aviratopayments.com/external/v1/test/payment/capture

Paramètres du body

Exemple

curl -X POST https://aviratopayments.com/external/v1/payment/capture \
  -H "X-API-KEY: votre_cle_api_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: capture-preauth-67890" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    }
  }'

Réponse (202)

{
  "success": true,
  "data": {
    "captureReference": "SHOP01-CTX-17195345678901",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "status": "received",
    "createdAt": "2026-06-29 15:00:00"
  }
}

Le captureReference (format {webcode}-CTX-{timestamp} en Live, {webcode}-CTXT-{timestamp} en Test) identifie cette opération de capture.

Capture partielle

Si vous avez préautorisé 500 EUR mais que le montant final du service est de 450 EUR, vous pouvez capturer seulement 45000 centimes. La différence est libérée automatiquement.

Capture excédentaire

Si vous tentez de capturer un montant supérieur au montant préautorisé, la requête est acceptée (HTTP 202) mais le processeur rejettera l'opération. Vous recevrez un webhook avec result: "failure" indiquant que le montant dépasse l'autorisation.

---

Annulation (Cancel)

Annule une préautorisation avant sa capture. Libère les fonds retenus sur la carte du client.

Live: POST https://aviratopayments.com/external/v1/payment/cancel
Test: POST https://aviratopayments.com/external/v1/test/payment/cancel

Paramètres du body

Exemple

curl -X POST https://aviratopayments.com/external/v1/payment/cancel \
  -H "X-API-KEY: votre_cle_api_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel-preauth-11111" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789"
  }'

Réponse (202)

{
  "success": true,
  "data": {
    "cancelReference": "SHOP01-CAX-17195456789012",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "status": "received",
    "createdAt": "2026-06-29 16:00:00"
  }
}

Le cancelReference (format {webcode}-CAX-{timestamp} en Live, {webcode}-CAXT-{timestamp} en Test) identifie cette opération d'annulation.

---

Extension (Extend)

Prolonge le délai d'une préautorisation avant son expiration. Les préautorisations ont une validité limitée (en général 7 à 28 jours selon la banque émettrice). Si vous avez besoin de plus de temps, vous pouvez la prolonger. L'extension ajoute 28 jours supplémentaires à compter du moment de la demande.

Live: POST https://aviratopayments.com/external/v1/payment/extend
Test: POST https://aviratopayments.com/external/v1/test/payment/extend

Paramètres du body

Il n'est pas nécessaire d'envoyer montant ni devise : l'extension conserve le montant d'origine.

Exemple

curl -X POST https://aviratopayments.com/external/v1/payment/extend \
  -H "X-API-KEY: votre_cle_api_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: extend-preauth-22222" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789"
  }'

Réponse (202)

{
  "success": true,
  "data": {
    "updateReference": "SHOP01-UPX-17195567890123",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "status": "received",
    "createdAt": "2026-06-29 17:00:00"
  }
}

Le updateReference (format {webcode}-UPX-{timestamp} en Live, {webcode}-UPXT-{timestamp} en Test) identifie cette opération d'extension. Le amount renvoyé est le montant d'origine du paiement.

---

État des modifications

Les modifications sont traitées de manière asynchrone. L'état renvoyé dans la réponse initiale dépend de l'opération et évolue lorsque le processeur confirme :

Note sur les états initiaux : Les remboursements renvoient pending car le traitement peut prendre du temps. Capture, cancel et extend renvoient received car la confirmation du processeur est plus rapide. Dans les deux cas, l'état final sera success ou failed.

Comment savoir quand une modification est terminée :

1. Webhooks (recommandé) : vous recevrez un webhook automatique lorsque le processeur confirmera l'opération. Voir Webhooks pour le format et des exemples
2. Consultation : vous pouvez consulter l'état mis à jour avec Lister les modifications d'un paiement

---

Modifications en environnement Test

En environnement Test, les modifications sont traitées de manière simulée et immédiate. Aucun processeur réel n'est contacté. Le backend génère un webhook simulé avec le résultat (success ou failed) envoyé à votre URL de webhook en quelques secondes.

Comportement simulé par type

Important : En Test, le webhook de confirmation est généré automatiquement au moment de la requête. En Live, le webhook arrive lorsque le processeur réel confirme l'opération (secondes à minutes).

---

Référence rapide des préfixes

Chaque type de modification génère une référence avec un préfixe identificatif :

Erreurs courantes sur les modifications