Fizetési linkek

A fizetési linkek újrafelhasználható URL-ek, amelyek lehetővé teszik az ügyfelek számára a rendelés kifizetését. A standard rendelésekkel ellentétben, amelyek egyetlen sikertelen kísérlet után lejárnak, a fizetési linkek többszöri újrapróbálkozást támogatnak, így ideálisak számlákhoz, e-mail alapú fizetésekhez és olyan forgatókönyvekhez, ahol az ügyfél nem feltétlenül fizet azonnal.

Főbb jellemzők

Újrafelhasználható: Az ügyfelek legfeljebb 25 alkalommal próbálkozhatnak újra, ha korábbi kísérleteik sikertelenek.
Hosszú élettartam: Az alapértelmezett lejárat 30 nap (konfigurálható az expiration_period mezővel).
Megosztható: Küldje el a linket e-mailben, SMS-ben, chaten, vagy ágyazza be a weboldalába.

Fizetési link létrehozása

Küldjön egy POST kérést a /v1/paymentlinks/ végpontra:

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

A válasz tartalmazza az ügyfélnek megosztandó payment_url-t és egy egyedi id-t a nyomon követéshez:

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

Mentse el az id értéket — a fizetési link állapotának későbbi ellenőrzéséhez fogja használni.

Kötelező mezők

Mező	Leírás
`merchant_order_id`	Az Ön saját referenciaazonosítója a fizetési linkhez
`amount`	Összeg centben (pl. 9,95 EUR = `995`)
`currency`	ISO 4217 pénznemkód (pl. `EUR`, `GBP`)

Opcionális mezők

Mező	Leírás
`description`	Az ügyfélnek megjelenített leírás
`expiration_period`	ISO 8601 időtartam. Az alapértelmezett `P30D` (30 nap)
`return_url`	URL, ahová az ügyfelet sikeres fizetés után irányítjuk
`failure_url`	URL, ahová az ügyfelet törlés, lejárat vagy hiba esetén irányítjuk
`webhook_url`	URL az állapotváltozási értesítések fogadásához
`customer`	Ügyfél adatok objektum (név, e-mail stb.)

Ha megadja a return_url és a failure_url értéket is, az ügyfeleket a failure_url címre irányítjuk, amikor a rendelés állapota cancelled, expired vagy error. Egyébként minden átirányítás a return_url címre történik.

Fizetési link lekérdezése

Küldjön egy GET kérést a /v1/paymentlinks/{id}/ végpontra a létrehozási válaszból kapott fizetési link id használatával:

GET /v1/paymentlinks/{id}/

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

A válasz tartalmazza az aktuális állapotot és a linkből létrehozott összes rendelésre mutató hivatkozásokat, állapotuk szerint csoportosítva:

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

Ebben a példában az ügyfél egy sikertelen kísérletet tett (a 0d79014c... rendelés error állapotban), mielőtt sikerrel járt volna (a 3bb663cc... rendelés completed állapotban). Bármely rendelés teljes részleteit lekérheti a GET /v1/orders/{order_id}/ végponton.

Fizetési link állapotok

Állapot	Leírás
`new`	A link létrejött, de még nem történt fizetési kísérlet.
`processing`	Fizetési kísérlet van jelenleg folyamatban.
`all_unsuccessful`	Eddig minden fizetési kísérlet sikertelen volt. Az ügyfél még újrapróbálkozhat (legfeljebb 25 kísérlet).
`completed`	A fizetés sikeres volt. A link már nem aktív.
`expired`	A link lejárt, mielőtt sikeres fizetés történt volna.

Az all_unsuccessful állapot nem végleges állapot. Az ügyfél továbbra is megkísérelheti a fizetést, amíg a fizetés sikerrel nem jár, el nem éri a maximális kísérletek számát (25), vagy a link le nem jár.

Miután egy fizetési link eléri a completed vagy expired állapotot, nem használható újra. Hozzon létre új fizetési linket, ha az ügyfélnek újra fizetnie kell.

Példa munkafolyamat

Hozzon létre fizetési linket a POST /v1/paymentlinks/ végponton.
Ossza meg a kapott payment_url-t az ügyfelével (pl. e-mailben, SMS-ben vagy számlán).
Az ügyfél megnyitja a linket és befejezi a fizetést.
A Cost+ webhookot küld az Ön webhook_url címére, amikor az állapot megváltozik.
Ellenőrizze a fizetési link állapotát a GET /v1/paymentlinks/{id}/ végponton.
Teljesítse a rendelést, amint az állapot completed.

Kapcsolódó végpontok

Fizetési link létrehozása — újrafelhasználható fizetési link létrehozása
Fizetési link lekérdezése — fizetési link aktuális állapotának lekérdezése

On this page