Mokėjimo nuorodos

Mokėjimo nuorodos yra pakartotinai naudojami URL, leidžiantys klientams apmokėti užsakymą. Skirtingai nuo standartinių užsakymų, kurių galiojimas baigiasi po vieno nesėkmingo bandymo, mokėjimo nuorodos palaiko kelis pakartotinius bandymus, todėl jos idealiai tinka sąskaitoms, mokėjimams el. paštu ir scenarijams, kai klientas gali nemokėti iš karto.

Pagrindinės savybės

Pakartotinai naudojamos: klientai gali bandyti mokėti iki 25 kartų, jei ankstesni bandymai nepavyksta.
Ilgai galiojančios: numatytasis galiojimo laikotarpis yra 30 dienų (konfigūruojamas per expiration_period).
Dalinamos: siųskite nuorodą el. paštu, SMS, pokalbiu ar įterpkite į savo svetainę.

Mokėjimo nuorodos kūrimas

Siųskite POST užklausą į /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"
  }'

Atsakyme pateikiamas payment_url, kurį galite dalintis su klientu, ir unikalus id sekimui:

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

Išsaugokite id — jį naudosite mokėjimo nuorodos būsenai patikrinti vėliau.

Privalomi laukai

Laukas	Aprašymas
`merchant_order_id`	Jūsų nuosavasis mokėjimo nuorodos nuorodos ID
`amount`	Suma centais (pvz., 9,95 EUR = `995`)
`currency`	ISO 4217 valiutos kodas (pvz., `EUR`, `GBP`)

Neprivalomi laukai

Laukas	Aprašymas
`description`	Aprašymas, rodomas klientui
`expiration_period`	ISO 8601 trukmė. Numatytoji yra `P30D` (30 dienų)
`return_url`	URL, į kurį nukreipti klientą po sėkmingo mokėjimo
`failure_url`	URL, į kurį nukreipti klientą atšaukimo, galiojimo pabaigos ar klaidos atveju
`webhook_url`	URL būsenos pakeitimo pranešimams gauti
`customer`	Kliento informacijos objektas (vardas, el. paštas ir kt.)

Jei pateiksite ir return_url, ir failure_url, klientai nukreipiami į failure_url, kai užsakymo būsena yra cancelled, expired arba error. Kitu atveju visi peradresavimai nukreipiami į return_url.

Mokėjimo nuorodos gavimas

Siųskite GET užklausą į /v1/paymentlinks/{id}/, naudodami mokėjimo nuorodos id iš kūrimo atsakymo:

GET /v1/paymentlinks/{id}/

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

Atsakyme pateikiama esama būsena ir nuorodos į visus užsakymus, sukurtus iš šios nuorodos, sugrupuotus pagal jų būseną:

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

Šiame pavyzdyje klientas atliko vieną nesėkmingą bandymą (užsakymas 0d79014c... su error būsena) prieš pavykstant (užsakymas 3bb663cc... su completed būsena). Galite gauti pilnas bet kurio užsakymo detales per GET /v1/orders/{order_id}/.

Mokėjimo nuorodos būsenos

Būsena	Aprašymas
`new`	Nuoroda sukurta, bet mokėjimo bandymų dar nebuvo.
`processing`	Šiuo metu vykdomas mokėjimo bandymas.
`all_unsuccessful`	Visi mokėjimo bandymai iki šiol nepavyko. Klientas vis dar gali bandyti pakartotinai (iki 25 bandymų).
`completed`	Mokėjimas sėkmingas. Nuoroda nebegalioja.
`expired`	Nuorodos galiojimas baigėsi prieš sėkmingą mokėjimą.

Būsena all_unsuccessful nėra galutinė. Klientas vis dar gali bandyti mokėti pakartotinai, kol mokėjimas pavyks, bus pasiektas maksimalus bandymų skaičius (25) arba nuorodos galiojimas baigsis.

Kai mokėjimo nuoroda pasiekia completed arba expired būseną, ji nebegali būti naudojama. Sukurkite naują mokėjimo nuorodą, jei klientas turi mokėti dar kartą.

Darbo eigos pavyzdys

Sukurkite mokėjimo nuorodą per POST /v1/paymentlinks/.
Pasidalinkite grąžintu payment_url su klientu (pvz., el. paštu, SMS ar sąskaitoje).
Klientas atidaro nuorodą ir atlieka mokėjimą.
Cost+ siunčia webhook į jūsų webhook_url, kai pasikeičia būsena.
Patikrinkite mokėjimo nuorodos būseną per GET /v1/paymentlinks/{id}/.
Įvykdykite užsakymą, kai būsena yra completed.

Susiję galiniai taškai

Sukurti mokėjimo nuorodą — sukurti pakartotinai naudojamą mokėjimo nuorodą
Gauti mokėjimo nuorodą — gauti esamą mokėjimo nuorodos būseną

On this page