Enlaces de pago

Los enlaces de pago son URLs reutilizables que permiten a los clientes pagar un pedido. A diferencia de los pedidos estandar que expiran despues de un unico intento fallido, los enlaces de pago soportan multiples intentos de reintento, lo que los hace ideales para facturas, pagos por correo electronico y escenarios donde el cliente puede no pagar de inmediato.

Caracteristicas principales

Reutilizables: Los clientes pueden reintentar el pago hasta 25 veces si los intentos anteriores fallan.
Larga duracion: La expiracion predeterminada es de 30 dias (configurable via expiration_period).
Compartibles: Envia el enlace por correo electronico, SMS, chat o insertalo en tu sitio web.

Crear un enlace de pago

Envia una solicitud POST a /v1/paymentlinks/:

POST /v1/paymentlinks/

curl -X POST https://api.costplus.online/v1/paymentlinks/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "invoice-1234",
    "amount": 995,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

La respuesta incluye el payment_url para compartir con el cliente y un id unico para seguimiento:

Response (201 Created)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "new",
  "reason": "Payment Link was created, not yet visited",
  "orders": {},
  "created": "2026-01-15T12:00:00.000000Z"
}

Guarda el id — lo usaras para consultar el estado del enlace de pago mas adelante.

Campos obligatorios

Campo	Descripcion
`merchant_order_id`	Tu propio ID de referencia para el enlace de pago
`amount`	Importe en centimos (ej., 9,95 EUR = `995`)
`currency`	Codigo de moneda ISO 4217 (ej., `EUR`, `GBP`)

Campos opcionales

Campo	Descripcion
`description`	Descripcion mostrada al cliente
`expiration_period`	Duracion ISO 8601. Por defecto `P30D` (30 dias)
`return_url`	URL para redirigir al cliente despues de un pago exitoso
`failure_url`	URL para redirigir al cliente en caso de cancelacion, expiracion o error
`webhook_url`	URL para recibir notificaciones de cambio de estado
`customer`	Objeto con datos del cliente (nombre, correo electronico, etc.)

Si proporcionas tanto return_url como failure_url, los clientes son redirigidos a failure_url cuando el estado del pedido es cancelled, expired o error. De lo contrario, todas las redirecciones van a return_url.

Consultar un enlace de pago

Envia una solicitud GET a /v1/paymentlinks/{id}/ usando el id del enlace de pago de la respuesta de creacion:

GET /v1/paymentlinks/{id}/

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/

La respuesta incluye el estado actual y referencias a todos los pedidos creados desde el enlace, agrupados por su estado:

Response (completed example)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "completed",
  "reason": "Completed",
  "completed": "2026-01-15T12:05:30.123456+00:00",
  "completed_order_id": "3bb663cc-2a20-400d-8bf6-18d9695d0c66",
  "orders": {
    "error": ["0d79014c-0aaa-4fd6-87c5-c8cfa5f5ac69"],
    "completed": ["3bb663cc-2a20-400d-8bf6-18d9695d0c66"]
  }
}

En este ejemplo, el cliente realizo un intento fallido (pedido 0d79014c... en estado error) antes de tener exito (pedido 3bb663cc... en estado completed). Puedes obtener los detalles completos de cualquier pedido mediante GET /v1/orders/{order_id}/.

Estados del enlace de pago

Estado	Descripcion
`new`	El enlace ha sido creado pero no se ha realizado ningun intento de pago.
`processing`	Un intento de pago esta actualmente en curso.
`all_unsuccessful`	Todos los intentos de pago hasta ahora han fallado. El cliente aun puede reintentar (hasta 25 intentos).
`completed`	El pago fue exitoso. El enlace ya no esta activo.
`expired`	El enlace ha expirado antes de que se realizara un pago exitoso.

El estado all_unsuccessful no es un estado final. El cliente aun puede intentar pagar de nuevo hasta que el pago tenga exito, se alcance el numero maximo de intentos (25) o el enlace expire.

Una vez que un enlace de pago alcanza el estado completed o expired, no puede volver a utilizarse. Crea un nuevo enlace de pago si el cliente necesita pagar de nuevo.

Flujo de trabajo de ejemplo

Crea un enlace de pago mediante POST /v1/paymentlinks/.
Comparte el payment_url devuelto con tu cliente (ej., por correo electronico, SMS o factura).
El cliente abre el enlace y completa el pago.
Cost+ envia un webhook a tu webhook_url cuando cambia el estado.
Verifica el estado del enlace de pago mediante GET /v1/paymentlinks/{id}/.
Procesa el pedido una vez que el estado sea completed.

Endpoints relacionados

Crear enlace de pago — crear un enlace de pago reutilizable
Obtener enlace de pago — consultar el estado actual de un enlace de pago

On this page