API externe

Documentation développeurs

Intégrez les paiements en ligne et TPE, consultez les opérations et recevez des webhooks via l'API externe Avirato Payments.

Exemples complets

Exemples de flux d'intégration de bout en bout avec cURL. Remplacez la clé API et le webcode par les vôtres.

---

Flux 1 : Paiement en ligne complet (Live)

1.1 Créer une session de paiement

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: votre_cle_api_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 25000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false
  }'

Réponse (201 Created) :

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXT-17195000001234",
    "paymentUrl": "https://aviratopayments.com/pay-external/eyJhbGciOi...",
    "status": "pending",
    "amount": { "value": 25000, "currency": "EUR" },
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false,
    "createdAt": "2026-06-28 10:30:00"
  }
}

1.2 Rediriger le client

Redirigez le client vers la paymentUrl renvoyée. Il verra la page de paiement sécurisée et finalisera la transaction. Après le paiement, il sera redirigé vers urlOk (succès) ou urlKo (échec/annulation).

1.3 Consulter l'état du paiement

Une fois le client redirigé en retour, consultez la session pour obtenir le résultat et le paymentReference :

curl -X GET "https://aviratopayments.com/external/v1/payment/session/SHOP01-EXT-17195000001234?webcode=SHOP01" \
  -H "X-API-KEY: votre_cle_api_live"

Réponse (200 OK) :

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXT-17195000001234",
    "status": "completed",
    "amount": { "value": 25000, "currency": "EUR" },
    "countryCode": "ES",
    "shopperLocale": "es-ES",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false,
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "createdAt": "2026-06-28 10:30:00",
    "paymentReference": "SHOP01-PXT-17195000005678",
    "completedAt": "2026-06-28 10:35:22",
    "paymentStatus": "AUTHORISED",
    "attempts": [
      {
        "paymentReference": "SHOP01-PXT-17195000005678",
        "status": "authorised",
        "createdAt": "2026-06-28 10:34:00"
      }
    ]
  }
}

Le paymentReference (SHOP01-PXT-17195000005678) est celui que vous utiliserez pour toute modification ultérieure.

---

Flux 2 : Préautorisation + capture (ou annulation)

2.1 Créer une préautorisation

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: votre_cle_api_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: preauth-order-67890" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 50000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "description": "Deposito garantia - Servicio #67890",
    "customReference": "ORD-2026-67890",
    "isPreAuth": true
  }'

Le client finalise la préautorisation. Obtenez le paymentReference en consultant la session comme dans le Flux 1.

2.2 Capturer le montant final (partiel)

Lorsque le service est terminé, capturez le montant réel (qui peut être inférieur au montant préautorisé) :

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-order-67890" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195000009876",
    "amount": {
      "value": 45000,
      "currency": "EUR"
    }
  }'

Réponse (202 Accepted) :

{
  "success": true,
  "data": {
    "captureReference": "SHOP01-CTX-17195100001234",
    "paymentReference": "SHOP01-PXT-17195000009876",
    "amount": { "value": 45000, "currency": "EUR" },
    "status": "received",
    "createdAt": "2026-06-29 11:00:00"
  }
}

2.3 (Alternative) Annuler la préautorisation

Si le service est annulé, libérez les fonds :

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-order-67890" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195000009876"
  }'

Réponse (202 Accepted) :

{
  "success": true,
  "data": {
    "cancelReference": "SHOP01-CAX-17195200001234",
    "paymentReference": "SHOP01-PXT-17195000009876",
    "status": "received",
    "createdAt": "2026-06-29 12:00:00"
  }
}

---

Flux 3 : Paiement POS + remboursement (Live)

3.1 Lister les terminaux disponibles

curl -X GET "https://aviratopayments.com/external/v1/pos/terminals?webcode=SHOP01" \
  -H "X-API-KEY: votre_cle_api_live"

Réponse (200 OK) :

{
  "success": true,
  "data": [
    {
      "poiId": "V400m-123456789",
      "status": "boarded",
      "name": "Mostrador Principal",
      "model": "V400m",
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-06-20T08:30:00Z"
    }
  ]
}

