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://api.costplus.online/pay/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://api.costplus.online/pay/4851e31c.../select-payment-method/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 der Nebeneinheit ISO 4217 der Währung. Beispielsweise 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	Filtern Sie nach einer einzelnen Zahlungsmethode (z. B. `["credit-card"]`). Lassen Sie es weg, um alle aktivierten Methoden anzuzeigen. Verwenden Sie für mehrere spezifische Methoden stattdessen das Array `transactions`
`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 Feld amount ist immer eine Ganzzahl in der Nebeneinheit ISO 4217 der Währung. Für EUR bedeutet 1295 12,95 EUR; Null- und Drei-Dezimal-Währungen verwenden ihren eigenen ISO 4217-Exponenten. Die Übergabe eines Dezimalwerts wie 1295.00 oder 12.95 führt zu einem Fehler oder einer falschen Gebühr.

Mehrere Zahlungsmethoden

Es gibt zwei Möglichkeiten zu steuern, welche Zahlungsmethoden auf der gehosteten Seite angezeigt werden:

Option A – payment_methods (Einzelfilter). Übergeben Sie ein Array mit einem Element, um die Bestellung auf eine Zahlungsmethode zu beschränken. Lassen Sie das Feld vollständig weg, um alle für Ihr Konto aktivierten Methoden anzuzeigen.

Option B – transactions-Array (empfohlen für mehrere Methoden). Fügen Sie einen Eintrag pro Zahlungsmethode hinzu. Jede Transaktion erhält ihren eigenen payment_url und die Methoden erscheinen in Array-Reihenfolge auf der gehosteten Seite:

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

Das Feld payment_methods bei Bestellungen akzeptiert höchstens einen Wert. Um mehrere spezifische Methoden anzubieten, verwenden Sie immer das Array transactions. Wenn Sie einen wiederverwendbaren Link mit mehreren Zahlungsmethoden benötigen, sollten Sie stattdessen Zahlungslinks in Betracht ziehen, die ein echtes payment_methods-Array unterstützen.

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.