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://api.costplus.online/pay/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://api.costplus.online/pay/4851e31c.../select-payment-method/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 menší jednotce ISO 4217 měny. 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`	Žádný	Filtrujte na jednu platební metodu (např. `["credit-card"]`). Vynechat pro zobrazení všech povolených metod. Pro více specifických metod použijte místo toho pole `transactions`
`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 celé číslo ve vedlejší jednotce ISO 4217 měny. Pro EUR znamená 1295 12,95 EUR; Měny s nulou a třemi desetinnými místy používají svůj vlastní exponent ISO 4217. Předání desetinné hodnoty, jako je 1295.00 nebo 12.95, bude mít za následek chybu nebo nesprávný poplatek.

Více platebních metod

Existují dva způsoby, jak ovládat, které platební metody se zobrazí na hostované stránce:

Možnost A — payment_methods (jediný filtr). Předejte jednoprvkové pole pro omezení objednávky na jednu platební metodu. Chcete-li zobrazit všechny metody povolené pro váš účet, pole úplně vynechejte.

Možnost B – pole transactions (doporučeno pro více metod). Přidejte jednu položku pro každou platební metodu. Každá transakce dostane svůj vlastní payment_url a metody se zobrazí v pořadí polí na hostované stránce:

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

Pole payment_methods na objednávkách přijímá maximálně jednu hodnotu. Chcete-li nabídnout více konkrétních metod, vždy použijte pole transactions. Pokud potřebujete znovu použitelný odkaz s více platebními metodami, zvažte místo toho Platební odkazy, které podporují skutečné pole payment_methods.

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