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 payment_url pointing to the hosted payment page.
You redirect the customer to the payment_url.
The customer completes payment on the Cost+ hosted page.
The customer is redirected back to your return_url.
Cost+ sends a webhook notification to your webhook_url with the order status.

[!NOTE] 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

Send a POST request to /v1/orders/ with the order details:

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

Response

The API responds with the full order object, including the payment_url you need to redirect the customer to:

{
  "id": "b9ae6...",
  "project_id": "...",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:00:00.000000+00:00",
  "completed": null,
  "expiration_period": "PT30M",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://pay.costplus.com/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [],
  "flags": ["is-test"]
}

[!TIP] The flags array contains "is-test" when the order was created using test API credentials. Use this to verify you are operating in the correct environment.

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 to after a successful payment
`failure_url`	No	URL to redirect the customer to if the payment fails
`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 which payment methods are available on the hosted page
`webhook_url`	No	URL to receive status change notifications
`expiration_period`	No	ISO 8601 duration for order expiry. Default is `PT30M` (30 minutes)

[!WARNING] 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.

Filtering Payment Methods

You can control which payment methods appear on the hosted payment page by adding a transactions array to the order request. Each entry specifies a payment method:

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

The order of payment methods on the hosted page is determined by the order of the items in the transactions array. In the example above, credit card will appear first, followed by Apple Pay.

[!TIP] If you provide only a single entry in the transactions array, the customer will be taken directly to that payment method without seeing a selection screen.

Cancel Button Behavior

The hosted payment page includes a cancel button. When the customer clicks it, they are redirected back to the return_url. The order status will remain new or transition to cancelled, depending on the timing. Always verify the order status via the API or webhooks rather than relying on the redirect alone.