3.2 Envoyer un paiement au terminal

curl -X POST https://aviratopayments.com/external/v1/pos/payment \
  -H "X-API-KEY: votre_cle_api_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-sale-11111" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-123456789",
    "amount": {
      "value": 8500,
      "currency": "EUR"
    },
    "description": "Venta mostrador #205",
    "customReference": "VENTA-205-20260628"
  }'

Réponse (200 OK) :

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSX-17195300001234",
    "paymentReference": "SHOP01-POSX-17195300001234",
    "poiId": "V400m-123456789",
    "amount": { "value": 8500, "currency": "EUR" },
    "status": "success",
    "isPreAuth": false,
    "pspReference": "KVGQSN3K2SKFNVNS",
    "description": "Venta mostrador #205",
    "customReference": "VENTA-205-20260628",
    "createdAt": "2026-06-28 14:15:00"
  }
}

3.3 Remboursement partiel du paiement POS

Le paymentReference du paiement POS est le posPaymentId :

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-pos-11111" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-POSX-17195300001234",
    "amount": {
      "value": 2000,
      "currency": "EUR"
    },
    "reason": "CUSTOMER REQUEST"
  }'

Réponse (202 Accepted) :

{
  "success": true,
  "data": {
    "refundReference": "SHOP01-RFX-17195400001234",
    "paymentReference": "SHOP01-POSX-17195300001234",
    "amount": { "value": 2000, "currency": "EUR" },
    "status": "pending",
    "createdAt": "2026-06-28 15:00:00"
  }
}

---

Flux 4 : Lister les paiements avec pagination

4.1 Première page

curl -X GET "https://aviratopayments.com/external/v1/payment/sessions?webcode=SHOP01&status=completed&take=5" \
  -H "X-API-KEY: votre_cle_api_live"

Réponse :

{
  "success": true,
  "data": {
    "payments": [
      {
        "sessionId": "SHOP01-EXT-17195000001234",
        "status": "completed",
        "amount": { "value": 25000, "currency": "EUR" },
        "description": "Pedido #12345",
        "customReference": "ORD-2026-12345",
        "isPreAuth": false,
        "createdAt": "2026-06-28 10:30:00",
        "completedAt": "2026-06-28 10:35:22",
        "paymentReference": "SHOP01-PXT-17195000005678",
        "paymentStatus": "AUTHORISED"
      }
    ],
    "meta": {
      "cursor": "eyJpZCI6NX0=",
      "hasMore": true,
      "total": 23
    }
  }
}

4.2 Page suivante

Utilisez le cursor de la réponse précédente :

curl -X GET "https://aviratopayments.com/external/v1/payment/sessions?webcode=SHOP01&status=completed&take=5&cursor=eyJpZCI6NX0=" \
  -H "X-API-KEY: votre_cle_api_live"

Répétez jusqu'à ce que meta.hasMore soit false.

---

Flux 5 : Vérifier les modifications

5.1 Lister les modifications d'une session en ligne

curl -X GET "https://aviratopayments.com/external/v1/payment/session/SHOP01-EXT-17195000001234/modifications?webcode=SHOP01" \
  -H "X-API-KEY: votre_cle_api_live"

5.2 Lister les modifications d'un paiement POS

curl -X GET "https://aviratopayments.com/external/v1/pos/payment/SHOP01-POSX-17195300001234/modifications?webcode=SHOP01" \
  -H "X-API-KEY: votre_cle_api_live"

5.3 Lister toutes les modifications avec filtres

curl -X GET "https://aviratopayments.com/external/v1/modifications?webcode=SHOP01&type=refund&status=success&take=10" \
  -H "X-API-KEY: votre_cle_api_live"

Réponse (200 OK) :

{
  "success": true,
  "data": {
    "modifications": [
      {
        "operationReference": "SHOP01-RFX-17195400001234",
        "operationType": "refund",
        "paymentReference": "SHOP01-POSX-17195300001234",
        "sessionId": "SHOP01-POSX-17195300001234",
        "status": "success",
        "requestedAt": "2026-06-28 15:00:00",
        "createdAt": "2026-06-28 15:00:00",
        "resolvedAt": "2026-06-28 15:00:05",
        "amount": { "value": 2000, "currency": "EUR" },
        "reason": "CUSTOMER REQUEST"
      }
    ],
    "meta": {
      "cursor": null,
      "hasMore": false,
      "total": 1
    }
  }
}

