Hostovaná platební stránka (HPP)

Hostovaná platební stránka (HPP) je platební formulář Cost+ vyhovující standardu PCI DSS. Umožňuje přijímat platby bez manipulace s citlivými údaji karet na vašich vlastních serverech. Vytvoříte objednávku přes API, přesměrujete zákazníka na hostovanou stránku a ten se po platbě vrátí na váš web.

Jak to funguje

Váš server vytvoří objednávku voláním POST /v1/orders/.
API vrátí URL směřující na hostovanou platební stránku.
Přesměrujete zákazníka na platební stránku.
Zákazník dokončí platbu na hostované stránce Cost+.
Zákazník je přesměrován zpět na vaši return_url (nebo failure_url v případě neúspěšné platby).
Cost+ odešle webhookovou notifikaci na vaši webhook_url se stavem objednávky.

Hostovaná platební stránka je plně v souladu s PCI DSS. Nikdy nemusíte pracovat s nezašifrovanými čísly karet ani citlivými platebními daty na svých serverech.

Vytvoření objednávky

Existují dva přístupy k použití HPP:

Přístup 1: Zobrazit všechny platební metody (nejjednodušší)

Vytvořte objednávku bez uvedení transactions. Odpověď obsahuje order_url — zákazník je přesměrován tam a vidí všechny platební metody povolené pro váš účet:

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

Přesměrujte zákazníka na order_url. Na hostované stránce se zobrazí všechny povolené platební metody.

Přístup 2: Předvýběr platebních metod

Vytvořte objednávku s polem transactions pro kontrolu, které platební metody se zobrazí a v jakém pořadí. Každá transakce obsahuje payment_method a odpověď vrátí payment_url uvnitř objektu transakce:

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

Přesměrujte zákazníka na payment_url z transakce.

Pokud uvedete pouze jednu položku v poli transactions, zákazník je přesměrován přímo na danou platební metodu bez zobrazení výběrové obrazovky. Pole flags obsahuje "is-test" při použití sandbox API klíče.

Pole požadavku

Pole	Povinné	Popis
`currency`	Ano	Kód měny dle ISO 4217 (např. `EUR`, `GBP`, `SEK`)
`amount`	Ano	Částka v centech. Například 12,95 EUR je reprezentováno jako `1295`
`merchant_order_id`	Ne	Vaše vlastní referenční ID objednávky
`return_url`	Ne	URL pro přesměrování zákazníka po platbě (výchozí pro všechny stavy)
`failure_url`	Ne	URL pro přesměrování zákazníka při stavu `cancelled`, `expired` nebo `error` (viz Návratové URL níže)
`locale`	Ne	Jazyk platební stránky. Podporované: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	Ne	Popis objednávky zobrazený zákazníkovi
`payment_methods`	Ne	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`	Ne	URL pro příjem notifikací o změně stavu
`expiration_period`	Ne	ISO 8601 doba platnosti objednávky. Výchozí je `PT30M` (30 minut)

Pole amount je vždy v nejmenší měnové jednotce (centy). Hodnota 1295 znamená 12,95 v dané měně. Předání 1295.00 nebo 12.95 povede k chybě nebo nesprávné částce.

Více platebních metod

Pro nabídku více konkrétních platebních metod přidejte více položek do pole transactions. Pořadí na hostované stránce odpovídá pořadí v poli:

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

Návratové URL

Po platbě je zákazník přesměrován na základě stavu objednávky a poskytnutých URL:

Když jsou nastaveny return_url i failure_url:
- cancelled, expired nebo error → zákazník je přesměrován na failure_url
- Všechny ostatní stavy → zákazník je přesměrován na return_url
Když je nastaven pouze return_url:
- Všechny stavy → zákazník je přesměrován na return_url

Použijte failure_url pro zobrazení stránky s opakováním nebo podporou při neúspěšných platbách, zatímco return_url zobrazí potvrzení objednávky. Pokud potřebujete pouze jeden cíl, stačí samotná return_url.

Chování tlačítka Zrušit

Hostovaná platební stránka obsahuje tlačítko pro zrušení. Když na něj zákazník klikne, je přesměrován na failure_url (pokud je zadána) nebo return_url. Stav objednávky se změní na cancelled. Vždy ověřte stav objednávky prostřednictvím API nebo webhooků místo spoléhání na přesměrování.

Související endpointy

Vytvoření objednávky — vytvoření platební objednávky a získání payment_url
Získání objednávky — kontrola stavu objednávky po platbě

Hostovaná platební stránka (HPP)

On this page