Maksulinkit

Maksulinkit ovat uudelleenkäytettäviä URL-osoitteita, joiden kautta asiakkaat voivat maksaa tilauksen. Toisin kuin tavalliset tilaukset, jotka vanhenevat yhden epäonnistuneen yrityksen jälkeen, maksulinkit tukevat useita uudelleenyrityksiä, mikä tekee niistä ihanteellisia laskuille, sähköpostimaksuille ja tilanteille, joissa asiakas ei välttämättä maksa heti.

Keskeiset ominaisuudet

Uudelleenkäytettävä: Asiakkaat voivat yrittää maksua uudelleen enintään 25 kertaa, jos aiemmat yritykset epäonnistuvat.
Pitkäikäinen: Oletusvanhenemisaika on 30 päivää (muokattavissa expiration_period-kentällä).
Jaettava: Lähetä linkki sähköpostitse, tekstiviestillä, chatissa tai upota se verkkosivustollesi.

Maksulinkin luominen

Lähetä POST-pyyntö osoitteeseen /v1/paymentlinks/:

POST /v1/paymentlinks/

curl -X POST https://api.costplus.online/v1/paymentlinks/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "invoice-1234",
    "amount": 995,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

Vastaus sisältää asiakkaalle jaettavan payment_url-osoitteen ja yksilöllisen id-tunnisteen seurantaa varten:

Response (201 Created)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "new",
  "reason": "Payment Link was created, not yet visited",
  "orders": {},
  "created": "2026-01-15T12:00:00.000000Z"
}

Tallenna id — tarvitset sitä maksulinkin tilan tarkistamiseen myöhemmin.

Pakolliset kentät

Kenttä	Kuvaus
`merchant_order_id`	Oma viitetunnisteesi maksulinkille
`amount`	Summa senteissä (esim. 9,95 EUR = `995`)
`currency`	ISO 4217 -valuuttakoodi (esim. `EUR`, `GBP`)

Valinnaiset kentät

Kenttä	Kuvaus
`description`	Asiakkaalle näytettävä kuvaus
`expiration_period`	ISO 8601 -kesto. Oletusarvo on `P30D` (30 päivää)
`return_url`	URL, johon asiakas ohjataan onnistuneen maksun jälkeen
`failure_url`	URL, johon asiakas ohjataan peruutuksen, vanhenemisen tai virheen yhteydessä
`webhook_url`	URL tilanmuutosilmoitusten vastaanottamiseen
`customer`	Asiakkaan tiedot (nimi, sähköposti jne.)

Jos annat sekä return_url- että failure_url-osoitteet, asiakas ohjataan failure_url-osoitteeseen, kun tilauksen tila on cancelled, expired tai error. Muussa tapauksessa kaikki uudelleenohjaukset menevät return_url-osoitteeseen.

Maksulinkin hakeminen

Lähetä GET-pyyntö osoitteeseen /v1/paymentlinks/{id}/ käyttäen luontivastauksen maksulinkin id-tunnistetta:

GET /v1/paymentlinks/{id}/

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/

Vastaus sisältää nykyisen tilan ja viittaukset kaikkiin linkistä luotuihin tilauksiin, ryhmiteltynä tilan mukaan:

Response (completed example)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "completed",
  "reason": "Completed",
  "completed": "2026-01-15T12:05:30.123456+00:00",
  "completed_order_id": "3bb663cc-2a20-400d-8bf6-18d9695d0c66",
  "orders": {
    "error": ["0d79014c-0aaa-4fd6-87c5-c8cfa5f5ac69"],
    "completed": ["3bb663cc-2a20-400d-8bf6-18d9695d0c66"]
  }
}

Tässä esimerkissä asiakas teki yhden epäonnistuneen yrityksen (tilaus 0d79014c... error-tilassa) ennen onnistumista (tilaus 3bb663cc... completed-tilassa). Voit hakea minkä tahansa tilauksen täydelliset tiedot kutsulla GET /v1/orders/{order_id}/.

Maksulinkkien tilat

Tila	Kuvaus
`new`	Linkki on luotu, mutta maksuyritystä ei ole tehty.
`processing`	Maksuyritys on käynnissä.
`all_unsuccessful`	Kaikki tähänastiset maksuyritykset ovat epäonnistuneet. Asiakas voi silti yrittää uudelleen (enintään 25 yritystä).
`completed`	Maksu onnistui. Linkki ei ole enää aktiivinen.
`expired`	Linkki on vanhentunut ennen onnistunutta maksua.

all_unsuccessful-tila ei ole lopullinen. Asiakas voi silti yrittää maksaa uudelleen, kunnes joko maksu onnistuu, yritysten enimmäismäärä (25) saavutetaan tai linkki vanhenee.

Kun maksulinkki saavuttaa completed- tai expired-tilan, sitä ei voi enää käyttää. Luo uusi maksulinkki, jos asiakkaan täytyy maksaa uudelleen.

Esimerkkityönkulku

Luo maksulinkki kutsulla POST /v1/paymentlinks/.
Jaa palautettu payment_url asiakkaallesi (esim. sähköpostilla, tekstiviestillä tai laskulla).
Asiakas avaa linkin ja suorittaa maksun.
Cost+ lähettää webhookin webhook_url-osoitteeseesi tilan muuttuessa.
Vahvista maksulinkin tila kutsulla GET /v1/paymentlinks/{id}/.
Toimita tilaus, kun tila on completed.

Liittyvät päätepisteet

Luo maksulinkki — luo uudelleenkäytettävä maksulinkki
Hae maksulinkki — hae maksulinkin nykyinen tila

On this page