GET/api/v1/checkout/pay/:sessionIdPublic

Afficher le checkout hébergé

Retourne les données publiques d'une session checkout : montant, branding, méthodes autorisées et champs personnalisés. Appelé par la page checkout avant le paiement.

Paramètres de chemin

Nom	Type	Requis	Description
sessionId	string	Oui	Identifiant de session (préfixe cs_)

Réponse (data)

Nom	Type	Requis	Description
sessionId	string	Oui	Identifiant de la session
status	string	Oui	OPEN, SUCCEEDED, FAILED, EXPIRED, etc.
amount	string	Oui	Montant en unités mineures (ex. centimes)
currency	string	Oui	Code ISO 4217
title	string	Oui	Titre affiché au payeur
description	string \| null	—	Description optionnelle
allowedMethods	WALLET \| MOBILE_MONEY \| CARD \| BANK_TRANSFER \| QR	Oui	Méthodes affichées au payeur : intersection entre allowedMethods de la session (intention marchand), les règles de routage tenant, et — pour INTERNAL (CARD / Mobile Money) — la capacité du sous-tenant processeur à router le paiement
merchantName	string \| null	—	Nom affiché du marchand
expiresAt	string \| null	—	Date d'expiration ISO 8601
failureCode	string \| null	—	Code d'échec IZZIPAY normalisé (ex. INSUFFICIENT_FUNDS) si status = FAILED
failureMessage	string \| null	—	Message d'échec lisible pour le payeur si status = FAILED

Exemple réponse

json

{
  "success": true,
  "data": {
    "sessionId": "cs_38b62a204d2da0bcdd312c59",
    "status": "OPEN",
    "amount": "2500",
    "currency": "USD",
    "title": "Commande #1234",
    "description": "Achat boutique en ligne",
    "merchantName": "Merchant Shop SARL",
    "merchantLogo": "https://cdn.example/logo.png",
    "allowedMethods": [
      "WALLET",
      "MOBILE_MONEY",
      "CARD",
      "BANK_TRANSFER",
      "QR"
    ],
    "locale": "fr",
    "expiresAt": "2026-08-28T12:00:00.000Z",
    "branding": {
      "primaryColor": "#43A047"
    },
    "customFields": [],
    "successMessage": "Merci pour votre paiement !"
  },
  "error": null
}

Erreurs

CHECKOUT_SESSION_EXPIRED (409) — La session checkout a expiré
CHECKOUT_NO_PAYMENT_METHODS (409) — Aucune méthode de paiement n'est routable pour cette session (devise, montant ou configuration provider)
CHECKOUT_SESSION_ALREADY_COMPLETED (409) — La session est déjà terminée

Exemples

bash

curl -X GET https://api.dev.izzi-finance.com/api/v1/api/v1/checkout/pay/:sessionId \
  -H "Content-Type: application/json"

Voir aussi

POST/api/v1/checkout/pay/:sessionId/completePublic

Compléter un paiement checkout

Finalise le paiement pour une session ouverte. Header optionnel Idempotency-Key (sinon clé dérivée automatiquement). Crée un payment intent financial-core, une charge marchand et déclenche les webhooks payment.succeeded en cas de succès.

Paramètres de chemin

Nom	Type	Requis	Description
sessionId	string	Oui	Identifiant de session checkout

Corps de requête

Nom	Type	Requis	Description
paymentMethod	WALLET \| MOBILE_MONEY \| CARD \| BANK_TRANSFER \| QR	Oui	Méthode de paiement sélectionnée
paymentDetails	object	Oui	MOBILE_MONEY : phone/phoneNumber, operator?, countryCode?. CARD : cardNumber, cardExpiry, cardCvc. WALLET : walletId. QR/BANK_TRANSFER : selon provider.
customerInfo	object	—	Métadonnées client optionnelles

Corps commun à toutes les méthodes. Les champs de paymentDetails varient selon paymentMethod.

Exemple requête

json

{
  "paymentMethod": "MOBILE_MONEY",
  "paymentDetails": {
    "phone": "+243900000000",
    "operator": "ORANGE",
    "countryCode": "CD"
  }
}

Réponse (data)