---

Flux 6 : Paiement en ligne complet en environnement TEST

Ce flux montre comment tester l'intégration sans argent réel.

6.1 Créer une session de paiement (Test)

curl -X POST https://aviratopayments.com/external/v1/test/payment/session \
  -H "X-API-KEY: votre_cle_api_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-order-99999" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 10000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "description": "Test - Pedido #99999",
    "customReference": "TEST-ORD-99999"
  }'

Réponse (201 Created) :

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXTT-17195500001234",
    "paymentUrl": "https://aviratopayments.com/pay-external-test/eyJhbGciOi...",
    "status": "pending",
    "amount": { "value": 10000, "currency": "EUR" },
    "description": "Test - Pedido #99999",
    "customReference": "TEST-ORD-99999",
    "isPreAuth": false,
    "createdAt": "2026-06-28 16:00:00"
  }
}

Notez que le sessionId a le préfixe -EXTT- et que la paymentUrl pointe vers /pay-external-test/.

6.2 Simuler le paiement

Redirigez le client vers la paymentUrl. Il verra un formulaire de paiement simulé. Pour un paiement réussi, saisissez :

  • Numéro : 4111 1111 1111 1111
  • Expiration : 12/30
  • CVC : 737
  • Nom : Test User (tout nom qui n'est pas une valeur spéciale)

Pour simuler un refus, utilisez comme nom du titulaire : DECLINED

6.3 Recevoir le webhook simulé

Immédiatement après la finalisation du paiement, vous recevrez un webhook sur votre URL configurée :

{
  "event_code": "AUTHORISATION",
  "data": {
    "amount": 10000,
    "currency": "EUR",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "paymentStatus": "AUTHORISED",
    "description": "Test - Pedido #99999",
    "customReference": "TEST-ORD-99999",
    "paymentSource": "external_api"
  }
}

6.4 Consulter l'état (Test)

curl -X GET "https://aviratopayments.com/external/v1/test/payment/session/SHOP01-EXTT-17195500001234?webcode=SHOP01" \
  -H "X-API-KEY: votre_cle_api_test"

La réponse aura status: "completed" avec le paymentReference de l'environnement test.

---

Flux 7 : Paiement POS en environnement TEST

7.1 Lister les terminaux simulés

curl -X GET "https://aviratopayments.com/external/v1/test/pos/terminals?webcode=SHOP01" \
  -H "X-API-KEY: votre_cle_api_test"

Réponse (200 OK) :

{
  "success": true,
  "data": [
    {
      "poiId": "V400m-TEST-000001",
      "status": "boarded",
      "name": "Terminal Test 1 - Mostrador",
      "model": "V400m",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    },
    {
      "poiId": "S1F2-TEST-000002",
      "status": "boarded",
      "name": "Terminal Test 2 - Terraza",
      "model": "S1F2",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    },
    {
      "poiId": "P400Plus-TEST-000003",
      "status": "boarded",
      "name": "Terminal Test 3 - Almacen",
      "model": "P400Plus",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    }
  ]
}

Avec syncFromProvider=true, seuls les 2 terminaux online sont renvoyés (V400m-TEST-000001 et S1F2-TEST-000002).

7.2 Paiement réussi (montant ne se terminant pas par 77, 99 ni 55)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: votre_cle_api_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-001" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "description": "Test POS - Venta #001",
    "customReference": "TEST-VENTA-001"
  }'

Réponse (200 OK) - Succès (les deux derniers chiffres de 5000 sont 00) :

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSXT-17195600001234",
    "paymentReference": "SHOP01-POSXT-17195600001234",
    "poiId": "V400m-TEST-000001",
    "amount": { "value": 5000, "currency": "EUR" },
    "status": "success",
    "isPreAuth": false,
    "pspReference": "test_psp_a1b2c3d4e5f67890",
    "description": "Test POS - Venta #001",
    "customReference": "TEST-VENTA-001",
    "createdAt": "2026-06-28 17:00:00"
  }
}

