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

# Créer un Lien de paiement

> Créez des liens de paiement réutilisables pour collecter des paiements

## Créer un Lien de paiement

### Requête de base

```bash theme={null}
curl -X POST https://api.yabetoo.com/v1/payment-links \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "amount",
    "name": "Paiement facture",
    "amount": 25000,
    "currency": "XOF"
  }'
```

### Paramètres requis

| Paramètre  | Type   | Description                                           |
| ---------- | ------ | ----------------------------------------------------- |
| `type`     | string | Type de lien : `product`, `amount`, ou `subscription` |
| `name`     | string | Nom du lien (affiché au client)                       |
| `currency` | string | Code devise (`XOF`, `EUR`, `USD`)                     |

### Paramètres optionnels

| Paramètre                | Type    | Description                             |
| ------------------------ | ------- | --------------------------------------- |
| `description`            | string  | Description du lien                     |
| `slug`                   | string  | Slug personnalisé pour l'URL            |
| `amount`                 | number  | Montant fixe (pour type `amount`)       |
| `minAmount`              | number  | Montant minimum (pour montant variable) |
| `maxAmount`              | number  | Montant maximum (pour montant variable) |
| `items`                  | array   | Articles à vendre (pour type `product`) |
| `expiresAt`              | string  | Date d'expiration (ISO 8601)            |
| `maxRedemptions`         | number  | Nombre maximum d'utilisations           |
| `collectBillingAddress`  | boolean | Collecter l'adresse de facturation      |
| `collectShippingAddress` | boolean | Collecter l'adresse de livraison        |
| `allowPromotionCodes`    | boolean | Autoriser les codes promo               |
| `successUrl`             | string  | URL de redirection après paiement       |
| `cancelUrl`              | string  | URL de redirection si annulation        |
| `brandingId`             | string  | ID du branding personnalisé             |
| `metadata`               | object  | Données personnalisées                  |

## Types de liens

<Tabs>
  <Tab title="Montant fixe">
    ### Type `amount` - Montant fixe

    Pour collecter un montant spécifique :

    ```json theme={null}
    {
      "type": "amount",
      "name": "Facture #1234",
      "description": "Paiement de votre facture du mois de janvier",
      "amount": 50000,
      "currency": "XOF"
    }
    ```
  </Tab>

  <Tab title="Montant variable">
    ### Type `amount` - Montant variable

    Permettez au client de choisir le montant (idéal pour les dons) :

    ```json theme={null}
    {
      "type": "amount",
      "name": "Faire un don",
      "description": "Soutenez notre association",
      "minAmount": 1000,
      "maxAmount": 1000000,
      "currency": "XOF"
    }
    ```

    <Tip>
      Si `amount` est omis mais `minAmount` et/ou `maxAmount` sont définis,
      le client pourra saisir le montant de son choix dans les limites spécifiées.
    </Tip>
  </Tab>

  <Tab title="Produits">
    ### Type `product` - Vente de produits

    Vendez des produits de votre catalogue :

    ```json theme={null}
    {
      "type": "product",
      "name": "Boutique T-shirts",
      "description": "Collection été 2024",
      "currency": "XOF",
      "items": [
        {
          "productId": "prod_abc123",
          "priceId": "price_xyz789",
          "quantity": 1,
          "adjustableQuantity": true,
          "minQuantity": 1,
          "maxQuantity": 10
        },
        {
          "name": "Frais de livraison",
          "description": "Livraison express",
          "quantity": 1,
          "isOptional": false
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Abonnement">
    ### Type `subscription` - Abonnement récurrent

    Créez un lien qui démarre un abonnement :

    ```json theme={null}
    {
      "type": "subscription",
      "name": "Abonnement Pro",
      "description": "Accès illimité à toutes les fonctionnalités",
      "currency": "XOF",
      "items": [
        {
          "priceId": "price_recurring_monthly"
        }
      ]
    }
    ```

    <Warning>
      Pour les abonnements, utilisez un `priceId` associé à un prix récurrent.
    </Warning>
  </Tab>
</Tabs>

## Structure des articles (items)

Pour les types `product` et `subscription`, vous pouvez définir des articles :

| Champ                | Type    | Description                                   |
| -------------------- | ------- | --------------------------------------------- |
| `productId`          | string  | ID du produit (`prod_xxx`)                    |
| `priceId`            | string  | ID du prix (`price_xxx`)                      |
| `name`               | string  | Nom personnalisé (si pas de produit)          |
| `description`        | string  | Description personnalisée                     |
| `imageUrl`           | string  | URL de l'image                                |
| `quantity`           | number  | Quantité par défaut (défaut: 1)               |
| `adjustableQuantity` | boolean | Permettre au client de modifier la quantité   |
| `minQuantity`        | number  | Quantité minimum                              |
| `maxQuantity`        | number  | Quantité maximum                              |
| `isOptional`         | boolean | Article optionnel (le client peut le retirer) |
| `sortOrder`          | number  | Ordre d'affichage                             |

## Options avancées

### Limiter les utilisations

```json theme={null}
{
  "type": "amount",
  "name": "Offre limitée",
  "amount": 15000,
  "currency": "XOF",
  "maxRedemptions": 100,
  "expiresAt": "2024-12-31T23:59:59Z"
}
```

### Collecter les adresses

```json theme={null}
{
  "collectBillingAddress": true,
  "collectShippingAddress": true
}
```

### Autoriser les codes promo

```json theme={null}
{
  "allowPromotionCodes": true
}
```

### URL de redirection personnalisées

```json theme={null}
{
  "successUrl": "https://votre-site.com/merci?link_id={PAYMENT_LINK_ID}",
  "cancelUrl": "https://votre-site.com/annule"
}
```

### Slug personnalisé

Créez une URL mémorable :

```json theme={null}
{
  "slug": "don-2024"
}
```

L'URL sera : `https://checkout.yabetoo.com/p/don-2024`

