Cost+Docs

Hostovana platobna stranka (HPP)

Prijimajte platby pomocou hostovanej platobnej stranky Cost+

Hostovana platobna stranka (HPP) je platobny formular Cost+ kompatibilny s PCI DSS. Umoznuje vam prijimat platby bez manipulacie s citlivymi udajmi kariet na vasich vlastnych serveroch. Vytvorite objednavku cez API, presmerujete zakaznika na hostovanu stranku a po platbe sa vrati na vasu stranku.

Ako to funguje

  1. Vas server vytvori objednavku volanim POST /v1/orders/.
  2. API vrati URL adresu smerujucu na hostovanu platobnu stranku.
  3. Presmerujete zakaznika na platobnu stranku.
  4. Zakaznik dokonci platbu na hostovanej stranke Cost+.
  5. Zakaznik je presmerovany spat na vasu return_url (alebo failure_url pri neuspesnych platbach).
  6. Cost+ posle webhook notifikaciu na vasu webhook_url so stavom objednavky.

Hostovana platobna stranka je plne kompatibilna s PCI DSS. Nikdy nemusite manipulovat so surovymi cislami kariet ani s citlivymi platobnymi udajmi na vasich serveroch.

Vytvorenie objednavky

Existuju dva pristupy k pouzitiu HPP:

Pristup 1: Zobrazenie vsetkych platobnych metod (najjednoduchsie)

Vytvorte objednavku bez zadania transactions. Odpoved obsahuje order_url -- zakaznik je presmerovany tam a vidi vsetky platobne metody aktivovane pre vas ucet:

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

Presmerujte zakaznika na order_url. Na hostovanej stranke sa zobrazia vsetky aktivovane platobne metody.

Pristup 2: Predvolene platobne metody

Vytvorte objednavku s polom transactions na kontrolu toho, ktore platobne metody sa zobrazia a v akom poradi. Kazda transakcia obsahuje payment_method a odpoved vrati payment_url v objekte transakcie:

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

Presmerujte zakaznika na payment_url z transakcie.

Ak uvediete len jednu polozku v poli transactions, zakaznik je presmerovany priamo na tu platobnu metodu bez zobrazenia obrazovky vyberu. Pole flags obsahuje "is-test" pri pouziti sandbox API kluca.

Polia poziadavky

PolePovinnePopis
currencyAnoISO 4217 kod meny (napr. EUR, GBP, SEK)
amountánoSuma v menovej jednotke ISO 4217. Napríklad 12,95 EUR je reprezentované ako 1295
merchant_order_idNieVase vlastne referencne ID pre objednavku
return_urlNieURL na presmerovanie zakaznika po platbe (predvolene pre vsetky stavy)
failure_urlNieURL na presmerovanie zakaznika pri stavoch cancelled, expired alebo error (pozrite Navratove URL nizsie)
localeNieJazyk platobnej stranky. Podporovane: en-GB, de-DE, nl-NL, nl-BE, fr-BE, sv-SE, no-NO, da-DK
descriptionNiePopis objednavky zobrazeny zakaznikovi
payment_methodsNieFiltrujte na jeden spôsob platby (napr. ["credit-card"]). Vynechaním zobrazíte všetky povolené metódy. Pre viacero špecifických metód použite namiesto toho pole transactions
webhook_urlNieURL na prijimanie notifikacii o zmene stavu
expiration_periodNieISO 8601 trvanie pre exspiraciu objednavky. Predvolene je PT30M (30 minut)

Pole amount je vždy celé číslo v menovej jednotke ISO 4217. Pre EUR znamená 1295 12,95 EUR; meny s nulou a tromi desatinnými miestami používajú svoj vlastný exponent ISO 4217. Odovzdanie desatinnej hodnoty, napríklad 1295.00 alebo 12.95, bude mať za následok chybu alebo nesprávny poplatok.

Viacero platobnych metod

Existujú dva spôsoby, ako ovládať, ktoré spôsoby platby sa zobrazia na hosťovanej stránke:

Možnosť A – payment_methods (jeden filter). Odovzdajte jednoprvkové pole na obmedzenie objednávky na jeden spôsob platby. Ak chcete zobraziť všetky metódy povolené pre váš účet, pole úplne vynechajte.

Možnosť B – pole transactions (odporúčané pre viacero spôsobov). Pridajte jednu položku na každý spôsob platby. Každá transakcia dostane svoj vlastný payment_url a metódy sa zobrazia v poradí polí na hosťovanej stránke:

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

Pole payment_methods na objednávkach akceptuje najviac jednu hodnotu. Ak chcete ponúknuť viacero špecifických metód, vždy použite pole transactions. Ak potrebujete opakovane použiteľný odkaz s viacerými spôsobmi platby, zvážte namiesto toho platobné odkazy, ktoré podporujú skutočné pole payment_methods.

Po platbe je zakaznik presmerovany na zaklade stavu objednavky a toho, ktore URL ste zadali:

  • Ked su nastavene obe return_url a failure_url:

    • cancelled, expired alebo error -> zakaznik je presmerovany na failure_url
    • Vsetky ostatne stavy -> zakaznik je presmerovany na return_url
  • Ked je nastavena len return_url:

    • Vsetky stavy -> zakaznik je presmerovany na return_url

Pouzite failure_url na zobrazenie stranky s moznostou opakovaneho pokusu alebo podporou pre neuspesne platby, zatial co return_url zobrazuje potvrdenie objednavky. Ak potrebujete len jednu cielovu adresu, samotna return_url je dostatocna.

Spravanie tlacidla Zrusit

Hostovana platobna stranka obsahuje tlacidlo Zrusit. Ked na neho zakaznik klikne, je presmerovany na failure_url (ak je zadana) alebo return_url. Stav objednavky sa zmeni na cancelled. Vzdy overujte stav objednavky cez API alebo webhooky namiesto spoliemania sa len na presmerovanie.

Suvisiace endpointy

On this page