7.3 Paiement refusé (montant se terminant par 77)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: votre_cle_api_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-002" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 10077,
      "currency": "EUR"
    },
    "description": "Test POS - Rechazo simulado"
  }'

Réponse (200 OK) - Refusé :

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSXT-17195600005678",
    "paymentReference": "SHOP01-POSXT-17195600005678",
    "poiId": "V400m-TEST-000001",
    "amount": { "value": 10077, "currency": "EUR" },
    "status": "failed",
    "isPreAuth": false,
    "pspReference": "test_psp_f8e7d6c5b4a39012",
    "errorMessage": "Card declined (test simulation)",
    "description": "Test POS - Rechazo simulado",
    "createdAt": "2026-06-28 17:05:00"
  }
}

7.4 Timeout simulé (montant se terminant par 99)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: votre_cle_api_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-003" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 2599,
      "currency": "EUR"
    },
    "description": "Test POS - Timeout simulado"
  }'

Réponse (200 OK) - Timeout :

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSXT-17195600009012",
    "paymentReference": "SHOP01-POSXT-17195600009012",
    "poiId": "V400m-TEST-000001",
    "amount": { "value": 2599, "currency": "EUR" },
    "status": "timeout",
    "isPreAuth": false,
    "errorMessage": "POS payment timeout. The payment may still be processed asynchronously via webhook.",
    "description": "Test POS - Timeout simulado",
    "createdAt": "2026-06-28 17:10:00"
  }
}

7.5 Terminal offline (erreur 502)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: votre_cle_api_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-004" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "P400Plus-TEST-000003",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "description": "Test POS - Terminal offline"
  }'

Réponse (502) - Erreur de terminal :

{
  "success": false,
  "error": {
    "message": "Error in POS payment response: Reject",
    "code": 13004,
    "statusCode": 502,
    "traceId": "abc123def456..."
  }
}

7.6 Terminal occupé (montant se terminant par 55)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: votre_cle_api_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-005" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 1055,
      "currency": "EUR"
    },
    "description": "Test POS - Terminal ocupado"
  }'

Réponse (409) - Terminal occupé :

{
  "success": false,
  "error": {
    "message": "Terminal busy (test simulation)",
    "code": 13005,
    "statusCode": 409,
    "traceId": "abc123def456..."
  }
}

7.7 poiId non valide (erreur 400)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: votre_cle_api_test" \
  -H "Content-Type: application/json" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "TERMINAL-INVENTADO-123",
    "amount": {
      "value": 1000,
      "currency": "EUR"
    }
  }'

Réponse (400) - Terminal non valide :

{
  "success": false,
  "error": {
    "message": "The specified terminal is not valid: device not found",
    "code": 12001,
    "statusCode": 400,
    "traceId": "abc123def456..."
  }
}

---

Flux 8 : Modification en environnement TEST + webhook

8.1 Remboursement en Test

curl -X POST https://aviratopayments.com/external/v1/test/payment/refund \
  -H "X-API-KEY: votre_cle_api_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-refund-001" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "amount": {
      "value": 3000,
      "currency": "EUR"
    },
    "reason": "CUSTOMER REQUEST"
  }'

Réponse (202 Accepted) :

{
  "success": true,
  "data": {
    "refundReference": "SHOP01-RFXT-17195700001234",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "amount": { "value": 3000, "currency": "EUR" },
    "status": "pending",
    "createdAt": "2026-06-28 18:00:00"
  }
}

8.2 Webhook simulé que vous recevrez

Immédiatement (< 1 seconde), vous recevrez sur votre URL de webhook :

{
  "event_code": "REFUND",
  "data": {
    "amount": 3000,
    "currency": "EUR",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "refundReason": "CUSTOMER REQUEST",
    "refundReference": "SHOP01-RFXT-17195700001234",
    "status": "success",
    "customReference": "TEST-ORD-99999",
    "paymentSource": "external_api"
  }
}

En Test, les webhooks de modification sont générés et envoyés automatiquement après la requête, sans attendre le processeur.