## Exemple complet

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.yabetoo.com/v1/payment-links \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "type": "product",
      "name": "Boutique Formation",
      "description": "Formations en ligne",
      "slug": "formations",
      "currency": "XOF",
      "collectBillingAddress": true,
      "allowPromotionCodes": true,
      "successUrl": "https://votre-site.com/success",
      "cancelUrl": "https://votre-site.com/cancel",
      "maxRedemptions": 500,
      "expiresAt": "2024-12-31T23:59:59Z",
      "items": [
        {
          "productId": "prod_formation_js",
          "priceId": "price_formation_js",
          "quantity": 1,
          "adjustableQuantity": false
        },
        {
          "productId": "prod_formation_react",
          "priceId": "price_formation_react",
          "quantity": 1,
          "isOptional": true
        }
      ],
      "metadata": {
        "campaign": "summer_2024",
        "source": "newsletter"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.yabetoo.com/v1/payment-links", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer sk_live_...",
    },
    body: JSON.stringify({
      type: "product",
      name: "Boutique Formation",
      description: "Formations en ligne",
      slug: "formations",
      currency: "XOF",
      collectBillingAddress: true,
      allowPromotionCodes: true,
      successUrl: "https://votre-site.com/success",
      items: [
        {
          productId: "prod_formation_js",
          priceId: "price_formation_js",
          quantity: 1,
        },
      ],
      metadata: {
        campaign: "summer_2024",
      },
    }),
  });

  const paymentLink = await response.json();
  console.log(paymentLink.url); // URL à partager
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.yabetoo.com/v1/payment-links",
      headers={
          "Authorization": "Bearer sk_live_...",
          "Content-Type": "application/json"
      },
      json={
          "type": "amount",
          "name": "Faire un don",
          "description": "Soutenez notre cause",
          "minAmount": 1000,
          "maxAmount": 500000,
          "currency": "XOF",
          "allowPromotionCodes": False,
          "metadata": {
              "campaign": "charity_2024"
          }
      }
  )

  payment_link = response.json()
  print(payment_link["url"])
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => "https://api.yabetoo.com/v1/payment-links",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer sk_live_...",
          "Content-Type: application/json"
      ],
      CURLOPT_POSTFIELDS => json_encode([
          "type" => "amount",
          "name" => "Paiement facture",
          "amount" => 75000,
          "currency" => "XOF",
          "expiresAt" => "2024-06-30T23:59:59Z",
          "metadata" => [
              "invoice_id" => "INV-2024-001"
          ]
      ])
  ]);

  $response = curl_exec($curl);
  $paymentLink = json_decode($response, true);
  echo $paymentLink["url"];
  ```
</CodeGroup>

## Réponse

```json theme={null}
{
  "id": "plink_abc123def456ghi789jkl012",
  "object": "payment_link",
  "type": "product",
  "name": "Boutique Formation",
  "description": "Formations en ligne",
  "slug": "formations",
  "url": "https://checkout.yabetoo.com/p/formations",
  "currency": "XOF",
  "amount": null,
  "minAmount": null,
  "maxAmount": null,
  "isActive": true,
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "maxRedemptions": 500,
  "redemptionCount": 0,
  "collectBillingAddress": true,
  "collectShippingAddress": false,
  "allowPromotionCodes": true,
  "successUrl": "https://votre-site.com/success",
  "cancelUrl": "https://votre-site.com/cancel",
  "items": [
    {
      "id": "plitem_abc123",
      "productId": "prod_formation_js",
      "priceId": "price_formation_js",
      "name": "Formation JavaScript",
      "description": "Maîtrisez JavaScript",
      "quantity": 1,
      "adjustableQuantity": false,
      "isOptional": false,
      "sortOrder": 0
    },
    {
      "id": "plitem_def456",
      "productId": "prod_formation_react",
      "priceId": "price_formation_react",
      "name": "Formation React",
      "description": "Créez des apps React",
      "quantity": 1,
      "adjustableQuantity": false,
      "isOptional": true,
      "sortOrder": 1
    }
  ],
  "metadata": {
    "campaign": "summer_2024",
    "source": "newsletter"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
```

### Champs de la réponse

| Champ             | Description                              |
| ----------------- | ---------------------------------------- |
| `id`              | Identifiant unique du lien               |
| `url`             | URL publique à partager                  |
| `slug`            | Slug utilisé dans l'URL                  |
| `isActive`        | Indique si le lien est actif             |
| `redemptionCount` | Nombre de fois que le lien a été utilisé |
| `items`           | Liste des articles (pour type `product`) |

## Opérations courantes

### Récupérer un lien

```bash theme={null}
curl https://api.yabetoo.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..."
```

### Mettre à jour un lien

```bash theme={null}
curl -X PATCH https://api.yabetoo.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nouveau nom",
    "isActive": false
  }'
```

### Désactiver un lien

```bash theme={null}
curl -X PATCH https://api.yabetoo.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'
```

### Supprimer un lien

```bash theme={null}
curl -X DELETE https://api.yabetoo.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..."
```

### Lister les liens

```bash theme={null}
curl "https://api.yabetoo.com/v1/payment-links?type=product&isActive=true" \
  -H "Authorization: Bearer sk_live_..."
```

## Webhooks

Recevez des notifications lorsqu'un paiement est effectué via un lien :

```json theme={null}
{
  "type": "payment_link.payment.completed",
  "data": {
    "object": {
      "paymentLinkId": "plink_abc123",
      "sessionId": "plsession_xyz789",
      "amount": 25000,
      "currency": "XOF",
      "customerEmail": "client@example.com",
      "status": "completed"
    }
  }
}
```

### Événements disponibles

| Événement                        | Description                 |
| -------------------------------- | --------------------------- |
| `payment_link.created`           | Lien créé                   |
| `payment_link.updated`           | Lien mis à jour             |
| `payment_link.payment.completed` | Paiement réussi via le lien |
| `payment_link.payment.failed`    | Paiement échoué             |

## Bonnes pratiques

<AccordionGroup>
  <Accordion title="Sécurité">
    * Créez toujours les liens côté serveur
    * Ne stockez jamais les clés API côté client
    * Utilisez des webhooks pour vérifier les paiements
  </Accordion>

  <Accordion title="Expérience utilisateur">
    * Utilisez des slugs mémorables pour les liens importants
    * Ajoutez une description claire
    * Définissez une date d'expiration raisonnable
  </Accordion>

  <Accordion title="Gestion">
    * Utilisez les métadonnées pour le suivi (campagne, source, etc.)
    * Surveillez le `redemptionCount` pour les offres limitées
    * Désactivez les liens plutôt que de les supprimer
  </Accordion>
</AccordionGroup>

## Prochaines étapes

<CardGroup cols={2}>
  <Card title="Partager un lien" icon="share" href="/fr/payments/payment-link/share">
    Découvrez comment partager vos liens efficacement
  </Card>

  <Card title="Webhooks" icon="bell" href="/fr/developer-tools/webhook/overview">
    Configurez les notifications en temps réel
  </Card>
</CardGroup>