Makselingid

Makselingid on korduvkasutatavad URL-id, mis võimaldavad klientidel tellimuse eest maksta. Erinevalt tavalistest tellimustest, mis aeguvad pärast ühte ebaõnnestunud katset, toetavad makselingid mitut korduskatset, muutes need ideaalseks arvete, e-postipõhiste maksete ja olukordade jaoks, kus klient ei pruugi kohe maksta.

Põhifunktsioonid

Korduvkasutatav: Kliendid saavad makset uuesti proovida kuni 25 korda, kui eelmised katsed ebaõnnestuvad.
Pika elueaga: Vaikimisi aegumisaeg on 30 päeva (seadistatav expiration_period kaudu).
Jagatav: Saatke link e-posti, SMS-i, vestluse kaudu või manustage see oma veebilehele.

Makselingi loomine

Saatke POST päring aadressile /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"
  }'

Vastus sisaldab payment_url-i kliendiga jagamiseks ja unikaalset id-d jälgimiseks:

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

Salvestage id — seda kasutate hiljem makselingi oleku kontrollimiseks.

Kohustuslikud väljad

Väli	Kirjeldus
`merchant_order_id`	Teie enda viide-ID makselingi jaoks
`amount`	Summa sentides (nt 9,95 EUR = `995`)
`currency`	ISO 4217 valuutakood (nt `EUR`, `GBP`)

Valikulised väljad

Väli	Kirjeldus
`description`	Kliendile kuvatav kirjeldus
`expiration_period`	ISO 8601 kestvus. Vaikimisi on `P30D` (30 päeva)
`return_url`	URL, kuhu klient pärast edukat makset suunatakse
`failure_url`	URL, kuhu klient suunatakse tühistamise, aegumise või vea korral
`webhook_url`	URL olekumuutuste teavituste saamiseks
`customer`	Kliendi andmete objekt (nimi, e-post jne)

Kui esitate nii return_url kui ka failure_url, suunatakse kliendid failure_url-ile, kui tellimuse olek on cancelled, expired või error. Vastasel juhul suunatakse kõik ümbersuunamised return_url-ile.

Makselingi pärimine

Saatke GET päring aadressile /v1/paymentlinks/{id}/, kasutades loomise vastusest saadud makselingi id-d:

GET /v1/paymentlinks/{id}/

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

Vastus sisaldab praegust olekut ja viiteid kõigile lingist loodud tellimustele, grupeerituna nende oleku järgi:

Vastus (lõpetatud näide)

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

Selles näites tegi klient ühe ebaõnnestunud katse (tellimus 0d79014c... olekus error) enne edukat makset (tellimus 3bb663cc... olekus completed). Saate pärida mis tahes tellimuse täielikud üksikasjad päringuga GET /v1/orders/{order_id}/.

Makselingi olekud

Olek	Kirjeldus
`new`	Link on loodud, kuid maksekatset pole tehtud.
`processing`	Maksekatse on praegu pooleli.
`all_unsuccessful`	Kõik senised maksekatsed on ebaõnnestunud. Klient saab siiski uuesti proovida (kuni 25 katset).
`completed`	Makse oli edukas. Link ei ole enam aktiivne.
`expired`	Link on aegunud enne eduka makse teostamist.

Olek all_unsuccessful ei ole lõppolek. Klient saab siiski uuesti proovida maksta, kuni kas makse õnnestub, maksimaalne katsete arv (25) on saavutatud või link aegub.

Kui makselink jõuab olekusse completed või expired, ei saa seda enam kasutada. Looge uus makselink, kui klient peab uuesti maksma.

Näidis-töövoog

Looge makselink päringuga POST /v1/paymentlinks/.
Jagage tagastatud payment_url-i oma kliendiga (nt e-posti, SMS-i või arve kaudu).
Klient avab lingi ja teostab makse.
Cost+ saadab veebihaagi teie webhook_url-ile, kui olek muutub.
Kontrollige makselingi olekut päringuga GET /v1/paymentlinks/{id}/.
Täitke tellimus, kui olek on completed.

Seotud lõpp-punktid

Makselingi loomine — looge korduvkasutatav makselink
Makselingi pärimine — pärige makselingi praegune olek

On this page