Hosted Payment Page (HPP)

The Hosted Payment Page (HPP) is Cost+'s PCI DSS compliant payment form. It allows you to accept payments without handling sensitive card data on your own servers. You create an order via the API, redirect the customer to the hosted page, and they return to your site after payment.

How It Works

Your server creates an order by calling POST /v1/orders/.
The API returns a URL pointing to the hosted payment page.
You redirect the customer to the payment page.
The customer completes payment on the Cost+ hosted page.
The customer is redirected back to your return_url (or failure_url for failed payments).
Cost+ sends a webhook notification to your webhook_url with the order status.

The hosted payment page is fully PCI DSS compliant. You never need to handle raw card numbers or sensitive payment data on your servers.

Creating an Order

There are two approaches to using the HPP:

Approach 1: Show All Payment Methods (Simplest)

Create an order without specifying transactions. The response includes an order_url — the customer is redirected there and sees all payment methods enabled for your account:

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"
}

Redirect the customer to the order_url. On the hosted page, all enabled payment methods are shown.

Approach 2: Pre-select Payment Methods

Create an order with a transactions array to control which payment methods appear and in what order. Each transaction includes a payment_method, and the response returns a payment_url inside the transaction object:

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.../"
    }
  ]
}

Redirect the customer to the payment_url from the transaction.

If you provide only a single entry in the transactions array, the customer is taken directly to that payment method without seeing a selection screen. The flags array contains "is-test" when using a sandbox API key.

Request Fields

Field	Required	Description
`currency`	Yes	ISO 4217 currency code (e.g., `EUR`, `GBP`, `SEK`)
`amount`	Yes	Amount in cents. For example, 12.95 EUR is represented as `1295`
`merchant_order_id`	No	Your own reference ID for the order
`return_url`	No	URL to redirect the customer after payment (default for all statuses)
`failure_url`	No	URL to redirect the customer on `cancelled`, `expired`, or `error` status (see Return URLs below)
`locale`	No	Language for the payment page. Supported: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	No	Description of the order, shown to the customer
`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 to receive status change notifications
`expiration_period`	No	ISO 8601 duration for order expiry. Default is `PT30M` (30 minutes)

The amount field is always in the smallest currency unit (cents). Passing 1295 means 12.95 in the given currency. Passing 1295.00 or 12.95 will result in an error or an incorrect charge.

Multiple Payment Methods

There are two ways to control which payment methods appear on the hosted page:

Option A — payment_methods (single filter). Pass a single-element array to restrict the order to one payment method. Omit the field entirely to show all methods enabled for your account.

Option B — transactions array (recommended for multiple methods). Add one entry per payment method. Each transaction gets its own payment_url, and the methods appear in array order on the hosted page:

"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.

Return URLs

After payment, the customer is redirected based on the order status and which URLs you provided:

When both return_url and failure_url are set:
- cancelled, expired, or error → customer is redirected to failure_url
- All other statuses → customer is redirected to return_url
When only return_url is set:
- All statuses → customer is redirected to return_url

Use failure_url to show a retry or support page for failed payments, while return_url shows an order confirmation. If you only need one destination, return_url alone is sufficient.

Cancel Button Behavior

The hosted payment page includes a cancel button. When the customer clicks it, they are redirected to failure_url (if provided) or return_url. The order status will transition to cancelled. Always verify the order status via the API or webhooks rather than relying on the redirect alone.

Create Order — create a payment order and receive the payment_url
Get Order — check the order status after payment

On this page