> ## Documentation Index > Fetch the complete documentation index at: https://docs.i-pay.money/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```text theme={null} https:///api/v1 ``` ### En-têtes requis ```http theme={null} Content-Type: application/json Authorization: Bearer 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 ```http theme={null} POST /api/v1/external_payments ``` ### Corps de la requête ```json theme={null} { "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 ```json theme={null} { "title": "Commande #1001", "amount": 15000, "reference": "ep_7f3a9c2e5b8d4f61a0c4e2d9b6f8a103", "status": "initiated", "should_expire": true, "page_url": "https:///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 ```bash theme={null} curl -X POST "https:///api/v1/external_payments" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -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 ```javascript theme={null} async function createExternalPayment(order) { const response = await fetch("https:///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. ```http theme={null} GET /api/v1/external_payments/{reference} ``` ### Transaction réussie ```json theme={null} { "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 ```json theme={null} { "message": "No payment details found for this reference", "status": "initiated", "reference": "ep_7f3a9c2e5b8d4f61a0c4e2d9b6f8a103", "page_url": "https:///external_payments/abc123def456/preview" } ``` ### Lien expiré ```json theme={null} { "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`.