> ## 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.

# Create a Payment Link

> Create reusable payment links to collect payments

## Create a Payment Link

### Basic Request

```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": "Invoice Payment",
    "amount": 25000,
    "currency": "XOF"
  }'
```

### Required Parameters

| Parameter  | Type   | Description                                       |
| ---------- | ------ | ------------------------------------------------- |
| `type`     | string | Link type: `product`, `amount`, or `subscription` |
| `name`     | string | Link name (displayed to customer)                 |
| `currency` | string | Currency code (`XOF`, `EUR`, `USD`)               |

### Optional Parameters

| Parameter                | Type    | Description                          |
| ------------------------ | ------- | ------------------------------------ |
| `description`            | string  | Link description                     |
| `slug`                   | string  | Custom slug for the URL              |
| `amount`                 | number  | Fixed amount (for `amount` type)     |
| `minAmount`              | number  | Minimum amount (for variable amount) |
| `maxAmount`              | number  | Maximum amount (for variable amount) |
| `items`                  | array   | Items to sell (for `product` type)   |
| `expiresAt`              | string  | Expiration date (ISO 8601)           |
| `maxRedemptions`         | number  | Maximum number of uses               |
| `collectBillingAddress`  | boolean | Collect billing address              |
| `collectShippingAddress` | boolean | Collect shipping address             |
| `allowPromotionCodes`    | boolean | Allow promo codes                    |
| `successUrl`             | string  | Redirect URL after payment           |
| `cancelUrl`              | string  | Redirect URL if cancelled            |
| `brandingId`             | string  | Custom branding ID                   |
| `metadata`               | object  | Custom data                          |

## Link Types

<Tabs>
  <Tab title="Fixed Amount">
    ### Type `amount` - Fixed Amount

    To collect a specific amount:

    ```json theme={null}
    {
      "type": "amount",
      "name": "Invoice #1234",
      "description": "Payment for your January invoice",
      "amount": 50000,
      "currency": "XOF"
    }
    ```
  </Tab>

  <Tab title="Variable Amount">
    ### Type `amount` - Variable Amount

    Allow the customer to choose the amount (ideal for donations):

    ```json theme={null}
    {
      "type": "amount",
      "name": "Make a Donation",
      "description": "Support our organization",
      "minAmount": 1000,
      "maxAmount": 1000000,
      "currency": "XOF"
    }
    ```

    <Tip>
      If `amount` is omitted but `minAmount` and/or `maxAmount` are defined,
      the customer can enter any amount within the specified limits.
    </Tip>
  </Tab>

  <Tab title="Products">
    ### Type `product` - Product Sales

    Sell products from your catalog:

    ```json theme={null}
    {
      "type": "product",
      "name": "T-shirt Shop",
      "description": "Summer 2024 Collection",
      "currency": "XOF",
      "items": [
        {
          "productId": "prod_abc123",
          "priceId": "price_xyz789",
          "quantity": 1,
          "adjustableQuantity": true,
          "minQuantity": 1,
          "maxQuantity": 10
        },
        {
          "name": "Shipping Fee",
          "description": "Express delivery",
          "quantity": 1,
          "isOptional": false
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Subscription">
    ### Type `subscription` - Recurring Subscription

    Create a link that starts a subscription:

    ```json theme={null}
    {
      "type": "subscription",
      "name": "Pro Subscription",
      "description": "Unlimited access to all features",
      "currency": "XOF",
      "items": [
        {
          "priceId": "price_recurring_monthly"
        }
      ]
    }
    ```

    <Warning>
      For subscriptions, use a `priceId` associated with a recurring price.
    </Warning>
  </Tab>
</Tabs>

## Item Structure

For `product` and `subscription` types, you can define items:

| Field                | Type    | Description                            |
| -------------------- | ------- | -------------------------------------- |
| `productId`          | string  | Product ID (`prod_xxx`)                |
| `priceId`            | string  | Price ID (`price_xxx`)                 |
| `name`               | string  | Custom name (if no product)            |
| `description`        | string  | Custom description                     |
| `imageUrl`           | string  | Image URL                              |
| `quantity`           | number  | Default quantity (default: 1)          |
| `adjustableQuantity` | boolean | Allow customer to modify quantity      |
| `minQuantity`        | number  | Minimum quantity                       |
| `maxQuantity`        | number  | Maximum quantity                       |
| `isOptional`         | boolean | Optional item (customer can remove it) |
| `sortOrder`          | number  | Display order                          |

## Advanced Options

### Limit Usage

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

### Collect Addresses

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

### Allow Promo Codes

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

### Custom Redirect URLs

```json theme={null}
{
  "successUrl": "https://your-site.com/thank-you?link_id={PAYMENT_LINK_ID}",
  "cancelUrl": "https://your-site.com/cancelled"
}
```

### Custom Slug

Create a memorable URL:

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

The URL will be: `https://checkout.yabetoo.com/p/donate-2024`

