Crear links de pago

Un link de pago es el cobro que compartes con tu pagador. Necesitas un token de tu comercio.

Crear un link

POST /api/payment-links — requiere concept, description y amount; el resto tiene valor por defecto.

curl -s -X POST "$API/api/payment-links" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "payment_link",
      "attributes": {
        "concept": "Pedido 1042",
        "description": "Compra en línea — pedido 1042",
        "reference": "pedido-1042",
        "currency": "COP",
        "amount": "50000",
        "vat_enabled": false,
        "max_payment_count": 1,
        "expires_at": "2026-12-31T23:59:59Z",
        "accepted_payment_methods": ["pse", "card"],
        "customer_data_policy": "hidden",
        "shipping_data_policy": "hidden"
      }
    }
  }'

La respuesta (201) trae el link completo, con su url pública (la que abre el pagador) y el total que pagará:

{
  "data": {
    "type": "payment_link",
    "id": "ac1e5ebc-6e56-4a47-9747-0372cac275e9",
    "attributes": {
      "token": "D8bwL5EqTqOMOtO-IhIXm5NAEwTDMElp",
      "concept": "Pedido 1042",
      "description": "Compra en línea — pedido 1042",
      "reference": "pedido-1042",
      "currency": "COP",
      "amount": 50000,
      "vat_enabled": false,
      "vat_rate": 19,
      "consumption_tax_enabled": false,
      "consumption_tax_rate": 10,
      "tip_amount": 0,
      "extra_label": null,
      "extra_value": 0,
      "max_payment_count": 1,
      "expires_at": "2026-12-31T23:59:59+00:00",
      "confirmation_url": null,
      "thank_you_url": null,
      "images": [],
      "spec_document_url": null,
      "requires_shipping": false,
      "customer_data_policy": "hidden",
      "accepted_payment_methods": ["cuentas_crezcamos", "pse", "card"],
      "shipping_data_policy": "hidden",
      "state": "active",
      "total": 50000,
      "url": "https://pay.example.com/l/D8bwL5EqTqOMOtO-IhIXm5NAEwTDMElp"
    }
  },
  "meta": null
}

Observa

• Los importes de respuesta son números (50000); en la petición amount acepta número o texto.
• accepted_payment_methods siempre incluye cuentas_crezcamos, aunque no lo pidas (regla de la pasarela).
• total es lo que paga el pagador: suma IVA, impuesto al consumo, propina y extra si están activos.

Atributos que más usarás

Atributo	Por defecto	Descripción
amount	—	Valor base. El total que paga el pagador (total) suma IVA (activo por defecto), impuesto al consumo, propina y extra.
currency	COP	PSE solo admite COP.
reference	el token	Tu referencia del pedido. Aparece en el pago y en los webhooks.
vat_enabled / vat_rate	true / 19	El IVA viene activado por defecto al 19 %: un amount de 30000 produce un total de 35700. Envía "vat_enabled": false si tu valor ya incluye IVA o no aplica. vat_rate es un porcentaje entero.
max_payment_count	1	Cuántas veces se puede pagar. Con más de uno el link es reutilizable.
expires_at	—	Vencimiento (ISO 8601). Pasada esa fecha el link deja de estar disponible.
accepted_payment_methods	["cuentas_crezcamos"]	Medios que ofrece la página: card, pse, cuentas_crezcamos, bre_b. cuentas_crezcamos se agrega siempre.
customer_data_policy / shipping_data_policy	hidden	hidden, optional o required: qué pide el checkout al pagador.
confirmation_url / thank_you_url	—	Dónde enviar al pagador tras pagar (no es una confirmación de pago; ver abajo).

Reutilización y estado

El estado del link es uno solo por link. Un link de varios usos que ya recibió un pago puede pasar a paid y dejar de estar disponible para los siguientes pagadores. Si cobras pedidos distintos, crea un link por pedido.

Listar, consultar y revocar

curl -s "$API/api/payment-links"            -H "Authorization: Bearer $TOKEN"   # lista
curl -s "$API/api/payment-links/$LINK_ID"   -H "Authorization: Bearer $TOKEN"   # detalle
curl -s -X PATCH "$API/api/payment-links/$LINK_ID/revoke"     -H "Authorization: Bearer $TOKEN"   # el pagador deja de poder usarlo
curl -s -X PATCH "$API/api/payment-links/$LINK_ID/reactivate" -H "Authorization: Bearer $TOKEN"

Revocar un link en un estado que no lo admite responde 409.

Cómo sabes que se pagó

No consultes el link en bucle ni confíes en que el pagador vuelva a tu sitio. Registra un webhook: la pasarela te envía payment.approved o payment.rejected firmado.

nota

Hoy no existe una API pública para consultar un pago. El resultado se conoce por webhook; ver huecos conocidos.