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://api.costplus.online/pay/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://api.costplus.online/pay/4851e31c.../select-payment-method/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 de kleine eenheid ISO 4217 van de valuta. 12,95 EUR wordt bijvoorbeeld 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 op één betaalmethode (bijvoorbeeld `["credit-card"]`). Laat dit achterwege om alle ingeschakelde methoden weer te geven. Voor meerdere specifieke methoden gebruikt u in plaats daarvan de array `transactions`
`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 een geheel getal in de secundaire eenheid ISO 4217 van de valuta. Voor EUR betekent 1295 12,95 EUR; Valuta's met nul en drie decimalen gebruiken hun eigen ISO 4217-exponent. Het doorgeven van een decimale waarde zoals 1295.00 of 12.95 zal resulteren in een fout of een onjuiste afschrijving.

Meerdere betaalmethoden

Er zijn twee manieren om te bepalen welke betaalmethoden op de gehoste pagina verschijnen:

Optie A — payment_methods (enkel filter). Geef een array met één element door om de bestelling te beperken tot één betaalmethode. Laat het veld geheel weg om alle methoden weer te geven die voor uw account zijn ingeschakeld.

Optie B — transactions-array (aanbevolen voor meerdere methoden). Voeg één item per betaalmethode toe. Elke transactie krijgt zijn eigen payment_url en de methoden verschijnen in arrayvolgorde op de gehoste pagina:

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

Het veld payment_methods op bestellingen accepteert maximaal één waarde. Als u meerdere specifieke methoden wilt aanbieden, gebruikt u altijd de array transactions. Als je een herbruikbare link met meerdere betaalmethoden nodig hebt, overweeg dan Betaallinks, die een echte payment_methods-array ondersteunen.

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

Hosted Payment Page (HPP)

On this page