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

# Payment Links

> Create shareable payment URLs for your buyers.

# Payment Links

Payment links let you collect payments without building a custom checkout. Create a link, share it via any channel, and the buyer completes payment through the hosted Wava checkout page.

## Use cases

* **Invoicing**: Send a payment link with a fixed amount for an invoice.
* **Social commerce**: Share links via WhatsApp, Instagram, or email.
* **Donations**: Create dynamic links where the buyer enters the amount.
* **Recurring manual payments**: Generate a new link for each billing cycle.

## Creating a payment link

```bash theme={null}
curl -X POST "https://api.wava.co/v1/links" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "description": "Invoice #1234",
    "currency": "COP",
    "order_key": "invoice-1234",
    "redirect_link": "https://mystore.com/success",
    "redirect_link_cancel": "https://mystore.com/cancel",
    "redirect_link_failure": "https://mystore.com/error",
    "ttl_minutes": 1440
  }'
```

### Request fields

| Field                   | Type         | Required | Description                                                                                                                                                     |
| ----------------------- | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `description`           | string       | Yes      | Label shown to the buyer on the checkout page                                                                                                                   |
| `amount`                | number       | No       | Fixed amount in the smallest currency unit. Omit for dynamic links                                                                                              |
| `currency`              | string       | No       | 3-letter ISO code (e.g. `COP`). Defaults to the store's currency                                                                                                |
| `order_key`             | string       | No       | Your internal reference (invoice ID, order number, etc.)                                                                                                        |
| `redirect_link`         | string (URL) | No       | Redirect after successful payment                                                                                                                               |
| `redirect_link_cancel`  | string (URL) | No       | Redirect when buyer cancels                                                                                                                                     |
| `redirect_link_failure` | string (URL) | No       | Redirect on payment failure                                                                                                                                     |
| `ttl_minutes`           | integer      | No       | Minutes until the link expires (1–525600). Omit for no expiration                                                                                               |
| `user_data_required`    | boolean      | No       | Whether the checkout collects shopper contact data (name, email, phone). Omit to use the type default: `true` for fixed-amount links, `false` for dynamic links |

### Response

```json theme={null}
{
  "data": {
    "link": "https://checkout.wava.co/link/abc123def456",
    "hash": "abc123def456",
    "expires_at": "2026-06-18T14:30:00.000Z"
  }
}
```

`expires_at` is the UTC timestamp when the link expires, or `null` if no `ttl_minutes` was provided.

Share the `link` with your buyer. When they open it, they see the payment amount and can select their preferred payment method (Nequi, Daviplata, Breb, or Stripe if enabled).

## Link expiration (TTL)

Use `ttl_minutes` to create time-limited links:

```json theme={null}
{
  "description": "Flash sale — 24h only",
  "amount": 99000,
  "currency": "COP",
  "ttl_minutes": 1440
}
```

Once a link passes its `expires_at` timestamp:

* The Wava checkout page returns a `410` error with code `PAYMENT_LINK_EXPIRED`.
* Attempting to place an order on the link is blocked.
* The error response includes redirect URLs (same fields as `PAYMENT_LINK_INACTIVE`) so you can send buyers to a custom expiration page.

**In-flight payments are honored**: if a buyer starts payment before the link expires and the gateway confirms afterward, the payment is accepted. Expiration only blocks new payment attempts.

## Redirect URLs

After the buyer completes (or cancels) the payment, they are redirected to the URL you specified:

| Field                   | When used          |
| ----------------------- | ------------------ |
| `redirect_link`         | Successful payment |
| `redirect_link_cancel`  | Buyer cancels      |
| `redirect_link_failure` | Payment fails      |

All redirect fields are optional. If omitted, the buyer stays on the Wava checkout confirmation page.

<Tip>
  Use `order_key` to associate the payment link with your internal reference (invoice number, order ID, etc.) for reconciliation.
</Tip>

## Webhooks and payment links

<Warning>
  Payment links created from the Wava merchant dashboard (app.wava.co) do not trigger webhook notifications. Webhooks are only sent for payment links created via the API. If you need webhook notifications for payments, create links programmatically using this endpoint.
</Warning>

## Error codes

| Code                    | HTTP | Description                            |
| ----------------------- | ---- | -------------------------------------- |
| `PAYMENT_LINK_INACTIVE` | 410  | Link was manually deactivated          |
| `PAYMENT_LINK_EXPIRED`  | 410  | Link passed its `expires_at` timestamp |