Cost+Docs

Poveznice za plaćanje

Stvorite poveznice za plaćanje za višestruku upotrebu

Poveznice za plaćanje su URL-ovi za višestruku upotrebu koji omogućuju kupcima plaćanje narudžbe. Za razliku od standardnih narudžbi koje istječu nakon jednog neuspjelog pokušaja, poveznice za plaćanje podržavaju više ponovnih pokušaja, što ih čini idealnim za račune, plaćanja putem e-pošte i scenarije gdje kupac možda neće odmah platiti.

Ključne značajke

  • Višestruka upotreba: Kupci mogu ponoviti plaćanje do 25 puta ako prethodni pokušaji ne uspiju.
  • Dugotrajne: Zadani rok isteka je 30 dana (konfigurirano putem expiration_period).
  • Dijeljive: Pošaljite poveznicu putem e-pošte, SMS-a, chata ili je ugradite na svoju web stranicu.

Stvaranje poveznice za plaćanje

Pošaljite POST zahtjev na /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"
  }'

Odgovor uključuje payment_url za dijeljenje s kupcem i jedinstveni id za praćenje:

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://api.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "new",
  "reason": "Payment Link was created, not yet visited",
  "orders": {},
  "created": "2026-01-15T12:00:00.000000Z"
}

Spremite id — koristit ćete ga za kasniju provjeru statusa poveznice za plaćanje.

Obavezna polja

PoljeOpis
merchant_order_idVaš vlastiti referentni ID za poveznicu za plaćanje
amountIznos u manjoj jedinici ISO 4217 valute (npr. 9,95 EUR = 995)
currencyISO 4217 kod valute (npr. EUR, GBP)

Neobavezna polja

PoljeOpis
descriptionOpis prikazan kupcu
expiration_periodISO 8601 trajanje. Zadano je P30D (30 dana)
return_urlURL za preusmjeravanje kupca nakon uspješnog plaćanja
failure_urlURL za preusmjeravanje kupca pri odustajanju, isteku ili grešci
webhook_urlURL za primanje obavijesti o promjeni statusa
customerObjekt s podacima o kupcu (ime, e-pošta itd.)

Ako navedete i return_url i failure_url, kupci se preusmjeravaju na failure_url kada je status narudžbe cancelled, expired ili error. U suprotnom, sva preusmjeravanja idu na return_url.

Dohvaćanje poveznice za plaćanje

Pošaljite GET zahtjev na /v1/paymentlinks/{id}/ koristeći id poveznice za plaćanje iz odgovora na stvaranje:

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

Odgovor uključuje trenutni status i reference na sve narudžbe stvorene iz poveznice, grupirane prema njihovom statusu:

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

U ovom primjeru, kupac je imao jedan neuspjeli pokušaj (narudžba 0d79014c... u statusu error) prije uspjeha (narudžba 3bb663cc... u statusu completed). Potpune detalje bilo koje narudžbe možete dohvatiti putem GET /v1/orders/{order_id}/.

Statusi poveznice za plaćanje

StatusOpis
newPoveznica je stvorena, ali nije napravljen nijedan pokušaj plaćanja.
processingPokušaj plaćanja je trenutno u tijeku.
all_unsuccessfulSvi dosadašnji pokušaji plaćanja nisu uspjeli. Kupac još uvijek može pokušati ponovo (do 25 pokušaja).
completedPlaćanje je uspjelo. Poveznica više nije aktivna.
expiredPoveznica je istekla prije uspješnog plaćanja.

Status all_unsuccessful nije konačni status. Kupac još uvijek može pokušati platiti sve dok plaćanje ne uspije, dok se ne dosegne maksimalni broj pokušaja (25) ili dok poveznica ne istekne.

Nakon što poveznica za plaćanje dosegne status completed ili expired, ne može se ponovno koristiti. Stvorite novu poveznicu za plaćanje ako kupac treba ponovo platiti.

Primjer tijeka rada

  1. Stvorite poveznicu za plaćanje putem POST /v1/paymentlinks/.
  2. Podijelite vraćeni payment_url sa svojim kupcem (npr. putem e-pošte, SMS-a ili računa).
  3. Kupac otvara poveznicu i dovršava plaćanje.
  4. Cost+ šalje webhook na vaš webhook_url kada se status promijeni.
  5. Provjerite status poveznice za plaćanje putem GET /v1/paymentlinks/{id}/.
  6. Ispunite narudžbu kada je status completed.

Povezane krajnje točke

On this page