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://pay.costplus.online/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://pay.costplus.online/4851e31c.../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 senteissä. Esimerkiksi 12,95 EUR esitetään arvona `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	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`	Ei	URL tilanmuutosilmoitusten vastaanottamiseen
`expiration_period`	Ei	ISO 8601 -kesto tilauksen vanhenemiselle. Oletusarvo on `PT30M` (30 minuuttia)

amount-kenttä on aina pienimmässä valuuttayksikössä (senteissä). Arvo 1295 tarkoittaa 12,95 annetussa valuutassa. Arvon 1295.00 tai 12.95 antaminen johtaa virheeseen tai virheelliseen veloitukseen.

Useita maksutapoja

Tarjotaksesi useita tiettyjä maksutapoja, lisää useita merkintöjä transactions-taulukkoon. Järjestys isännöidyllä sivulla vastaa taulukon järjestystä:

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

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

On this page