> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fedapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestion des collectes

L'API de FedaPay permet d’intégrer facilement des solutions de paiement sécurisées dans votre site web ou application. Ce guide vous expliquera en détail comment configurer et gérer la collecte de paiements à l’aide de l’API, de la création initiale à la finalisation du processus, en passant par les fonctionnalités avancées comme les paiements sans redirection. Que vous soyez développeur ou responsable de produits, vous trouverez ici tout le nécessaire pour utiliser FedaPay de manière optimale.

### Étapes pour Créer et Gérer une Collecte de Paiement

Les étapes de configuration d’une collecte se divisent en plusieurs processus essentiels.

<Steps>
  <Step title="Initialisation de la Collecte : Création d'une Requête">
    La première étape consiste à envoyer une requête de création de collecte via l’API. Cette requête nécessite certains paramètres obligatoires :

    * **description** : une brève description de l’objet de la collecte

    * **amount** : le montant, toujours en nombre entier

    * **currency** : la devise, indiquée par son numéro ou code ISO (référez-vous au Tableau des Devises FedaPay pour les détails)

    * **callback\_url** : un lien de retour facultatif pour rediriger le client après le paiement

    * **customer** : le client concerné par la collecte

    Si le client n’est pas encore enregistré dans votre système, vous pouvez créer simultanément son profil en ajoutant des informations comme le nom, prénom, email, et numéro de téléphone.

    #### Exemple de requête pour créer une collecte

    <CodeGroup>
      ```java Curl highlight={10,19} theme={null}
        curl -X POST \
        https://sandbox-api.fedapay.com/v1/transactions \
        -H 'Authorization: Bearer TOKEN' \
        -H 'Content-Type: application/json' \
        -d '{
              "description" : "Transaction for john.doe@example.com",
              "amount" : 2000,
              "currency" : {"iso" : "XOF"},
              "callback_url" : "https://maplateforme.com/callback",
              // Si le client n'existe pas encore
              "customer" : {
                  "firstname" : "John",
                  "lastname" : "Doe",
                  "email" : "john.doe@example.com",
                  "phone_number" : {
                      "number" : "+22997808080",
                      "country" : "bj"
                  }
              //Si le client existe déjà
              "customer": { id: 1 }
                }
            }'
      ```

      ```javascript NodeJs highlight={9,18} theme={null}
      const { FedaPay, Transaction } = require('fedapay');
      FedaPay.setApiKey('YOUR_SECRET_API_KEY');
      FedaPay.setEnvironment('sandbox');
      const transaction = await Transaction.create({
        description: 'Payment for order #1234',
        amount: 1000,
        currency: { iso: 'XOF' },
        callback_url: 'https://example.com/callback',
        // Si le client n'existe pas encore
        customer : {
            firstname : "John",
            lastname : "Doe",
            email : "john.doe@example.com",
            phone_number : {
                number : "+22997808080",
                country : "bj"
            }
        //Si le client existe déjà
        customer: { id: 1 }
      });
      ```

      ```php PHP highlight={8,18} theme={null}
      \FedaPay\Fedapay::setApiKey('YOUR_API_KEY');
      \FedaPay\Fedapay::setEnvironment('sandbox');
      $transaction = \FedaPay\Transaction::create([
        'description' => 'Payment for order #1234',
        'amount' => 1000,
        'currency' => ['iso' => 'XOF'],
        'callback_url' => 'https://example.com/callback',
        // Si le client n'existe pas encore
        'customer' => [
            'firstname' => 'John',
            'lastname' => 'Doe',
            'email' => 'john.doe@example.com',
            'phone_number' => [
                'number' => '+22997808080',
                'country' => 'bj'
            ]
        ]
        //Si le client existe déjà
        'customer' => ['id' => 1]
      ]);
      ```

      ```Ruby Ruby highlight={9,19} theme={null}
      require 'fedapay'
      FedaPay.api_key = 'YOUR_SECRET_API_KEY'
      FedaPay.environment = 'sandbox'
      transaction = FedaPay::Transaction.create(
        description: 'Payment for order #1234',
        amount: 1000,
        currency: { iso: 'XOF' },
        callback_url: 'https://example.com/callback',
        #Si le client n'existe pas encore :
        customer: {
          firstname: 'John',
          lastname: 'Doe',
          email: 'john.doe@example.com',
          phone_number: {
            number: '+22997808080',
            country: 'bj'
          }
      }
        #Si le client existe déjà
        customer: { id: 1 },
      )
      puts "Transaction successfully created : #{transaction.inspect}"
      ```
    </CodeGroup>

    <Info>
      [Retrouvez plus d’informations dans notre Reference API](/api-reference/transactions/create)

      Remplacez **YOUR\_SECRETE\_API\_KEY** par votre clé API et utilisez l’URL du serveur approprié (**sandbox** ou **live**).

      Si le client est déjà enregistré, utilisez simplement son ID ou email pour l’associer à la collecte.
    </Info>

    <Warning>
      **Attention :**

      Le paramètre **customer** n’est pas obligatoire. Cependant, lorsque vous créer une transaction avec un customer, assurez-vous que l’adresse email est unique. En effet, FedaPay considère qu’il s’agit du meme customer si les emails sont identique. Si vous envoyer la meme adresse email et que vous renseignez des nom, prénom et numéros de téléphone différents, FedaPay mettra simplement à jour le customer avec les nouvelles informations.
    </Warning>
  </Step>

  <Step title="Génération du Token et du Lien de Paiement">
    Une fois la requête envoyée, l'API renvoie un identifiant unique pour la collecte. Utilisez cet identifiant pour demander un lien et un token de paiement pour rediriger le client vers la page de paiement sécurisée.

    <CodeGroup>
      ```java cURL theme={null}
      curl -X POST \
      https://sandbox-api.fedapay.com/v1/transactions/ID/token \
      -H 'Authorization: Bearer TOKEN' \
      -H 'Content-Type: application/json'
      ```

      ```javaScript NodeJS theme={null}
      const transaction = await Transaction.create({...})
      const token = await transaction.generateToken();
      return redirect(token.url);
      ```

      ```PHP PHP theme={null}
      $transaction = \FedaPay\Transaction::create(array(...))
      $token = $transaction->generateToken();
      return header('Location: ' . $token->url);
      ```

      ```Ruby Ruby theme={null}
      require 'fedapay'
      # Configure FedaPay API credentials
      FedaPay.api_key = 'YOUR_SECRET_API_KEY'
      FedaPay.environment = 'sandbox' # or 'live'
      # Créer une transaction
      transaction = FedaPay::Transaction.create(
      amount: 1000,
      currency: { iso: 'XOF' },
      customer: { id: 1 },
      description: 'Payment for order #1234',
      callback_url: 'https://example.com/callback'
      )
      puts "Transaction successfully created: #{transaction.id}"
      # Générer un token de paiement
      token = transaction.generate_token
      #Afficher le lien sécurisé de paiement
      puts "Redirect user to: #{token.url}"
      ```
    </CodeGroup>

    Le lien ainsi généré peut être utilisé pour rediriger les utilisateurs vers la page de paiement de FedaPay.
  </Step>

  <Step title="Redirection vers la Page de Paiement">
    Ce lien redirige votre client vers une page de paiement sécurisée, où il pourra finaliser la collecte. Si vous avez spécifié un **callback\_url**, votre client sera redirigé automatiquement à l’issue du paiement.
  </Step>

  <Step title="Utilisation du Lien de Retour (Callback URL)">
    Le **callback\_url** permet de rediriger le client vers une page spécifique à la fin du paiement, avec le statut et l'ID de la collecte en paramètres. Par exemple :

    * **Paiement approuvé** : `https://www.monsite.com/?id=258&status=approved`

    * **Paiement annulé** : `https://www.monsite.com/?id=259&status=canceled`

    <Warning>
      **Attention** : Pour des raisons de sécurité, ne vous fiez pas au statut renvoyé par l'URL.
      Effectuez toujours une vérification directe auprès de l’API pour obtenir le statut réel.
    </Warning>
  </Step>

  <Step title="Récupération des Détails d’une Collecte">
    Pour récupérer les informations complètes d’une collecte, effectuez une requête avec l'ID de cette collecte.

    #### Exemple de requête pour récupérer les détails d’une collecte

    <CodeGroup>
      ```java cURL theme={null}
      /*Remplacez YOUR_SECRETE_API_KEY par la clé API secrète de votre compte sandbox ou live. Si vous utilisez votre compte live, vous devez remplacer le lien par https://api.fedapay.com/v1/transactions/ID */

      curl -X GET \
      https://sandbox-api.fedapay.com/v1/transactions/ID \
      -H 'Authorization: Bearer TOKEN' \
      -H 'Content-Type: application/json'
      ```

      ```javascript NodeJs theme={null}
      const { FedaPay, Transaction } = require('fedapay');
      /* Remplacez YOUR_SECRETE_API_KEY par votre véritable clé API */
      FedaPay.setApiKey("YOUR_SECRETE_API_KEY");
      /* Indiquez si vous souhaitez exécuter votre requête en mode test ou en mode live */
      FedaPay.setEnvironment('sandbox'); //or setEnvironment('live');
      /* Afficher les clients */
      const transaction = await Transaction.retrieve(ID, params = {}, headers = {});
      ```

      ```php PHP theme={null}
      \FedaPay\Fedapay::setApiKey(MY_API_KEY);
      $customer = \FedaPay\Transaction::retrieve(ID, params = {}, header = {});
      ```

      ```Ruby Ruby theme={null}
      require 'fedapay';
      # configurer la bibliothèque FedaPay
      FedaPay.api_key = '' # Votre clé API secrète
      FedaPay.environment = '' # sandbox or live
      transactions = FedaPay::Transaction.retrieve(ID);
      ```
    </CodeGroup>

    <Info>[Retrouvez plus d’informations dans notre Reference API](/api-reference/transactions/get-by-id)</Info>
  </Step>
