API checkout-hosted : Izzi Pay | Portail marchand izzi-pay

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 chaîne : centimes pour USD (ex. 2500 = 25,00 USD), francs entiers pour CDF (ex. 5000 = 5 000 CDF)
currency	string	Oui	Code ISO 4217
environment	SANDBOX \| PRODUCTION	Oui	SANDBOX ou PRODUCTION: hérité de la clé API à la création. La page hébergée affiche un bandeau en mode test.
title	string	Oui	Titre affiché au payeur
description	string \| null	Non	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	Non	Nom affiché du marchand
expiresAt	string \| null	Non	Date d'expiration ISO 8601
requiresCustomerEmail	boolean	Oui	true si le payeur doit saisir son email avant de payer (session sans customerEmail pré-rempli par le marchand). false si l'email est déjà connu.
failureCode	string \| null	Non	Code d'échec IZZIPAY normalisé (ex. INSUFFICIENT_FUNDS) si status = FAILED
failureMessage	string \| null	Non	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": [],
    "requiresCustomerEmail": true,
    "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.izzi-finance.com/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	Détails du paiement. Le contenu dépend de paymentMethod. Objet vide pour QR et BANK_TRANSFER.
paymentDetails.phone	string	Non	Requis pour MOBILE_MONEY. Numéro international, ex. +243840000000. phoneNumber est accepté comme alias.
paymentDetails.operator	string	Non	Optionnel pour MOBILE_MONEY. Code exact en majuscules. RDC (CD) : MPESA, AIRTEL ou ORANGE. MPESA = Vodacom M-Pesa, n'envoyez pas VODACOM. AFRICELL n'est pas accepté. S'il est omis, IZZIPAY le déduit du numéro. Autres pays : guide Mobile Money.
paymentDetails.countryCode	string	Non	Optionnel pour MOBILE_MONEY. Code ISO alpha-2. S'il est omis, IZZIPAY utilise l'indicatif du numéro, sinon la devise de la session.
paymentDetails.cardNumber	string	Non	Requis pour CARD. 13 à 19 chiffres.
paymentDetails.cardExpiry	string	Non	Requis pour CARD. Format MM/AA, mois de 01 à 12, date non expirée.
paymentDetails.cardCvc	string	Non	Requis pour CARD. 3 ou 4 chiffres.
paymentDetails.walletId	string	Non	Optionnel pour WALLET. UUID du portefeuille du payeur. Le débit se fait ensuite, une fois le payeur connecté. Réponse typique : nextAction AWAIT_WALLET_AUTH.
customerInfo	object	Non	Informations client collectées sur la page checkout. customerInfo.email est obligatoire lorsque GET /checkout/pay/:sessionId renvoie requiresCustomerEmail: true (sauf paiement WALLET connecté).
customerInfo.email	string	Non	Adresse email du payeur pour le reçu et le suivi. Ignorée si la session a déjà un customerEmail.

paymentDetails est toujours un objet. MOBILE_MONEY, CARD et WALLET : voir les champs ci-dessous. QR et BANK_TRANSFER : envoyez {}.

Exemples requête

json

{
  "paymentMethod": "MOBILE_MONEY",
  "paymentDetails": {
    "phone": "+243840000000",
    "operator": "ORANGE",
    "countryCode": "CD"
  },
  "customerInfo": {
    "email": "[email protected]"
  }
}

Réponse (data)

Nom	Type	Requis	Description
sessionId	string	Oui	Session traitée
status	string	Oui	SUCCEEDED, PROCESSING ou FAILED
paymentIntentId	string \| null	Non	UUID du payment intent financial-core (créé puis confirmé)
chargeId	string \| null	Non	Charge marchand créée en cas de succès
providerCode	string \| null	Non	Provider utilisé (INTERNAL, STRIPE, FLUTTERWAVE, etc.)
providerRef	string \| null	Non	Référence externe du provider
nextAction	POLL \| REDIRECT \| DISPLAY_QR \| AWAIT_WALLET_AUTH	Non	POLL, REDIRECT, DISPLAY_QR ou AWAIT_WALLET_AUTH
actionUrl	string \| null	Non	URL de redirection (CARD, 3DS)
qrPayload	string \| null	Non	Payload QR si nextAction = DISPLAY_QR
pollAfterMs	number	Non	Délai recommandé avant GET /status
instructions	string \| null	Non	Instructions affichées au payeur
redirectUrl	string \| null	Non	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.izzi-finance.com/api/v1/checkout/pay/:sessionId/complete \
  -H "Content-Type: application/json" \
  -d '{
  "paymentMethod": "MOBILE_MONEY",
  "paymentDetails": {
    "phone": "+243840000000",
    "operator": "ORANGE",
    "countryCode": "CD"
  },
  "customerInfo": {
    "email": "[email protected]"
  }
}'

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	Non	Intent lié une fois le paiement initié
chargeId	string \| null	Non	Charge créée si SUCCEEDED
failureCode	string \| null	Non	Code d'échec IZZIPAY normalisé (ex. INSUFFICIENT_FUNDS) si status = FAILED
failureMessage	string \| null	Non	Message d'échec lisible pour le payeur
redirectUrl	string \| null	Non	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.izzi-finance.com/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.izzi-finance.com/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	Non	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.izzi-finance.com/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.izzi-finance.com/api/v1/checkout/links/:slug/open \
  -H "Content-Type: application/json"