Hostitud makseleht (HPP)

Hostitud makseleht (HPP) on Cost+ PCI DSS-iga ühilduv maksevorm. See võimaldab teil makseid vastu võtta ilma tundlike kaardiandmetega oma serverites tegelemata. Te loote tellimuse API kaudu, suunate kliendi hostitud lehele ja nad naasevad pärast maksmist teie saidile.

Kuidas see töötab

Teie server loob tellimuse, kutsudes POST /v1/orders/.
API tagastab URL-i, mis viitab hostitud makselehele.
Te suunate kliendi makselehele.
Klient teostab makse Cost+ hostitud lehel.
Klient suunatakse tagasi teie return_url-ile (või failure_url-ile ebaõnnestunud maksete korral).
Cost+ saadab teie webhook_url-ile veebihaagi teavituse tellimuse olekuga.

Hostitud makseleht on täielikult PCI DSS-iga ühilduv. Te ei pea kunagi käsitlema töötlemata kaardinumbreid ega tundlikke makseandmeid oma serverites.

Tellimuse loomine

HPP kasutamiseks on kaks lähenemist:

Lähenemine 1: Kõigi makseviisidekuvamine (lihtsaim)

Looge tellimus ilma transactions määramata. Vastus sisaldab order_url-i — klient suunatakse sinna ja näeb kõiki teie kontol lubatud makseviise:

Päring

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

Vastus

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

Suunake klient order_url-ile. Hostitud lehel kuvatakse kõik lubatud makseviisid.

Lähenemine 2: Makseviisideeelvalimine

Looge tellimus koos transactions massiiviga, et kontrollida, millised makseviisid kuvatakse ja millises järjekorras. Iga tehing sisaldab payment_method-it ja vastus tagastab tehinguobjektis payment_url-i:

Päring

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

Vastus

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

Suunake klient tehingust saadud payment_url-ile.

Kui lisate transactions massiivi ainult ühe kirje, suunatakse klient otse sellele makseviisile ilma valikuekraani nägemata. flags massiiv sisaldab "is-test", kui kasutate liivakasti API võtit.

Päringu väljad

Väli	Kohustuslik	Kirjeldus
`currency`	Jah	ISO 4217 valuutakood (nt `EUR`, `GBP`, `SEK`)
`amount`	Jah	Summa valuuta ISO 4217 väikeühikus. Näiteks 12.95 EUR on esindatud kui `1295`
`merchant_order_id`	Ei	Teie enda tellimuse viide-ID
`return_url`	Ei	URL, kuhu klient pärast maksmist suunatakse (vaikimisi kõigi olekute jaoks)
`failure_url`	Ei	URL, kuhu klient suunatakse olekute `cancelled`, `expired` või `error` korral (vt Tagastus-URL-id allpool)
`locale`	Ei	Makselehe keel. Toetatud: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	Ei	Tellimuse kirjeldus, mis kuvatakse kliendile
`payment_methods`	Ei	Filtreerige ühe makseviisi järgi (nt `["credit-card"]`). Jätke kõigi lubatud meetodite kuvamine välja. Mitme konkreetse meetodi puhul kasutage selle asemel massiivi `transactions`
`webhook_url`	Ei	URL olekumuutuste teavituste saamiseks
`expiration_period`	Ei	ISO 8601 kestvus tellimuse aegumiseks. Vaikimisi on `PT30M` (30 minutit)

Väli amount on alati täisarv valuuta ISO 4217 väikeühikus. EUR puhul tähendab 1295 12,95 EUR; null- ja kolme kümnendkohaga valuutad kasutavad oma eksponenti ISO 4217. Kümnendväärtuse (nt 1295.00 või 12.95) edastamine põhjustab tõrke või vale tasu.

Mitu makseviisi

Hostitud lehel kuvatavate makseviiside kontrollimiseks on kaks võimalust.

Valik A – payment_methods (üks filter). Tellimuse piiramiseks ühe makseviisiga edastage üheelemendiline massiiv. Kõigi teie konto jaoks lubatud meetodite kuvamiseks jätke väli täielikult välja.

Valik B – massiiv transactions (soovitatav mitme meetodi jaoks). Lisage üks kirje iga makseviisi kohta. Iga tehing saab oma payment_url ja meetodid kuvatakse hostitud lehel massiivi järjekorras:

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

Tellimuste väli payment_methods aktsepteerib kuni ühe väärtuse. Mitme konkreetse meetodi pakkumiseks kasutage alati massiivi transactions. Kui vajate mitme makseviisiga korduvkasutatavat linki, kaaluge selle asemel [Makselinke] (/docs/guides/payment-links), mis toetavad tõelist payment_methods massiivi.

Tagastus-URL-id

Pärast maksmist suunatakse klient vastavalt tellimuse olekule ja teie esitatud URL-idele:

Kui nii return_url kui ka failure_url on määratud:
- cancelled, expired või error → klient suunatakse failure_url-ile
- Kõigi muude olekute korral → klient suunatakse return_url-ile
Kui ainult return_url on määratud:
- Kõigi olekute korral → klient suunatakse return_url-ile

Kasutage failure_url-i, et kuvada ebaõnnestunud maksete korral uuesti proovimise või toe lehte, samal ajal kui return_url kuvab tellimuse kinnituse. Kui vajate ainult ühte sihtpunkti, piisab ainult return_url-ist.

Tühistamisnupu käitumine

Hostitud makselehel on tühistamisnupp. Kui klient sellel klõpsab, suunatakse ta failure_url-ile (kui on olemas) või return_url-ile. Tellimuse olek muutub olekusse cancelled. Kontrollige alati tellimuse olekut API või veebihaakide kaudu, mitte ainult ümbersuunamise alusel.

Seotud lõpp-punktid

Tellimuse loomine — looge maksetellimus ja saage payment_url
Tellimuse pärimine — kontrollige tellimuse olekut pärast maksmist

Hostitud makseleht (HPP)

On this page