Transactions externes

Les transactions externes permettent de créer un lien de transaction depuis le tableau de bord marchand ou depuis votre application via l’API. Le client est redirigé vers une page de transaction hébergée par iPayMoney, puis votre système peut suivre le statut de la transaction par API ou par webhook.

Ce service est adapté aux boutiques en ligne, factures, inscriptions, ventes de tickets, dons et intégrations qui veulent éviter de gérer une page de transaction complète.

Note : vous devez disposer d’un compte marchand iPayMoney actif et de vos clés API pour créer des transactions externes.

Aperçu du parcours

1. Votre application crée une transaction externe. Omettez reference pour laisser iPayMoney générer une valeur aléatoire, ou fournissez une référence à forte entropie.
2. iPayMoney retourne une page_url.
3. Vous redirigez le client vers cette URL.
4. Le client choisit le moyen utilisé pour régler la transaction et valide l’opération.
5. Votre application vérifie le statut avec GET /api/v1/external_payments/{reference} ou traite une notification webhook.

Page publique

La page publique est l’interface consultée par le client. Elle affiche le marchand, le titre de la transaction, le montant, la description et le formulaire de transaction.

Page marchand

Depuis le tableau de bord, le marchand peut consulter le détail de la transaction externe, copier le lien public et suivre les transactions associées.

Créer un lien depuis le tableau de bord

Dans le menu marchand, ouvrez Transaction externe, puis cliquez sur Nouveau.

Renseignez ensuite :

Champ	Description
Titre	Nom affiché sur la page de transaction. Exemple : Facture 2026-001.
Description	Information visible par le client. Exemple : Transaction de la facture du mois de juin.
Montant	Montant à régler. Le montant minimum est 50.
Expiration	Si activée, le lien expire automatiquement après la durée configurée par iPayMoney.
URL de succès	URL HTTPS vers laquelle le client est redirigé après une transaction réussie.
URL d’échec	URL HTTPS vers laquelle le client est redirigé après une transaction échouée.

Après la création, copiez le lien public et partagez-le avec votre client.

Attention : les URLs de redirection doivent commencer par https:// lorsqu’elles sont renseignées.

Implémentation API

Utilisez l’API lorsque votre application doit créer automatiquement un lien de transaction, par exemple à la validation d’une commande e-commerce.

URL de base

https://<domaine-ipaymoney>/api/v1

En-têtes requis

Content-Type: application/json
Authorization: Bearer <cle_secrete_marchand>
Ipay-Target-Environment: sandbox
Ipay-Payment-Type: external_payment

Pour passer en production, remplacez sandbox par live et utilisez la clé secrète Live du compte marchand.

Attention : la clé secrète doit rester côté serveur. Ne l’exposez jamais dans du JavaScript frontend, une application mobile non sécurisée ou un dépôt public.

Créer une transaction externe

POST /api/v1/external_payments

Corps de la requête

{
  "title": "Commande #1001",
  "description": "Transaction de la commande #1001",
  "amount": 15000,
  "reference": "ep_7f3a9c2e5b8d4f61a0c4e2d9b6f8a103",
  "shouldExpire": true,
  "on_success_redirection_url": "https://votre-site.com/commandes/1001/succes",
  "on_failed_redirection_url": "https://votre-site.com/commandes/1001/echec"
}

Paramètres

Paramètre	Type	Obligatoire	Description
title	string	Oui	Titre affiché sur la page de transaction.
description	string	Non	Description affichée au client.
amount	number	Non	Montant fixe à régler, minimum 50. S’il est omis, le lien accepte un montant saisi lors du paiement.
reference	string	Non	Omettez-la pour laisser iPayMoney générer une valeur aléatoire. Si vous la fournissez, utilisez au moins 128 bits d’entropie et ne réutilisez jamais un numéro de commande séquentiel.
shouldExpire	boolean	Non	La v1 actuelle crée un lien expirant, même si false est envoyé. Utilisez true pour refléter le comportement réel.
on_success_redirection_url	URL	Non	URL HTTPS appelée après une transaction réussie.
on_failed_redirection_url	URL	Non	URL HTTPS appelée après une transaction échouée.

Réponse réussie

