# Enlaces de pago · Documentación de Pagos Express

> Crear, listar, consultar y desactivar enlaces de cobro con POST /v1/payment_links. Conceptos, importes en centavos, monedas, vencimiento y estados.

HTML: https://pagos.express/docs/enlaces-de-pago
Texto para modelos: https://pagos.express/docs/enlaces-de-pago.llms.txt
Índice de la documentación: https://pagos.express/docs

Un enlace de pago es una solicitud de cobro con conceptos, importe y vencimiento. El cliente lo abre, ve la marca del comercio y paga en el checkout del proveedor conectado.

## Crear: POST /v1/payment_links
Encabezados: `Authorization: Bearer`, `Idempotency-Key` (obligatorio), `Content-Type: application/json`.

- `title` (string 1–200, obligatorio): encabezado de la página de cobro.
- `description` (string ≤ 2000): texto opcional bajo el título.
- `items[]` (1–20): cada uno con `name` (1–200), `quantity` (1–999) y `unitPriceCentavos` (entero ≥ 1). El total es la suma. Para facturar: `satProductCode` (8 dígitos), `satUnitCode` (E48, H87…) y `tax` (`iva_included`, `iva_added` suma 16 % al total, `exempt`).
- `invoiceable` (boolean): el cliente puede pedir su CFDI al pagar. Requiere CFDI Express conectado con un emisor; si no, `409 invoicing_unavailable`.
- `currency` (ISO 4217, por defecto MXN): solo monedas de dos decimales que Stripe presente (USD, EUR…). JPY, KRW y KWD se rechazan. eCart Pay solo se ofrece cuando la moneda del enlace coincide con la de su cuenta.
- `providers` (opcional): pasarelas que verá el cliente, en orden: `stripe`, `ecartpay` o ambas. Vacío u omitido ofrece todas las conectadas. Cada una debe tener una conexión activa en el modo de tu clave; si no, `409 no_active_connection`. Con varias, la página deja elegir; eCart Pay pide el correo del cliente.
- `customerEmail`, `customerName`: prellenan el checkout.
- `expiresAt` (ISO 8601): tras ese instante no se puede pagar. Un checkout no puede iniciar a menos de 30 minutos del vencimiento.
- `metadata` (objeto plano): hasta 50 claves de 1–40 caracteres; valores string ≤ 500, números o booleanos. Sin anidar. Se devuelve en el enlace, sus pagos y cada webhook; el cliente no lo ve.

## Importes y límites
- Unidades menores: MX$1,500.00 = 150000. Sin totales aparte; solo `tax: "iva_added"` suma IVA al total.

## Facturación (CFDI)
Conecta CFDI Express en Conexiones y elige el emisor. Con `invoiceable: true`, al pagar el cliente ve “Facturar esta compra” y CFDI Express timbra con tu emisor (un timbre de tu saldo). `GET /v1/payments/{id}/invoice` da `invoiceUrl`, formas de pago SAT y la última factura; `POST` a la misma ruta factura por el cliente con rfc, name, zip, regimenFiscal, usoCfdi y formaPago si hay varias. `POST /v1/payments/{id}/invoice/cancel` con `motivo` 02 o 03. `GET /v1/payments/{id}/invoice/files` da las URLs del PDF y XML (caducan en 15 minutos) y `GET /v1/invoicing/catalogs` los catálogos SAT de régimen fiscal y uso CFDI. Eventos: payment.invoiced, payment.invoice_failed, payment.invoice_cancelled. Un precio con IVA incluido puede diferir un centavo de la factura por concepto.
- Totales fuera del rango de Stripe se rechazan al crear: mínimo por moneda (MX$10.00, US$0.50, €0.50…) o máximo de ocho dígitos.
- Otra moneda liquida en la moneda de la cuenta conectada al tipo de cambio de Stripe.

## Estados
`active` (se puede pagar), `processing` (checkout abierto), `paid` (cobrado; `paidPaymentId` apunta al pago `succeeded`), `expired`, `disabled`.

## Operaciones
- Listar: `GET /v1/payment_links` con `limit` (1–100), `starting_after`, `status`.
- Consultar: `GET /v1/payment_links/{id}`.
- Desactivar: `POST /v1/payment_links/{id}/disable`. No reembolsa. Un checkout ya pagado responde `409 link_already_paid`.
- Editar: `POST /v1/payment_links/{id}` cambia title, description, customerEmail, customerName, expiresAt o metadata mientras esté `active`. Conceptos e importe no cambian. `metadata` reemplaza el objeto completo.
- Marcar pagado fuera del checkout: `POST /v1/payment_links/{id}/mark_paid` con `method` (card, oxxo_cash, spei_transfer, other), `note`, `paidAt` y `reference` opcional (PNG/JPEG/WebP/PDF ≤ 700 KB como data URL). Crea un pago `provider: manual` en `succeeded` y dispara los webhooks. Con un checkout en curso responde `409 request_in_flight`.

Conectar Stripe o eCart Pay es una acción del dashboard; la API solo lee `GET /v1/connections`. Sin cuenta de eCart Pay, el comercio puede crearla con el enlace de partner de Pagos Express: https://api.partners.tendencys.com/api/r/100/ecartpay