Nom	Type	Requis	Description
sessionId	string	Oui	Session traitée
status	string	Oui	SUCCEEDED, PROCESSING ou FAILED
paymentIntentId	string \| null	—	UUID du payment intent financial-core (créé puis confirmé)
chargeId	string \| null	—	Charge marchand créée en cas de succès
providerCode	string \| null	—	Provider utilisé (INTERNAL, STRIPE, FLUTTERWAVE, etc.)
providerRef	string \| null	—	Référence externe du provider
nextAction	POLL \| REDIRECT \| DISPLAY_QR	—	POLL, REDIRECT ou DISPLAY_QR
actionUrl	string \| null	—	URL de redirection (CARD, 3DS)
qrPayload	string \| null	—	Payload QR si nextAction = DISPLAY_QR
pollAfterMs	number	—	Délai recommandé avant GET /status
instructions	string \| null	—	Instructions affichées au payeur
redirectUrl	string \| null	—	URL de redirection enrichie : successUrl (SUCCEEDED) ou cancelUrl (FAILED/CANCELLED) avec session_id, charge_id, amount, currency et status en query params

Exemples réponse

json

{
  "success": true,
  "data": {
    "sessionId": "cs_38b62a204d2da0bcdd312c59",
    "status": "SUCCEEDED",
    "redirectUrl": "https://merchant.example/success?session_id=cs_38b62a204d2da0bcdd312c59&amount=2500&currency=USD&status=SUCCEEDED&charge_id=a76c830e-b7f1-4fd4-b5b6-618ffdb76b62",
    "paymentIntentId": "b04cb5ed-3e0b-446a-b3cd-8ef2e2836b8d",
    "chargeId": "a76c830e-b7f1-4fd4-b5b6-618ffdb76b62",
    "providerCode": "INTERNAL",
    "providerRef": "internal_ref_001",
    "nextAction": "POLL",
    "actionUrl": null,
    "instructions": null,
    "qrPayload": null
  },
  "error": null
}

Erreurs

CHECKOUT_SESSION_EXPIRED (409) — La session checkout a expiré
CHECKOUT_SESSION_NOT_OPEN (409) — La session n'est plus payable (déjà payée, annulée ou fermée)
PAYMENT_METHOD_NOT_ALLOWED (409) — La méthode demandée n'est pas disponible pour cette session checkout
INVALID_PAYMENT_DETAILS (400) — paymentDetails invalides pour la méthode choisie
RISK_BLOCKED (409) — Paiement bloqué par l'évaluation de risque
PAYMENT_FAILED (409) — Échec de finalisation (intent ou provider)
PAYMENT_PROVIDER_NOT_AVAILABLE (409) — Aucun provider disponible pour cette méthode et devise

Exemples

bash

curl -X POST https://api.dev.izzi-finance.com/api/v1/api/v1/checkout/pay/:sessionId/complete \
  -H "Content-Type: application/json" \
  -d '{
  "paymentMethod": "MOBILE_MONEY",
  "paymentDetails": {
    "phone": "+243900000000",
    "operator": "ORANGE",
    "countryCode": "CD"
  }
}'

Voir aussi

GET/api/v1/checkout/pay/:sessionId/statusPublic

Statut d'une session checkout

Polling du statut après un paiement asynchrone ou lorsque nextAction = POLL.

Paramètres de chemin

Nom	Type	Requis	Description
sessionId	string	Oui	Identifiant de session

Réponse (data)

Nom	Type	Requis	Description
status	string	Oui	Statut courant de la session
paymentIntentId	string \| null	—	Intent lié une fois le paiement initié
chargeId	string \| null	—	Charge créée si SUCCEEDED
failureCode	string \| null	—	Code d'échec IZZIPAY normalisé (ex. INSUFFICIENT_FUNDS) si status = FAILED
failureMessage	string \| null	—	Message d'échec lisible pour le payeur
redirectUrl	string \| null	—	URL enrichie : successUrl si SUCCEEDED, cancelUrl si FAILED ou CANCELLED (query params session_id, charge_id, amount, currency, status)

Exemple réponse

json

{
  "success": true,
  "data": {
    "sessionId": "cs_38b62a204d2da0bcdd312c59",
    "status": "FAILED",
    "failureCode": "INSUFFICIENT_FUNDS",
    "failureMessage": "Votre compte mobile money n'a pas assez de fonds pour ce paiement.",
    "completedAt": null
  }
}

Exemples

bash

curl -X GET https://api.dev.izzi-finance.com/api/v1/api/v1/checkout/pay/:sessionId/status \
  -H "Content-Type: application/json"