{
  "title": "Commande #1001",
  "amount": 15000,
  "reference": "ep_7f3a9c2e5b8d4f61a0c4e2d9b6f8a103",
  "status": "initiated",
  "should_expire": true,
  "page_url": "https://<domaine-ipaymoney>/external_payments/abc123def456/preview"
}

Redirigez ensuite le client vers page_url.

Attention : la consultation GET /api/v1/external_payments/{reference} est actuellement accessible sans clé API et peut retourner le numéro, le nom du client et les données de transaction. Ne publiez jamais la référence et n’utilisez pas une valeur prévisible comme ORDER-1001.

Exemple avec cURL

curl -X POST "https://<domaine-ipaymoney>/api/v1/external_payments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <cle_secrete_marchand>" \
  -H "Ipay-Target-Environment: sandbox" \
  -H "Ipay-Payment-Type: external_payment" \
  -d '{
    "title": "Commande #1001",
    "description": "Transaction de la commande #1001",
    "amount": 15000,
    "reference": "ep_7f3a9c2e5b8d4f61a0c4e2d9b6f8a103",
    "shouldExpire": true,
    "on_success_redirection_url": "https://votre-site.com/commandes/1001/succes",
    "on_failed_redirection_url": "https://votre-site.com/commandes/1001/echec"
  }'

Exemple d’intégration serveur

async function createExternalPayment(order) {
  const response = await fetch("https://<domaine-ipaymoney>/api/v1/external_payments", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.IPAYMONEY_SECRET_KEY}`,
      "Ipay-Target-Environment": process.env.IPAYMONEY_ENVIRONMENT || "sandbox",
      "Ipay-Payment-Type": "external_payment"
    },
    body: JSON.stringify({
      title: `Commande #${order.id}`,
      description: `Transaction de la commande #${order.id}`,
      amount: order.amount,
      reference: order.securePaymentReference,
      shouldExpire: true,
      on_success_redirection_url: `https://votre-site.com/commandes/${order.id}/succes`,
      on_failed_redirection_url: `https://votre-site.com/commandes/${order.id}/echec`
    })
  });

  if (!response.ok) {
    throw new Error(`Erreur iPayMoney: ${response.status}`);
  }

  return response.json();
}

Vérifier le statut d’une transaction

Après la redirection du client, vérifiez le statut côté serveur avec la référence de votre transaction.

GET /api/v1/external_payments/{reference}

Transaction réussie

{
  "reference": "ep_7f3a9c2e5b8d4f61a0c4e2d9b6f8a103",
  "amount": 15000,
  "country": "NE",
  "currency": "XOF",
  "transaction_id": "PROVIDER-TRANSACTION",
  "msisdn": "22796123456",
  "customer_name": "Client Demo",
  "status": "succeeded",
  "created_at": "2026-06-02T10:00:00Z"
}

Transaction non encore effectuée

{
  "message": "No payment details found for this reference",
  "status": "initiated",
  "reference": "ep_7f3a9c2e5b8d4f61a0c4e2d9b6f8a103",
  "page_url": "https://<domaine-ipaymoney>/external_payments/abc123def456/preview"
}

Lien expiré

{
  "message": "This payment link has expired",
  "has_expire": true,
  "status": "cancelled",
  "reference": "ep_7f3a9c2e5b8d4f61a0c4e2d9b6f8a103"
}

Webhooks

Pour éviter d’interroger l’API en continu, configurez un webhook depuis la section Développeurs > Webhooks. Lorsqu’une transaction externe est traitée, le payload peut contenir external_payment_reference, ce qui permet de relier la notification au lien créé.

Conseil : utilisez les webhooks pour mettre à jour automatiquement vos commandes, puis gardez GET /api/v1/external_payments/{reference} comme vérification serveur lorsque l’utilisateur revient sur votre site.

Bonnes pratiques

• Générez une référence privée, aléatoire et unique par commande ou facture.
• Enregistrez la reference et la page_url dans votre base de données.
• Ne créez pas une nouvelle transaction externe à chaque rafraîchissement de page.
• Vérifiez toujours le statut côté serveur avant de marquer une commande comme validée.
• Traitez les notifications webhook de manière idempotente.
• Utilisez l’environnement sandbox pour tester avant de passer en live.