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

# Payment Links

> Crea links de pago reutilizables o limitados con SimplePay para invoices, cobros asincronos, ventas manuales y flujos no embebidos.

Payment Links son URLs de pago que puedes compartir por email, WhatsApp, CRM, dashboard interno o portal de cliente.

## Cuando usarlos

Usa Payment Links si:

* El pago no ocurre dentro de un checkout inmediato.
* Necesitas cobrar una invoice, anticipo o servicio manual.
* Quieres limitar pagos, expirar el link o recolectar datos extra.
* Tu equipo comercial necesita enviar links desde sistemas internos.

## Crear un link

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://api.simplepay.mx/v1/payment-links" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice_2026_0007_link_v1" \
  -d '{
    "name": "Factura 2026-0007",
    "amount": 250000,
    "currency": "mxn",
    "description": "Servicios profesionales",
    "success_url": "https://app.example.com/invoices/2026-0007/paid",
    "client_reference_id": "invoice_2026_0007",
    "customer_email": "finance@example.com",
    "payment_method_types": ["card", "spei"],
    "max_payments": 1,
    "expires_at": "2026-07-01T05:59:59.000Z",
    "metadata": {
      "invoice_id": "2026-0007"
    }
  }'
```

## Campos utiles

| Campo                        | Uso                                          |
| ---------------------------- | -------------------------------------------- |
| `name`                       | Titulo visible o identificador del cobro.    |
| `amount`                     | Monto en minor units.                        |
| `currency`                   | Moneda en minusculas, normalmente `mxn`.     |
| `max_payments`               | Limita cuantas veces se puede pagar el link. |
| `expires_at`                 | Fecha de expiracion ISO 8601.                |
| `collect_customer_names`     | Pide nombre al pagar.                        |
| `collect_customer_addresses` | Pide direccion.                              |
| `require_phone`              | Pide telefono.                               |
| `metadata`                   | Referencias no secretas para reconciliacion. |

## Leer un link

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS "https://api.simplepay.mx/v1/payment-links/splink_0123456789abcdef0123456789abcdef" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY"
```

## Buen patron para invoices

<Steps>
  <Step title="Congela la invoice">
    Guarda monto, moneda, conceptos y cliente antes de crear el link.
  </Step>

  <Step title="Crea un link con `max_payments: 1`">
    Evita pagos duplicados para una invoice unica.
  </Step>

  <Step title="Persistelo">Guarda el ID `splink_...` y la URL retornada.</Step>

  <Step title="Escucha webhooks">
    Marca la invoice pagada solo por evento confirmado o read API.
  </Step>
</Steps>

<Tip>
  Si el precio cambia por descuentos, recargos o exchange rates, crea un link
  nuevo en vez de reciclar uno viejo.
</Tip>