</Steps>

### Paiements sans Redirection

Pour offrir une expérience fluide sans redirection, vous pouvez intégrer directement le formulaire de paiement dans votre application pour certaines méthodes spécifiques (MTN Bénin, Moov Bénin, Moov Togo, et MTN Côte d’Ivoire). Ce mode de paiement est particulièrement utile pour les sites e-commerce qui souhaitent garder l'utilisateur sur leur plateforme tout au long du processus, sans redirection vers une autre page.

**Envoi d’un Paiement Mobile Sans Redirection**

Le processus de paiement mobile sans redirection se divise en deux étapes principales dans l'environnement **Live** ou **Sandbox** :

<Steps>
  <Step title="Créer une collecte de paiement">
    La première étape consiste à créer une collecte via l'API de FedaPay. Cela génère un **token** qui est nécessaire pour effectuer la transaction.
  </Step>

  <Step title="Déclencher le paiement">
    Une fois que vous avez le token de paiement, vous devez envoyer une requête à l'API FedaPay pour traiter le paiement. La requête se fait en utilisant une des [méthodes de paiement](/payment-methods/fr/payment-methods-fr) spécifiques

    ***Voici un exemple de code pour envoyer un paiement mobile sans redirection***

    <CodeGroup>
      ```java curl theme={null}
      curl -X POST \
      https://sandbox-api.fedapay.com/v1/METHODE_PAIEMENT \
      -H 'Authorization: Bearer TOKEN' \
      -H 'Content-Type: application/json'
      -d '{
        "token" : "TOKEN_DE_PAIEMENT",
        "phone_number" = {
          "number": "64000001",
          "country":"bj"
        }
      }'
      ```

      ```javascript Node.js theme={null}
      const { FedaPay, Transaction } = require('fedapay');
      /* Configure your API key and environment */
      FedaPay.setApiKey('YOUR_SECRET_API_KEY');
      FedaPay.setEnvironment('sandbox'); // or 'live'
      /* Create a transaction */
      const transaction = await Transaction.create({
      description: 'Payment for order #5678',
      amount: 1000,
      currency: { iso: 'XOF' },
      callback_url: 'https://example.com/callback',
      customer: { id: 1 }
      });
      console.log('Transaction created:', transaction.id);
      /* Generate a payment token */
      const token = transaction.generateToken().token;
      /* Define payment method */
      const mode = 'mtn'; // or 'moov', 'mtn_ci', 'moov_tg'
      /* Optional phone number for the transaction */
      const phone_number = {
      number: '64000001',
      country: 'bj'
      };
      /* Trigger payment using the token */
      await transaction.sendNowWithToken(mode, token, phone_number);
      console.log(`Payment initiated via ${mode} for transaction ${transaction.id}`);
      /* Or trigger the payment in one step */
      await transaction.sendNow(mode, phone_number);
      ```

      ```php PHP theme={null}
      // Configure your API key and environment
      \FedaPay\FedaPay::setApiKey('YOUR_SECRET_API_KEY');
      \FedaPay\FedaPay::setEnvironment('sandbox'); // or 'live'
      // Create a transaction
      $transaction = \FedaPay\Transaction::create([
      "description" => "Payment for order #5678",
      "amount" => 1000,
      "currency" => ["iso" => "XOF"],
      "callback_url" => "https://example.com/callback",
      "customer" => ["id" => 1]
      ]);
      // Generate a payment token
      $token = $transaction->generateToken()->token;
      // Définir la méthode de paiement
      $mode = 'METHODE_PAIEMENT'; // 'mtn', 'moov', 'mtn_ci', 'moov_tg'
      // (Optional) Phone number linked to payment
      $phone_number = [
      "number" => "64000001",
      "country" => "bj"
      ];
      // Trigger payment with token
      $transaction->sendNowWithToken($mode, $token, $phone_number);
      // Or, trigger the payment in one step
      $transaction->sendNow($mode, $phone_number);
      ```

      ```Ruby Ruby theme={null}
      require 'fedapay'
      # Configure FedaPay API credentials
      FedaPay.api_key = 'YOUR_SECRET_API_KEY'
      FedaPay.environment = 'sandbox' # or 'live'
      # Create a transaction
      transaction = FedaPay::Transaction.create(
      amount: 1000,
      currency: { iso: 'XOF' },
      customer: { id: 1 },
      description: 'Payment for order #5678',
      callback_url: 'https://example.com/callback'
      )
      puts "Transaction created: #{transaction.id}"
      # Generate a payment token
      token_data = transaction.generate_token
      token = token_data.token
      # Define the payment method
      mode = 'mtn' # or 'moov', 'mtn_ci', 'moov_tg'
      # (Optional) Phone number for the payment
      phone_number = {
      number: '64000001',
      country: 'BJ'
      }
      # Trigger immediate payment with the token
      transaction.send_now_with_token(mode, token, phone_number)
      puts "Payment initiated via #{mode} for transaction #{transaction.id}"
      # Or trigger the payment in one step
      transaction.send_now(mode, phone_number)
      ```
    </CodeGroup>
  </Step>
