Pagina de pago alojada (HPP)

La pagina de pago alojada (HPP) es el formulario de pago compatible con PCI DSS de Cost+. Te permite aceptar pagos sin manejar datos sensibles de tarjeta en tus propios servidores. Creas un pedido a traves de la API, rediriges al cliente a la pagina alojada, y este regresa a tu sitio despues del pago.

Como funciona

Tu servidor crea un pedido llamando a POST /v1/orders/.
La API devuelve una URL que apunta a la pagina de pago alojada.
Rediriges al cliente a la pagina de pago.
El cliente completa el pago en la pagina alojada de Cost+.
El cliente es redirigido de vuelta a tu return_url (o failure_url para pagos fallidos).
Cost+ envia una notificacion webhook a tu webhook_url con el estado del pedido.

La pagina de pago alojada es totalmente compatible con PCI DSS. Nunca necesitas manejar numeros de tarjeta ni datos de pago sensibles en tus servidores.

Crear un pedido

Existen dos enfoques para usar el HPP:

Enfoque 1: Mostrar todos los metodos de pago (mas sencillo)

Crea un pedido sin especificar transactions. La respuesta incluye un order_url — el cliente es redirigido alli y ve todos los metodos de pago habilitados en tu cuenta:

Request

{
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-order-id-1",
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

Response

{
  "id": "43114fde-da30-4115-8004-b7f808f9b25c",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "order_url": "https://pay.costplus.online/43114fde.../select-payment-method/",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

Redirige al cliente al order_url. En la pagina alojada se muestran todos los metodos de pago habilitados.

Enfoque 2: Preseleccionar metodos de pago

Crea un pedido con un array transactions para controlar que metodos de pago aparecen y en que orden. Cada transaccion incluye un payment_method, y la respuesta devuelve un payment_url dentro del objeto de transaccion:

Request

{
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-order-id-1",
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    { "payment_method": "credit-card" }
  ]
}

Response

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "payment_url": "https://pay.costplus.online/4851e31c.../credit-card/d291f03f.../"
    }
  ]
}

Redirige al cliente al payment_url de la transaccion.

Si proporcionas solo una entrada en el array transactions, el cliente es llevado directamente a ese metodo de pago sin ver una pantalla de seleccion. El array flags contiene "is-test" cuando se usa una clave API de sandbox.

Campos de la solicitud

Campo	Obligatorio	Descripcion
`currency`	Si	Codigo de moneda ISO 4217 (ej., `EUR`, `GBP`, `SEK`)
`amount`	Si	Importe en centimos. Por ejemplo, 12,95 EUR se representa como `1295`
`merchant_order_id`	No	Tu propio ID de referencia para el pedido
`return_url`	No	URL para redirigir al cliente despues del pago (predeterminada para todos los estados)
`failure_url`	No	URL para redirigir al cliente en estado `cancelled`, `expired` o `error` (ver URLs de retorno abajo)
`locale`	No	Idioma de la pagina de pago. Soportados: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	No	Descripcion del pedido, mostrada al cliente
`payment_methods`	No	Filter to a single payment method (e.g. `["credit-card"]`). Omit to show all enabled methods. For multiple specific methods, use the `transactions` array instead
`webhook_url`	No	URL para recibir notificaciones de cambio de estado
`expiration_period`	No	Duracion ISO 8601 para la caducidad del pedido. Por defecto `PT30M` (30 minutos)

El campo amount siempre esta en la unidad monetaria mas pequena (centimos). Pasar 1295 significa 12,95 en la moneda dada. Pasar 1295.00 o 12.95 resultara en un error o un cargo incorrecto.

Multiples metodos de pago

Para ofrecer multiples metodos de pago especificos, agrega multiples entradas al array transactions. El orden en la pagina alojada coincide con el orden del array:

"transactions": [
  { "payment_method": "credit-card" },
  { "payment_method": "apple-pay" }
]

The payment_methods field on orders accepts at most one value. To offer multiple specific methods, always use the transactions array. If you need a reusable link with multiple payment methods, consider Payment Links instead, which support a true payment_methods array.

URLs de retorno

Despues del pago, el cliente es redirigido segun el estado del pedido y las URLs que proporcionaste:

Cuando se establecen tanto return_url como failure_url:
- cancelled, expired o error → el cliente es redirigido a failure_url
- Todos los demas estados → el cliente es redirigido a return_url
Cuando solo se establece return_url:
- Todos los estados → el cliente es redirigido a return_url

Usa failure_url para mostrar una pagina de reintento o soporte para pagos fallidos, mientras que return_url muestra una confirmacion de pedido. Si solo necesitas un destino, return_url solo es suficiente.

Comportamiento del boton Cancelar

La pagina de pago alojada incluye un boton de cancelar. Cuando el cliente lo pulsa, es redirigido a failure_url (si se proporciono) o return_url. El estado del pedido cambiara a cancelled. Verifica siempre el estado del pedido a traves de la API o webhooks en lugar de depender unicamente de la redireccion.

Endpoints relacionados

Crear pedido — crear un pedido de pago y recibir el payment_url
Obtener pedido — verificar el estado del pedido despues del pago

On this page