Hosted Payment Page (HPP)

Die Hosted Payment Page (HPP) ist das PCI-DSS-konforme Zahlungsformular von Cost+. Sie ermöglicht es Ihnen, Zahlungen zu akzeptieren, ohne sensible Kartendaten auf Ihren eigenen Servern zu verarbeiten. Sie erstellen eine Bestellung über die API, leiten den Kunden auf die gehostete Seite weiter, und er kehrt nach der Zahlung auf Ihre Website zurück.

So funktioniert es

Ihr Server erstellt eine Bestellung durch Aufruf von POST /v1/orders/.
Die API gibt eine URL zurück, die auf die gehostete Zahlungsseite verweist.
Sie leiten den Kunden auf die Zahlungsseite weiter.
Der Kunde schließt die Zahlung auf der gehosteten Cost+-Seite ab.
Der Kunde wird zurück zu Ihrer return_url (oder failure_url bei fehlgeschlagenen Zahlungen) weitergeleitet.
Cost+ sendet eine Webhook-Benachrichtigung an Ihre webhook_url mit dem Bestellungsstatus.

Die gehostete Zahlungsseite ist vollständig PCI-DSS-konform. Sie müssen niemals rohe Kartennummern oder sensible Zahlungsdaten auf Ihren Servern verarbeiten.

Bestellung erstellen

Es gibt zwei Ansätze zur Nutzung der HPP:

Ansatz 1: Alle Zahlungsmethoden anzeigen (einfachster Weg)

Erstellen Sie eine Bestellung ohne Angabe von transactions. Die Antwort enthält eine order_url — der Kunde wird dorthin weitergeleitet und sieht alle für Ihr Konto aktivierten Zahlungsmethoden:

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://pay.costplus.online/43114fde.../select-payment-method/",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

Leiten Sie den Kunden auf die order_url weiter. Auf der gehosteten Seite werden alle aktivierten Zahlungsmethoden angezeigt.

Ansatz 2: Zahlungsmethoden vorauswählen

Erstellen Sie eine Bestellung mit einem transactions-Array, um zu steuern, welche Zahlungsmethoden angezeigt werden und in welcher Reihenfolge. Jede Transaktion enthält eine payment_method, und die Antwort gibt eine payment_url im Transaktionsobjekt zurück:

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://pay.costplus.online/4851e31c.../credit-card/d291f03f.../"
    }
  ]
}

Leiten Sie den Kunden auf die payment_url der Transaktion weiter.

Wenn Sie nur einen einzigen Eintrag im transactions-Array angeben, wird der Kunde direkt zu dieser Zahlungsmethode weitergeleitet, ohne einen Auswahlbildschirm zu sehen. Das flags-Array enthält "is-test" bei Verwendung eines Sandbox-API-Schlüssels.

Anfragefelder

Feld	Erforderlich	Beschreibung
`currency`	Ja	ISO 4217 Währungscode (z. B. `EUR`, `GBP`, `SEK`)
`amount`	Ja	Betrag in Cent. Zum Beispiel wird 12,95 EUR als `1295` dargestellt
`merchant_order_id`	Nein	Ihre eigene Referenz-ID für die Bestellung
`return_url`	Nein	URL, zu der der Kunde nach der Zahlung weitergeleitet wird (Standard für alle Status)
`failure_url`	Nein	URL, zu der der Kunde bei `cancelled`, `expired` oder `error` Status weitergeleitet wird (siehe Rückleitungs-URLs unten)
`locale`	Nein	Sprache der Zahlungsseite. Unterstützt: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	Nein	Beschreibung der Bestellung, die dem Kunden angezeigt wird
`payment_methods`	Nein	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`	Nein	URL für Statusänderungsbenachrichtigungen
`expiration_period`	Nein	ISO 8601 Dauer für den Ablauf der Bestellung. Standard ist `PT30M` (30 Minuten)

Das amount-Feld ist immer in der kleinsten Währungseinheit (Cent). 1295 zu übergeben bedeutet 12,95 in der angegebenen Währung. 1295.00 oder 12.95 zu übergeben führt zu einem Fehler oder einer falschen Abbuchung.

Mehrere Zahlungsmethoden

Um mehrere bestimmte Zahlungsmethoden anzubieten, fügen Sie mehrere Einträge zum transactions-Array hinzu. Die Reihenfolge auf der gehosteten Seite entspricht der Array-Reihenfolge:

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

Rückleitungs-URLs

Nach der Zahlung wird der Kunde basierend auf dem Bestellungsstatus und den von Ihnen angegebenen URLs weitergeleitet:

Wenn sowohl return_url als auch failure_url gesetzt sind:
- cancelled, expired oder error → Kunde wird zu failure_url weitergeleitet
- Alle anderen Status → Kunde wird zu return_url weitergeleitet
Wenn nur return_url gesetzt ist:
- Alle Status → Kunde wird zu return_url weitergeleitet

Verwenden Sie failure_url, um eine Wiederholungs- oder Support-Seite für fehlgeschlagene Zahlungen anzuzeigen, während return_url eine Bestellbestätigung zeigt. Wenn Sie nur ein Ziel benötigen, reicht return_url allein aus.

Verhalten der Abbrechen-Schaltfläche

Die gehostete Zahlungsseite enthält eine Abbrechen-Schaltfläche. Wenn der Kunde darauf klickt, wird er zu failure_url (falls angegeben) oder return_url weitergeleitet. Der Bestellungsstatus wechselt zu cancelled. Verifizieren Sie den Bestellungsstatus immer über die API oder Webhooks, anstatt sich allein auf die Weiterleitung zu verlassen.