Voir aussi

POST/api/v1/checkout/pay/:sessionId/confirmPublic

Confirmer un paiement asynchrone

Confirme un paiement QR en attente. Réservé aux sessions PROCESSING avec paymentMethod QR — ne crée pas de charge immédiatement.

Paramètres de chemin

Nom	Type	Requis	Description
sessionId	string	Oui	Identifiant de session

Réponse (data)

Nom	Type	Requis	Description
sessionId	string	Oui	Session traitée
status	string	Oui	PROCESSING (confirmation QR en cours)

Exemple réponse

json

{
  "success": true,
  "data": {
    "sessionId": "cs_38b62a204d2da0bcdd312c59",
    "status": "PROCESSING"
  },
  "error": null
}

Erreurs

SESSION_NOT_PROCESSING (409) — La session n'attend pas de confirmation
CONFIRM_NOT_SUPPORTED (409) — Confirmation manuelle non supportée pour cette méthode
PAYMENT_NOT_FOUND (409) — Aucun paiement en attente pour cette session
CONFIRM_FAILED (409) — La confirmation du paiement a échoué

Exemples

bash

curl -X POST https://api.dev.izzi-finance.com/api/v1/api/v1/checkout/pay/:sessionId/confirm \
  -H "Content-Type: application/json"

Voir aussi

POST/api/v1/checkout/pay/:sessionId/select-methodPublic

Sélectionner une méthode de paiement

Enregistre la méthode choisie avant l'appel /complete (flux en deux étapes).

Paramètres de chemin

Nom	Type	Requis	Description
sessionId	string	Oui	Identifiant de session

Corps de requête

Nom	Type	Requis	Description
method	WALLET \| MOBILE_MONEY \| CARD \| BANK_TRANSFER \| QR	Oui	Méthode sélectionnée
details	object	—	Détails préliminaires optionnels

Exemple requête

json

{
  "method": "MOBILE_MONEY",
  "details": {
    "phone": "+243900000000"
  }
}

Réponse (data)

Nom	Type	Requis	Description
sessionId	string	Oui	Session mise à jour
status	string	Oui	PAYMENT_METHOD_SELECTED
method	string	Oui	Méthode enregistrée

Exemple réponse

json

{
  "success": true,
  "data": {
    "sessionId": "cs_38b62a204d2da0bcdd312c59",
    "status": "PAYMENT_METHOD_SELECTED",
    "method": "MOBILE_MONEY"
  }
}

Exemples

bash

curl -X POST https://api.dev.izzi-finance.com/api/v1/api/v1/checkout/pay/:sessionId/select-method \
  -H "Content-Type: application/json" \
  -d '{
  "method": "MOBILE_MONEY",
  "details": {
    "phone": "+243900000000"
  }
}'

Voir aussi

GET/api/v1/checkout/links/:slug/openPublic

Ouvrir un lien de paiement

Endpoint public qui résout un slug de lien de paiement et retourne une session checkout enfant.

Paramètres de chemin

Nom	Type	Requis	Description
slug	string	Oui	Slug du lien de paiement

Réponse (data)

Nom	Type	Requis	Description
sessionId	string	Oui	Session checkout créée ou réutilisée
url	string	Oui	URL hébergée vers la session enfant
linkUrl	string	Oui	URL publique du lien de paiement
slug	string	Oui	Slug du lien

Exemple réponse

json

{
  "success": true,
  "data": {
    "sessionId": "cs_child_abc123",
    "url": "https://checkout.example/session/cs_child_abc123",
    "linkUrl": "https://checkout.example/link/summer-sale",
    "slug": "summer-sale"
  },
  "error": null
}

Erreurs

PAYMENT_LINK_NOT_FOUND (404) — Lien de paiement introuvable
PAYMENT_LINK_USE_LINK_ROUTE (409) — Ouvrir ce lien via /checkout/links/:slug/open
PAYMENT_LINK_EXPIRED (409) — Le lien de paiement a expiré
PAYMENT_LINK_MAX_USES_REACHED (409) — Nombre maximum d'utilisations atteint
PAYMENT_LINK_NOT_ACTIVE (409) — Le lien de paiement n'est plus actif

Exemples

bash

curl -X GET https://api.dev.izzi-finance.com/api/v1/api/v1/checkout/links/:slug/open \
  -H "Content-Type: application/json"