</Steps>

<Warning>
  **Attention :**

  Remplacez **METHODE\_PAIEMENT** par la [méthode de paiement](https://docs.fedapay.com/payment-methods/fr/payment-methods-fr#modes-de-paiement-disponibles-sans-redirection) choisie (par exemple **mtn\_open**, **moov**, etc.).

  **VOTRE\_CLE\_API\_SECRETE** doit être remplacée par votre clé API secrète (en mode **sandbox** pour les tests ou en mode **live** pour les transactions en production).

  Lorsque vous êtes prêt à passer en production, remplacez l'URL de **sandbox** par l'URL en mode **Live** :

  * **Sandbox** : `https://sandbox-api.fedapay.com`

  * **Live** : `https://api.fedapay.com/v1/transactions/ID`

  ***Important** : Veillez à tester minutieusement vos intégrations dans l'environnement **sandbox** avant de les déployer en production*
</Warning>

<Warning>
  **Attention :**

  Le paramètre ***phone\_number*** n’est pas obligatoire pour la requête d’envoie de notification de paiement. Cependant, s’il n’est pas mentionné, FedaPay essaiera d’envoyer la notification au numéro lié au client associé à la transaction lors de sa création.
</Warning>

<Note>
  **Remarque** : Le paiement sans redirection ne prend pas en charge tous les opérateurs. Consulter la section [Méthodes de Paiement](/payment-methods/fr/payment-methods-fr) pour en savoir un peu plus.
</Note>

### Récupération Automatique du Statut d’une Collecte

Pour vérifier le statut final d’une collecte, surtout lors d’un paiement sans redirection :

* Envoyez une requête pour obtenir les détails de la collecte.

* **Implémentez un webhook** pour recevoir des notifications automatiques. [Consultez la section Webhooks pour plus de détails](/integration-api/fr/webhooks-fr).

### Cycle de Vie d’une Collecte : Les Statuts

![Cycle de vie d'une collecte sur FedaPay](https://res.cloudinary.com/dvilp6td2/image/upload/v1773402181/Cycle_vie_statut_fedapay_french28_r6ryzl.jpg)

Le diagramme ci-dessus illustre le cycle de vie complet d'une Collecte, de sa création jusqu'à son statut final.

Chaque collecte passe par différents statuts :

* **pending** : En attente (statut par défaut à la création)

* **approved** : Approuvée (paiement réussi)

* **declined** : Déclinée (interruption volontaire ou accidentelle par le client)

* **canceled** : Annulée (solde insuffisant ou autre problème de paiement)

* **refunded** : Remboursée (somme reversée au client)

* **transferred** : Transférée (montant transféré sur le compte marchand)

* **expired** :  la collecte n’a pas été finalisée dans le délai imparti

<Warning>
  Les statuts **canceled** et **declined** ne sont pas des statuts finaux une nouvelle tentative de paiement peut être relancée. Une collecte **pending** non finalisée expire automatiquement après 24 heures. Un remboursement peut être initié depuis **approved** ou **transferred** via une tentative de remboursement.
</Warning>

<Note>Pour consulter le statut en temps réel, rendez-vous dans le tableau de bord FedaPay sous la section **Collectes** ou utilisez l’API pour vérifier avec l'ID de la collecte.</Note>

### Ajouter des données personnalisées à vos transactions : merchant\_reference et custom\_metadata

Lorsque vous créez une transaction via l’API de FedaPay, il est souvent nécessaire d’y associer des informations propres à votre application. Cela vous permet de mieux suivre, analyser ou relier une transaction à un utilisateur ou une commande spécifique sur votre plateforme. FedaPay vous offre deux champs très utiles pour cela : **merchant\_reference** et **custom\_metadata**.

**merchant\_reference : Votre identifiant unique pour chaque transaction**

Le champ **merchant\_reference** vous permet d’attribuer à chaque transaction un identifiant unique défini par vous-même (par exemple : un ID de commande, un numéro de facture ou le code d’une session d’achat). Cet identifiant est stocké par FedaPay et peut ensuite être utilisé pour retrouver facilement la transaction via une API dédiée.

**Pourquoi l’utiliser ?**

* Vous avez une plateforme e-commerce ou une application mobile et souhaitez lier une transaction FedaPay à un paiement interne.

* Vous souhaitez retrouver rapidement une transaction en utilisant vos propres références, sans avoir à stocker l’ID généré par FedaPay.

* Vous voulez tracer plus facilement les paiements effectués par vos clients.

**Exemple : Créer une transaction avec merchant\_reference**

<CodeGroup>
  ```java Curl theme={null}
  curl -X POST \
  https://sandbox-api.fedapay.com/v1/transactions \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
        "description" : "Transaction for john.doe@example.com",
        "amount" : 2000,
        "currency" : {"iso" : "XOF"},
        "callback_url" : "https://maplateforme.com/callback",
        "customer" : {
          "email" : "john.doe@example.com",
        },
        "merchant_reference": "CMD-20250701-001" 
      }'
  ```

  ```javascript NodeJs theme={null}
  const { FedaPay, Transaction } = require('fedapay');
  // Configurer la clé API et l'environnement
  FedaPay.setApiKey('YOUR_SECRET_API_KEY');
  FedaPay.setEnvironment('sandbox'); // ou 'live'
  // Créer une transaction avec merchant_reference et custom_metadata
  const transaction = await Transaction.create({
  description: 'Transaction for john.doe@example.com',
  amount: 2000,
  currency: { iso: 'XOF' },
  callback_url: 'https://maplateforme.com/callback',
  customer: {
    email: 'john.doe@example.com'
  },
  merchant_reference: 'CMD-20250701-001',
  custom_metadata: {
    order_type: 'online',
    promo_code: 'SUMMER2025'
  }
  });

  console.log('Transaction created:', transaction.id);
  ```

  ```php PHP theme={null}
     $transaction = \FedaPay\Transaction::create([
  "description" => "Transaction for john.doe@example.com",
  "amount" => 2000,
  "currency" => ["iso" => "XOF"],
  "callback_url" => "https://maplateforme.com/callback",
  "customer" => [
  "email" => "john.doe@example.com"
  ],
  "merchant_reference" => "CMD-20250701-001",
  "custom_metadata" => [
  "order_type" => "online",
  "promo_code" => "SUMMER2025"
  ]
  ]);

  echo "Transaction created: " . $transaction->id;
  ```

  ```Ruby Ruby theme={null}
  require 'fedapay'

  # Configurer la clé API et l'environnement
  FedaPay.api_key = 'YOUR_SECRET_API_KEY'
  FedaPay.environment = 'sandbox' # ou 'live'

  # Créer une transaction avec merchant_reference et custom_metadata
  transaction = FedaPay::Transaction.create(
  description: 'Transaction for john.doe@example.com',
  amount: 2000,
  currency: { iso: 'XOF' },
  callback_url: 'https://maplateforme.com/callback',
  customer: { email: 'john.doe@example.com' },
  merchant_reference: 'CMD-20250701-001',
  custom_metadata: {
  order_type: 'online',
  promo_code: 'SUMMER2025'
  }
  )
  puts "Transaction created: #{transaction.id}"
  ```
</CodeGroup>

<Note>Dans cet exemple, CMD-20250701-001 est la référence propre au marchand pour cette commande.</Note>

**Récupérer une transaction avec la référence marchand**

<CodeGroup>
  ```java Curl theme={null}
  curl -X GET \
  https://sandbox-api.fedapay.com/v1/transactions/merchant/{reference}
   \
  -H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
  -H 'Content-Type: application/json'

  ```

  ```javascript NodeJs theme={null}
  const { FedaPay, Transaction } = require('fedapay');
  /* Replace YOUR_SECRET_API_KEY with your real API key */
  FedaPay.setApiKey("YOUR_SECRET_API_KEY");
  /* Specify whether you want to run your query in test or live mode */
  FedaPay.setEnvironment('sandbox'); // or 'live'
  /* Merchant reference to search */
  const reference = 'CMD-20250701-001';
  /* Retrieve transaction by merchant reference */
  const transaction = await Transaction.retrieveByMerchantReference(reference);
  console.log("Transaction found:", transaction.id);

  ```

  ```php PHP theme={null}
  $merchant_reference = 'CMD-20250701-001';
  $transaction = \FedaPay\Transaction::retrieveByMerchantReference($merchant_reference);
  echo "Transaction found: " . $transaction->id;
  ```

  ```Ruby Ruby theme={null}
  require 'fedapay'
  FedaPay.api_key = 'YOUR_SECRET_API_KEY'
  FedaPay.environment = 'sandbox' # or 'live'
  reference = 'CMD-20250701-001'
  transaction = FedaPay::Transaction.retrieve_by_merchant_reference(reference)
  puts "Transaction found: #{transaction.id}"
  ```
</CodeGroup>

**custom\_metadata : Ajouter des données personnalisées à vos transactions**

Avec le champ **custom\_metadata**, vous pouvez enregistrer des informations supplémentaires directement dans la transaction. Il peut s’agir, par exemple :

* Le numéro de la commande

* Du type de service acheté

* De l’identifiant de l’agent vendeur

* Ou toute autre donnée utile pour vous.

Ces données sont stockées sous forme de paires clé-valeur et restent attachées à la transaction, sans affecter son traitement.

**Pourquoi l’utiliser ?**

* Pour enrichir vos rapports internes ou automatiser certains traitements en récupérant vos propres données.

* Pour éviter de stocker des informations sensibles côté client.

* Pour gagner du temps lors du rapprochement comptable ou des vérifications manuelles.

**Exemple : Créer une transaction avec custom\_metadata**

<CodeGroup>
  ```java Curl theme={null}
  curl -X POST https://sandbox-api.fedapay.com/v1/transactions \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Abonnement premium",
  "amount": 10000,
  "currency": {"iso": "XOF"},
  "callback_url": "https://votreapp.com/callback",
  "customer": {
    "email": "utilisateur@votreapp.com"
  },
  "custom_metadata": {
    "client_id": "USER-14567",
    "forfait": "premium",
    "langue": "fr"
  }
  }'
  ```

  ```javascript NodeJs theme={null}
  const { FedaPay, Transaction } = require('fedapay');
  /* Replace YOUR_SECRET_API_KEY with your real API key */
  FedaPay.setApiKey("YOUR_SECRET_API_KEY");
  /* Specify whether you want to run your query in test or live mode */
  FedaPay.setEnvironment('sandbox'); // or 'live'
  /* Create a transaction with custom_metadata */
  const transaction = await Transaction.create({
  description: "Abonnement premium",
  amount: 10000,
  currency: { iso: "XOF" },
  callback_url: "https://votreapp.com/callback",
  customer: {
    email: "utilisateur@votreapp.com"
  },
  custom_metadata: {
    client_id: "USER-14567",
    forfait: "premium",
    langue: "fr"
  }
  });
  console.log("Transaction created:", transaction.id);

  ```

  ```php PHP theme={null}

  // Configurer la clé API et l'environnement
  \FedaPay\FedaPay::setApiKey('YOUR_SECRET_API_KEY');
  \FedaPay\FedaPay::setEnvironment('sandbox'); // ou 'live'
  // Créer une transaction avec custom_metadata
  $transaction = \FedaPay\Transaction::create([
  "description" => "Abonnement premium",
  "amount" => 10000,
  "currency" => ["iso" => "XOF"],
  "callback_url" => "https://votreapp.com/callback",
  "customer" => [
  "email" => "utilisateur@votreapp.com"
  ],
  "custom_metadata" => [
  "client_id" => "USER-14567",
  "forfait" => "premium",
  "langue" => "fr"
  ]
  ]);
  echo "Transaction created: " . $transaction->id;

  ```

  ```Ruby Ruby theme={null}
  require 'fedapay'
  FedaPay.api_key = 'YOUR_SECRET_API_KEY'
  FedaPay.environment = 'sandbox' # or 'live'
  transaction = FedaPay::Transaction.create(
  description: 'Abonnement premium',
  amount: 10000,
  currency: { iso: 'XOF' },
  callback_url: 'https://votreapp.com/callback',
  customer: {
  email: 'utilisateur@votreapp.com'
  },
  custom_metadata: {
  client_id: 'USER-14567',
  forfait: 'premium',
  langue: 'fr'
  }
  )
  puts "Transaction created: #{transaction.id}"
  ```
</CodeGroup>

<Warning>
  **Bonnes pratiques** :

  * Assurez-vous que la valeur de merchant\_reference est unique pour chaque transaction. Si la valeur de l’identifiant existe déjà, la création de la transaction échouera.

  * Utilisez custom\_metadata uniquement pour des données non sensibles (évitez les mots de passe, données de carte, etc.).

  * Ces champs sont facultatifs, mais très utiles pour automatiser vos flux métier et faciliter l’intégration avec vos outils internes.
</Warning>