Hosted Payment Page (HPP)

De Hosted Payment Page (HPP) is het PCI DSS-conforme betalingsformulier van Cost+. Hiermee kunt u betalingen accepteren zonder gevoelige kaartgegevens op uw eigen servers te verwerken. U maakt een bestelling aan via de API, verwijst de klant door naar de gehoste pagina en deze keert na betaling terug naar uw site.

Hoe het werkt

Uw server maakt een bestelling aan door POST /v1/orders/ aan te roepen.
De API retourneert een URL naar de hosted payment page.
U verwijst de klant door naar de betaalpagina.
De klant voltooit de betaling op de gehoste pagina van Cost+.
De klant wordt teruggeleid naar uw return_url (of failure_url bij mislukte betalingen).
Cost+ stuurt een webhookmelding naar uw webhook_url met de bestellingsstatus.

De hosted payment page is volledig PCI DSS-conform. U hoeft nooit onbewerkte kaartnummers of gevoelige betalingsgegevens op uw servers te verwerken.

Een bestelling aanmaken

Er zijn twee benaderingen voor het gebruik van de HPP:

Benadering 1: Alle betaalmethoden tonen (eenvoudigst)

Maak een bestelling aan zonder transactions op te geven. De respons bevat een order_url — de klant wordt daarnaartoe doorverwezen en ziet alle betaalmethoden die voor uw account zijn ingeschakeld:

Verzoek

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

Respons

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

Verwijs de klant door naar de order_url. Op de gehoste pagina worden alle ingeschakelde betaalmethoden getoond.

Benadering 2: Betaalmethoden vooraf selecteren

Maak een bestelling aan met een transactions-array om te bepalen welke betaalmethoden verschijnen en in welke volgorde. Elke transactie bevat een payment_method, en de respons retourneert een payment_url in het transactieobject:

Verzoek

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

Respons

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

Verwijs de klant door naar de payment_url uit de transactie.

Als u slechts een enkele vermelding in de transactions-array opgeeft, wordt de klant rechtstreeks naar die betaalmethode geleid zonder een selectiescherm te zien. De flags-array bevat "is-test" bij gebruik van een sandbox API-sleutel.

Verzoeksvelden

Veld	Vereist	Beschrijving
`currency`	Ja	ISO 4217-valutacode (bijv. `EUR`, `GBP`, `SEK`)
`amount`	Ja	Bedrag in centen. Bijvoorbeeld 12,95 EUR wordt weergegeven als `1295`
`merchant_order_id`	Nee	Uw eigen referentie-ID voor de bestelling
`return_url`	Nee	URL om de klant naartoe te verwijzen na betaling (standaard voor alle statussen)
`failure_url`	Nee	URL om de klant naartoe te verwijzen bij status `cancelled`, `expired` of `error` (zie Retour-URL's hieronder)
`locale`	Nee	Taal voor de betaalpagina. Ondersteund: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	Nee	Beschrijving van de bestelling, getoond aan de klant
`payment_methods`	Nee	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`	Nee	URL om statuswijzigingsmeldingen te ontvangen
`expiration_period`	Nee	ISO 8601-duur voor het verlopen van de bestelling. Standaard is `PT30M` (30 minuten)

Het veld amount is altijd in de kleinste valuta-eenheid (centen). Het doorgeven van 1295 betekent 12,95 in de opgegeven valuta. Het doorgeven van 1295.00 of 12.95 resulteert in een fout of een onjuist bedrag.

Meerdere betaalmethoden

Om meerdere specifieke betaalmethoden aan te bieden, voegt u meerdere vermeldingen toe aan de transactions-array. De volgorde op de gehoste pagina komt overeen met de arrayvolgorde:

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

Retour-URL's

Na betaling wordt de klant doorverwezen op basis van de bestellingsstatus en de URL's die u heeft opgegeven:

Wanneer zowel return_url als failure_url zijn ingesteld:
- cancelled, expired of error → klant wordt doorverwezen naar failure_url
- Alle andere statussen → klant wordt doorverwezen naar return_url
Wanneer alleen return_url is ingesteld:
- Alle statussen → klant wordt doorverwezen naar return_url

Gebruik failure_url om een pagina voor opnieuw proberen of ondersteuning te tonen bij mislukte betalingen, terwijl return_url een orderbevestiging toont. Als u slechts een bestemming nodig heeft, is return_url alleen voldoende.

Gedrag annuleerknop

De hosted payment page bevat een annuleerknop. Wanneer de klant hierop klikt, wordt deze doorverwezen naar failure_url (indien opgegeven) of return_url. De bestellingsstatus verandert naar cancelled. Verifieer altijd de bestellingsstatus via de API of webhooks in plaats van alleen op de doorverwijzing te vertrouwen.

Gerelateerde eindpunten

Bestelling aanmaken — een betalingsbestelling aanmaken en de payment_url ontvangen
Bestelling ophalen — de bestellingsstatus controleren na betaling

On this page