Hostowana strona płatności (HPP)

Hostowana strona płatności (HPP) to zgodny z PCI DSS formularz płatności Cost+. Umożliwia przyjmowanie płatności bez obsługi wrażliwych danych kart na własnych serwerach. Tworzysz zamówienie przez API, przekierowujesz klienta na hostowaną stronę, a po płatności wraca on na Twoją witrynę.

Jak to działa

Twój serwer tworzy zamówienie, wywołując POST /v1/orders/.
API zwraca URL wskazujący na hostowaną stronę płatności.
Przekierowujesz klienta na stronę płatności.
Klient realizuje płatność na hostowanej stronie Cost+.
Klient jest przekierowywany z powrotem na Twój return_url (lub failure_url w przypadku nieudanych płatności).
Cost+ wysyła powiadomienie webhook na Twój webhook_url ze statusem zamówienia.

Hostowana strona płatności jest w pełni zgodna z PCI DSS. Nigdy nie musisz obsługiwać surowych numerów kart ani wrażliwych danych płatniczych na swoich serwerach.

Tworzenie zamówienia

Istnieją dwa podejścia do korzystania z HPP:

Podejście 1: Pokaż wszystkie metody płatności (najprostsze)

Utwórz zamówienie bez określania transactions. Odpowiedź zawiera order_url — klient jest tam przekierowywany i widzi wszystkie metody płatności włączone dla Twojego konta:

Żądanie

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

Odpowiedź

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

Przekieruj klienta na order_url. Na hostowanej stronie wyświetlane są wszystkie włączone metody płatności.

Podejście 2: Wstępny wybór metod płatności

Utwórz zamówienie z tablicą transactions, aby kontrolować, które metody płatności się pojawią i w jakiej kolejności. Każda transakcja zawiera payment_method, a odpowiedź zwraca payment_url wewnątrz obiektu transakcji:

Żądanie

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

Odpowiedź

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

Przekieruj klienta na payment_url z transakcji.

Jeśli podasz tylko jeden wpis w tablicy transactions, klient zostanie przeniesiony bezpośrednio do tej metody płatności bez ekranu wyboru. Tablica flags zawiera "is-test" przy użyciu testowego klucza API.

Pola żądania

Pole	Wymagane	Opis
`currency`	Tak	Kod waluty ISO 4217 (np. `EUR`, `GBP`, `SEK`)
`amount`	Tak	Kwota w groszach/centach. Na przykład 12,95 EUR jest reprezentowane jako `1295`
`merchant_order_id`	Nie	Twój własny identyfikator referencyjny zamówienia
`return_url`	Nie	URL do przekierowania klienta po płatności (domyślny dla wszystkich statusów)
`failure_url`	Nie	URL do przekierowania klienta w przypadku statusu `cancelled`, `expired` lub `error` (patrz Adresy URL powrotu poniżej)
`locale`	Nie	Język strony płatności. Obsługiwane: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	Nie	Opis zamówienia wyświetlany klientowi
`payment_methods`	Nie	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`	Nie	URL do otrzymywania powiadomień o zmianie statusu
`expiration_period`	Nie	Czas ważności zamówienia w formacie ISO 8601. Domyślnie `PT30M` (30 minut)

Pole amount jest zawsze podawane w najmniejszej jednostce waluty (groszach/centach). Podanie 1295 oznacza 12,95 w danej walucie. Podanie 1295.00 lub 12.95 spowoduje błąd lub nieprawidłowe obciążenie.

Wiele metod płatności

Aby zaoferować wiele konkretnych metod płatności, dodaj wiele wpisów do tablicy transactions. Kolejność na hostowanej stronie odpowiada kolejności w tablicy:

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

Adresy URL powrotu

Po płatności klient jest przekierowywany w zależności od statusu zamówienia i podanych adresów URL:

Gdy ustawiono zarówno return_url, jak i failure_url:
- cancelled, expired lub error → klient jest przekierowywany na failure_url
- Wszystkie inne statusy → klient jest przekierowywany na return_url
Gdy ustawiono tylko return_url:
- Wszystkie statusy → klient jest przekierowywany na return_url

Użyj failure_url, aby wyświetlić stronę z możliwością ponowienia próby lub kontaktu z pomocą techniczną w przypadku nieudanych płatności, a return_url do wyświetlenia potwierdzenia zamówienia. Jeśli potrzebujesz tylko jednego celu, sam return_url wystarczy.

Zachowanie przycisku anulowania

Hostowana strona płatności zawiera przycisk anulowania. Gdy klient go kliknie, zostanie przekierowany na failure_url (jeśli podano) lub return_url. Status zamówienia zmieni się na cancelled. Zawsze weryfikuj status zamówienia przez API lub webhooki, zamiast polegać wyłącznie na przekierowaniu.

Powiązane punkty końcowe

Utwórz zamówienie — utwórz zamówienie płatności i otrzymaj payment_url
Pobierz zamówienie — sprawdź status zamówienia po płatności

On this page