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://api.costplus.online/pay/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://api.costplus.online/pay/4851e31c.../select-payment-method/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`	Sí	Importe en la unidad menor ISO 4217 de la moneda. 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	Filtrar a un único método de pago (por ejemplo, `["credit-card"]`). Omitir para mostrar todos los métodos habilitados. Para múltiples métodos específicos, use la matriz `transactions` en su lugar
`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 es siempre un número entero en la unidad menor ISO 4217 de la moneda. Para EUR, 1295 significa 12,95 EUR; Las monedas con cero y tres decimales utilizan su propio exponente ISO 4217. Pasar un valor decimal como 1295.00 o 12.95 dará como resultado un error o un cargo incorrecto.

Multiples metodos de pago

Hay dos formas de controlar qué métodos de pago aparecen en la página alojada:

Opción A: payment_methods (filtro único). Pase una matriz de un solo elemento para restringir el pedido a un método de pago. Omita el campo por completo para mostrar todos los métodos habilitados para su cuenta.

Opción B: matriz transactions (recomendada para múltiples métodos). Agregue una entrada por método de pago. Cada transacción obtiene su propio payment_url y los métodos aparecen en orden de matriz en la página alojada:

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

El campo payment_methods en pedidos acepta como máximo un valor. Para ofrecer múltiples métodos específicos, utilice siempre la matriz transactions. Si necesita un enlace reutilizable con múltiples métodos de pago, considere Enlaces de pago, que admiten una matriz payment_methods verdadera.

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

Pagina de pago alojada (HPP)

On this page