Linkuri de plată

Linkurile de plată sunt URL-uri reutilizabile care permit clienților să plătească o comandă. Spre deosebire de comenzile standard care expiră după o singură tentativă eșuată, linkurile de plată suportă mai multe reîncercări, fiind ideale pentru facturi, plăți prin email și scenarii în care clientul nu plătește imediat.

Caracteristici principale

Reutilizabile: Clienții pot reîncerca plata de până la 25 de ori dacă tentativele anterioare eșuează.
Durată lungă de viață: Expirarea implicită este de 30 de zile (configurabilă prin expiration_period).
Partajabile: Trimiteți linkul prin email, SMS, chat sau integrați-l pe site-ul dvs.

Crearea unui link de plată

Trimiteți o cerere POST la /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"
  }'

Răspunsul include payment_url pentru a-l partaja cu clientul și un id unic pentru urmărire:

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

Salvați id — îl veți folosi pentru a verifica statusul linkului de plată ulterior.

Câmpuri obligatorii

Câmp	Descriere
`merchant_order_id`	ID-ul dvs. de referință propriu pentru linkul de plată
`amount`	Suma în cenți (de ex., 9,95 EUR = `995`)
`currency`	Cod valutar ISO 4217 (de ex., `EUR`, `GBP`)

Câmpuri opționale

Câmp	Descriere
`description`	Descriere afișată clientului
`expiration_period`	Durată ISO 8601. Implicit este `P30D` (30 de zile)
`return_url`	URL pentru redirecționarea clientului după plata reușită
`failure_url`	URL pentru redirecționarea clientului la anulare, expirare sau eroare
`webhook_url`	URL pentru a primi notificări de schimbare a statusului
`customer`	Obiect cu detaliile clientului (nume, email, etc.)

Dacă furnizați atât return_url cât și failure_url, clienții sunt redirecționați la failure_url când statusul comenzii este cancelled, expired sau error. Altfel, toate redirecționările merg la return_url.

Preluarea unui link de plată

Trimiteți o cerere GET la /v1/paymentlinks/{id}/ folosind id-ul linkului de plată din răspunsul de creare:

GET /v1/paymentlinks/{id}/

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

Răspunsul include statusul curent și referințe la toate comenzile create din link, grupate după statusul lor:

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

În acest exemplu, clientul a avut o tentativă eșuată (comanda 0d79014c... cu statusul error) înainte de a reuși (comanda 3bb663cc... cu statusul completed). Puteți prelua detaliile complete ale oricărei comenzi prin GET /v1/orders/{order_id}/.

Statusurile linkului de plată

Status	Descriere
`new`	Linkul a fost creat, dar nu s-a efectuat nicio tentativă de plată.
`processing`	O tentativă de plată este în curs de desfășurare.
`all_unsuccessful`	Toate tentativele de plată de până acum au eșuat. Clientul poate încă reîncerca (până la 25 de tentative).
`completed`	Plata a fost efectuată cu succes. Linkul nu mai este activ.
`expired`	Linkul a expirat înainte ca o plată să fie efectuată cu succes.

Statusul all_unsuccessful nu este un status final. Clientul poate încă să încerce să plătească din nou până când plata reușește, se atinge numărul maxim de tentative (25) sau linkul expiră.

Odată ce un link de plată ajunge la statusul completed sau expired, nu mai poate fi utilizat din nou. Creați un link de plată nou dacă clientul trebuie să plătească din nou.

Exemplu de flux de lucru

Creați un link de plată prin POST /v1/paymentlinks/.
Partajați payment_url returnat cu clientul (de ex., prin email, SMS sau factură).
Clientul deschide linkul și finalizează plata.
Cost+ trimite un webhook la webhook_url când statusul se schimbă.
Verificați statusul linkului de plată prin GET /v1/paymentlinks/{id}/.
Onorați comanda odată ce statusul este completed.

Endpoint-uri asociate

Creare link de plată — creați un link de plată reutilizabil
Obținere link de plată — preluați statusul curent al unui link de plată

On this page