Isännöity maksusivu (HPP)

Isännöity maksusivu (HPP) on Cost+:n PCI DSS -yhteensopiva maksulomake. Sen avulla voit vastaanottaa maksuja käsittelemättä arkaluontoisia korttitietoja omilla palvelimillasi. Luot tilauksen API:n kautta, ohjaat asiakkaan isännöidylle sivulle, ja asiakas palaa sivustollesi maksun jälkeen.

Miten se toimii

Palvelimesi luo tilauksen kutsumalla POST /v1/orders/.
API palauttaa URL:n, joka osoittaa isännöidylle maksusivulle.
Ohjaat asiakkaan maksusivulle.
Asiakas suorittaa maksun Cost+:n isännöidyllä sivulla.
Asiakas ohjataan takaisin return_url-osoitteeseesi (tai failure_url-osoitteeseen epäonnistuneiden maksujen osalta).
Cost+ lähettää webhook-ilmoituksen webhook_url-osoitteeseesi tilauksen tilasta.

Isännöity maksusivu on täysin PCI DSS -yhteensopiva. Sinun ei koskaan tarvitse käsitellä raakoja korttinumeroita tai arkaluontoista maksutietoa palvelimillasi.

Tilauksen luominen

HPP:n käyttöön on kaksi lähestymistapaa:

Lähestymistapa 1: Näytä kaikki maksutavat (yksinkertaisin)

Luo tilaus ilman transactions-kenttää. Vastaus sisältää order_url-osoitteen — asiakas ohjataan sinne ja näkee kaikki tilillesi käyttöön otetut maksutavat:

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

Ohjaa asiakas order_url-osoitteeseen. Isännöidyllä sivulla näytetään kaikki käytössä olevat maksutavat.

Lähestymistapa 2: Valitse maksutavat etukäteen

Luo tilaus transactions-taulukolla hallitaksesi, mitkä maksutavat näytetään ja missä järjestyksessä. Jokainen tapahtuma sisältää payment_method-kentän, ja vastaus palauttaa payment_url-osoitteen tapahtumaobjektin sisällä:

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

Ohjaa asiakas tapahtuman payment_url-osoitteeseen.

Jos annat vain yhden merkinnän transactions-taulukkoon, asiakas siirtyy suoraan kyseiseen maksutapaan näkemättä valinnanäkymää. flags-taulukko sisältää "is-test" käytettäessä sandbox-API-avainta.

Pyyntökentät

Kenttä	Pakollinen	Kuvaus
`currency`	Kyllä	ISO 4217 -valuuttakoodi (esim. `EUR`, `GBP`, `SEK`)
`amount`	Kyllä	Summa valuutan ISO 4217 pienessä yksikössä. Esimerkiksi 12.95 EUR esitetään muodossa `1295`
`merchant_order_id`	Ei	Oma viitetunnisteesi tilaukselle
`return_url`	Ei	URL, johon asiakas ohjataan maksun jälkeen (oletusarvo kaikille tiloille)
`failure_url`	Ei	URL, johon asiakas ohjataan `cancelled`-, `expired`- tai `error`-tilassa (katso Paluu-URL:t alla)
`locale`	Ei	Maksusivun kieli. Tuetut: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	Ei	Tilauksen kuvaus, joka näytetään asiakkaalle
`payment_methods`	Ei	Suodata yhteen maksutapaan (esim. `["credit-card"]`). Älä näytä kaikkia käytössä olevia menetelmiä. Useita tiettyjä menetelmiä varten käytä sen sijaan `transactions`-taulukkoa
`webhook_url`	Ei	URL tilanmuutosilmoitusten vastaanottamiseen
`expiration_period`	Ei	ISO 8601 -kesto tilauksen vanhenemiselle. Oletusarvo on `PT30M` (30 minuuttia)

amount-kenttä on aina kokonaisluku valuutan ISO 4217-alayksikössä. EUR:lle 1295 tarkoittaa 12,95 EUR; nolla- ja kolmen desimaalin valuutat käyttävät omaa eksponenttiaan ISO 4217. Desimaaliarvon, kuten 1295.00 tai 12.95, välittäminen aiheuttaa virheen tai virheellisen veloituksen.

Useita maksutapoja

On kaksi tapaa hallita, mitkä maksutavat näkyvät isännöidyllä sivulla:

Vaihtoehto A – payment_methods (yksi suodatin). Ohjaa yksielementtinen matriisi rajoittaaksesi tilauksen yhteen maksutapaan. Jätä kenttä kokonaan pois, jotta näet kaikki tilissäsi käytössä olevat menetelmät.

Vaihtoehto B – transactions-taulukko (suositellaan useille tavoille). Lisää yksi merkintä maksutapaa kohden. Jokainen tapahtuma saa oman payment_url-koodinsa, ja menetelmät näkyvät taulukkojärjestyksessä isännöidyllä sivulla:

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

Tilausten payment_methods-kenttä hyväksyy enintään yhden arvon. Jos haluat tarjota useita tiettyjä menetelmiä, käytä aina transactions-taulukkoa. Jos tarvitset uudelleenkäytettävän linkin useilla maksutavoilla, harkitse sen sijaan Maksulinkit, jotka tukevat todellista payment_methods-taulukkoa.

Paluu-URL:t

Maksun jälkeen asiakas ohjataan tilauksen tilan ja antamiesi URL:ien perusteella:

Kun sekä return_url että failure_url on asetettu:
- cancelled, expired tai error → asiakas ohjataan failure_url-osoitteeseen
- Kaikissa muissa tiloissa → asiakas ohjataan return_url-osoitteeseen
Kun vain return_url on asetettu:
- Kaikissa tiloissa → asiakas ohjataan return_url-osoitteeseen

Käytä failure_url-osoitetta näyttääksesi uudelleenyritys- tai tukisivun epäonnistuneiden maksujen yhteydessä, kun taas return_url näyttää tilausvahvistuksen. Jos tarvitset vain yhden kohteen, pelkkä return_url riittää.

Peruutus-painikkeen toiminta

Isännöity maksusivu sisältää peruutus-painikkeen. Kun asiakas napsauttaa sitä, hänet ohjataan failure_url-osoitteeseen (jos annettu) tai return_url-osoitteeseen. Tilauksen tila muuttuu tilaan cancelled. Vahvista tilauksen tila aina API:n tai webhookien kautta sen sijaan, että luottaisit pelkästään uudelleenohjaukseen.

Liittyvät päätepisteet

Luo tilaus — luo maksutilaus ja vastaanota payment_url
Hae tilaus — tarkista tilauksen tila maksun jälkeen

Isännöity maksusivu (HPP)

On this page