Enlaces de pago

Los Enlaces de pago son URL de pago permanentes y compartibles, sin fecha de caducidad por defecto. A diferencia de las Sesiones de pago, que son de un solo uso y caducan, un Enlace de pago puede utilizarse varias veces y por varios clientes distintos.

Casos de uso típicos: enlace de pago en un correo de marketing, botón de compra en un sitio web, código QR en un punto de venta, enlace compartido por WhatsApp.

Enlace de pago frente a Sesión de pago

Enlace de pago → enlace permanente, reutilizable y compartible a gran escala. Ideal para productos estándar. Sesión de pago → sesión única, vinculada a un Customer concreto, que caduca pasado un plazo. Ideal para carritos de comercio electrónico personalizados.

Tipos de enlaces

Tipo	Uso	Campos requeridos
`product`	Venta de uno o varios Products definidos.	`products` (IDs)
`custom`	Importe libre definido por el comerciante.	`amount`
`donation`	Donación libre: el cliente introduce el importe.	No se requiere ningún importe

Endpoints

Méthode	Endpoint	Description
POST	`/payment-links/`	Crear un enlace de pago
GET	`/payment-links/`	Listar los enlaces
GET	`/payment-links/{id}/`	Recuperar un enlace
PATCH	`/payment-links/{id}/`	Modificar un enlace
DELETE	`/payment-links/{id}/`	Eliminar definitivamente
POST	`/payment-links/{id}/archive/`	Archivar (desactivar sin eliminar)
POST	`/payment-links/{id}/restore/`	Restaurar un enlace archivado

¿Está clara esta introducción?

Esquema del objeto

ResponseObjeto PaymentLink

json

{
  "id": "link_xxxxxxxxxxxx",
  "object": "payment_link",
  "name": "Formation Excel Avancé",
  "url": "https://pay.sangho.ga/l/lnk_xxx",
  "payment_link_type": "product",
  "currency": "XAF",
  "amount": 25000,
  "products": ["prod_xxx"],
  "status": "active",
  "validity_type": "limited",
  "max_usage": 100,
  "usage_count": 12,
  "expires_at": "2026-12-31T23:59:59Z",
  "redirect_url": {
    "success": "https://boutique.com/merci",
    "cancel": "https://boutique.com/panier"
  },
  "payment_method_types": ["mobile_money", "bank_card"],
  "collect_customer_info": true,
  "allow_quantity": false,
  "livemode": true,
  "metadata": { "sku": "FORM-XLS-001" },
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Crear un Enlace de pago

POSTCuerpo de la solicitud

currencyRequis

stringISO 4217ex :XAF

Código de moneda ISO 4217 del enlace de pago.

payment_link_typeOptionnel

stringdéfaut :product

Tipo del enlace: product, custom o donation. Determina los campos requeridos y el comportamiento de la página de pago.

productsOptionnel

array[string]

Lista de ID de Products que se venderán mediante este enlace. Requerido si payment_link_type: product.

Puede asociar hasta 20 productos por enlace. Si solo hay un producto asociado, la página de pago muestra directamente sus detalles. Con varios productos, el comprador ve una lista de selección.

amountOptionnel

integercentimes

Importe fijo en céntimos. Requerido si payment_link_type: custom. Se ignora para los tipos product y donation.

nameOptionnel

string

Nombre que se muestra como título en la página de pago. Si no se indica y type: product, se utiliza el nombre del primer producto.

validity_typeOptionnel

stringdéfaut :unlimited

Política de validez del enlace.

Valores: unlimited (nunca caduca, nunca se limita), limited (limitado por max_usage y/o expires_at), one_time (utilizable una sola vez, equivalente a max_usage: 1).

max_usageOptionnel

integer

Número máximo de usos del enlace. Una vez alcanzado, la página de pago muestra un mensaje de no disponibilidad.

Activo únicamente si validity_type: limited. Cuenta un uso en cuanto se inicia un pago (estado processing), aunque el pago falle después. Útil para las ventas en cantidad limitada.

expires_atOptionnel

stringISO 8601ex :2026-12-31T23:59:59Z

Fecha y hora de caducidad del enlace. Después de esa fecha, la página de pago se desactiva.

Activo únicamente si validity_type: limited. El enlace puede caducar antes de max_usage si se definen ambos.

redirect_urlOptionnel

object

URL de redirección tras el pago. Objeto con las claves success (URL tras un pago correcto) y cancel (URL si el comprador abandona).

Si no se indica, Sangho muestra una página de confirmación genérica. Añada ?session_id={CHECKOUT_SESSION_ID} a su URL de éxito para recuperar los detalles en el servidor.

payment_method_typesOptionnel

array[string]

Métodos de pago permitidos en este enlace. Si se omite, se ofrecen todos los métodos activos de la App.

collect_customer_infoOptionnel

booleandéfaut :true

Si es true, la página de pago recoge los datos del comprador (nombre, correo electrónico) y crea automáticamente un Customer.

Desactivar esta opción (false) genera pagos anónimos: menos datos, pero una experiencia más rápida. No se recomienda si desea enviar recibos automáticos.

allow_quantityOptionnel

booleandéfaut :false

Si es true, muestra un selector de cantidad en la página de pago. El comprador puede elegir cuántas unidades comprar.

metadataOptionnel

object

Datos libres. Se devuelven en los webhooks payment_intent.succeeded vinculados a este enlace.

¿Están claros los parámetros del Enlace de pago?

Crear un enlace de producto

bash

curl -X POST https://api.sangho.ga/v1/payment-links/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "XAF",
    "payment_link_type": "product",
    "products": ["prod_xxx"],
    "name": "Formation Excel Avancé",
    "validity_type": "limited",
    "max_usage": 50,
    "expires_at": "2026-12-31T23:59:59Z",
    "redirect_url": {
      "success": "https://boutique.com/merci",
      "cancel": "https://boutique.com/catalogue"
    },
    "metadata": { "campaign": "newsletter-mars-2026" }
  }'

Response201 Created

El enlace está activo de inmediato. Comparta link.url con sus clientes.

json

{
  "id": "link_xxxxxxxxxxxx",
  "object": "payment_link",
  "name": "Formation Excel Avancé",
  "url": "https://pay.sangho.ga/l/lnk_xxx",
  "payment_link_type": "product",
  "currency": "XAF",
  "amount": 25000,
  "status": "active",
  "validity_type": "limited",
  "max_usage": 50,
  "usage_count": 0,
  "expires_at": "2026-12-31T23:59:59Z",
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z"
}

ResponseEnlace archivado

POST /payment-links/{id}/archive/ desactiva el enlace sin eliminarlo. La página de pago deja de ser accesible, pero el enlace sigue pudiéndose recuperar mediante GET.

El archivado es reversible mediante /restore/. La eliminación (DELETE) es definitiva.

json

{
  "id": "link_xxxxxxxxxxxx",
  "status": "archived",
  "updated_at": "2026-06-01T12:00:00Z"
}