## Complete Example

<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": "Training Shop",
      "description": "Online courses",
      "slug": "training",
      "currency": "XOF",
      "collectBillingAddress": true,
      "allowPromotionCodes": true,
      "successUrl": "https://your-site.com/success",
      "cancelUrl": "https://your-site.com/cancel",
      "maxRedemptions": 500,
      "expiresAt": "2024-12-31T23:59:59Z",
      "items": [
        {
          "productId": "prod_js_course",
          "priceId": "price_js_course",
          "quantity": 1,
          "adjustableQuantity": false
        },
        {
          "productId": "prod_react_course",
          "priceId": "price_react_course",
          "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: "Training Shop",
      description: "Online courses",
      slug: "training",
      currency: "XOF",
      collectBillingAddress: true,
      allowPromotionCodes: true,
      successUrl: "https://your-site.com/success",
      items: [
        {
          productId: "prod_js_course",
          priceId: "price_js_course",
          quantity: 1,
        },
      ],
      metadata: {
        campaign: "summer_2024",
      },
    }),
  });

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

  ```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": "Make a Donation",
          "description": "Support our 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" => "Invoice Payment",
          "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>

## Response

```json theme={null}
{
  "id": "plink_abc123def456ghi789jkl012",
  "object": "payment_link",
  "type": "product",
  "name": "Training Shop",
  "description": "Online courses",
  "slug": "training",
  "url": "https://checkout.yabetoo.com/p/training",
  "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://your-site.com/success",
  "cancelUrl": "https://your-site.com/cancel",
  "items": [
    {
      "id": "plitem_abc123",
      "productId": "prod_js_course",
      "priceId": "price_js_course",
      "name": "JavaScript Course",
      "description": "Master JavaScript",
      "quantity": 1,
      "adjustableQuantity": false,
      "isOptional": false,
      "sortOrder": 0
    },
    {
      "id": "plitem_def456",
      "productId": "prod_react_course",
      "priceId": "price_react_course",
      "name": "React Course",
      "description": "Build React apps",
      "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"
}
```

### Response Fields

| Field             | Description                            |
| ----------------- | -------------------------------------- |
| `id`              | Unique link identifier                 |
| `url`             | Public URL to share                    |
| `slug`            | Slug used in the URL                   |
| `isActive`        | Indicates if the link is active        |
| `redemptionCount` | Number of times the link has been used |
| `items`           | List of items (for `product` type)     |

## Common Operations

### Retrieve a Link

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

### Update a Link

```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": "New Name",
    "isActive": false
  }'
```

### Deactivate a Link

```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
  }'
```

### Delete a Link

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

### List Links

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

## Webhooks

Receive notifications when a payment is made via a link:

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

### Available Events

| Event                            | Description                 |
| -------------------------------- | --------------------------- |
| `payment_link.created`           | Link created                |
| `payment_link.updated`           | Link updated                |
| `payment_link.payment.completed` | Successful payment via link |
| `payment_link.payment.failed`    | Failed payment              |

## Best Practices

<AccordionGroup>
  <Accordion title="Security">
    * Always create links server-side
    * Never store API keys client-side
    * Use webhooks to verify payments
  </Accordion>

  <Accordion title="User Experience">
    * Use memorable slugs for important links
    * Add a clear description
    * Set a reasonable expiration date
  </Accordion>

  <Accordion title="Management">
    * Use metadata for tracking (campaign, source, etc.)
    * Monitor `redemptionCount` for limited offers
    * Deactivate links rather than deleting them
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Share a Link" icon="share" href="/en/payments/payment-link/share">
    Learn how to share your links effectively
  </Card>

  <Card title="Webhooks" icon="bell" href="/en/developer-tools/webhook/overview">
    Configure real-time notifications
  </Card>
</CardGroup>