API - Checkout

Le checkout est le point d'entrée du paiement : vous le créez côté serveur, nous vous renvoyons une URL vers laquelle rediriger votre client.

Les conventions générales (en-têtes, enveloppe de réponse, codes d'erreur) s'appliquent.

Créer un checkout

POST /api/public/v1/pay/create-checkout

Paramètres

Champ	Type	Obligatoire	Description
amount	entier	Oui	Montant en ariary. Entre 300 et 20 000 000, sans décimale.
comment	string	Oui	Motif affiché au client. 100 caractères maximum.
wallet_id	uuid	Oui	Portefeuille virtuel destinataire, appartenant à votre compte.
company	string	Oui	Nom affiché sur la page de paiement.
return_urls.return_to_merchant_url	url	Oui	URL de retour vers votre site après le paiement.

Exemple

curl --request POST \
    "https://efn.efaina.com/api/public/v1/pay/create-checkout" \
    --header "Authorization: Bearer VOTRE_TOKEN" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data '{
      "amount": 125000,
      "comment": "Facture INV-2024-001",
      "wallet_id": "a3bb189e-b1be-49d4-aec2-a9b02d7a5c20",
      "company": "MyCompany SARL",
      "return_urls": {
        "return_to_merchant_url": "https://merchant.example.com/payment/callback"
      }
    }'

Réponse 201

{
  "statusHttp": "success",
  "message": "Success",
  "response": {
    "status": "success",
    "checkout_url": "https://pay.example.com/checkout?token=eyJ0b2tlbiI6...",
    "transaction": "72b46ff8-1bc2-4a33-bc63-022eb743a4a5"
  }
}

• checkout_url : redirigez votre client vers cette URL.
• transaction : identifiant de la transaction. Le checkout et sa transaction partagent le même identifiant — c'est celui que vous retrouverez dans les webhooks et sur GET /details-transaction/{transaction}.

Enregistrez cet identifiant de votre côté dès la création : c'est votre clé de rapprochement quand la notification arrivera.

Erreurs spécifiques

Code	Cas
404 NOT_FOUND_DATA	Le wallet_id n'existe pas.
403 UNAUTHORIZED	Le portefeuille appartient à un autre compte.
422 PAYLOAD_VALIDATION	Montant hors bornes, commentaire trop long, URL de retour manquante.
500 SERVER_ERROR	Aucun moyen de paiement ne peut traiter ce montant.

Durée de validité

Le lien de checkout expire une heure après sa création. Passé ce délai, générez-en un nouveau : un lien expiré ne peut pas être réactivé.

Après la redirection

Le client choisit son moyen de paiement sur notre page, puis revient sur votre return_to_merchant_url.

Le retour du client ne prouve pas le paiement

Le retour navigateur peut survenir avant la confirmation de l'opérateur, ou ne jamais survenir si le client ferme son onglet. Attendez l'évènement checkout.completed / transaction.completed, ou interrogez GET /details-transaction/{transaction}, avant de livrer la commande.

Référence complète

Schémas de requête et de réponse détaillés : référence API générée.