Cost+Docs

Links tal-Ħlas

Oħloq links tal-ħlas li jistgħu jerġgħu jintużaw

Il-links tal-ħlas huma URLs li jistgħu jerġgħu jintużaw li jippermettu lill-klijenti jħallsu għal ordni. B'differenza mill-ordnijiet standard li jiskadu wara tentattiv fallut wieħed, il-links tal-ħlas jappoġġjaw tentattivi multipli ta' retry, u dan jagħmilhom ideali għal fatturi, ħlasijiet ibbażati fuq l-email, u xenarji fejn il-klijent jista' ma jħallasx immedjatament.

Karatteristiċi Ewlenin

  • Jistgħu jerġgħu jintużaw: Il-klijenti jistgħu jerġgħu jippruvaw il-ħlas sa 25 darba jekk tentattivi preċedenti jfallu.
  • Fit-tul: L-iskadenza default hija 30 jum (konfigurabbli permezz ta' expiration_period).
  • Jistgħu jiġu mqassma: Ibgħat il-link permezz ta' email, SMS, chat, jew inkorporah fuq il-website tiegħek.

Ibgħat talba POST lejn /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"
  }'

Ir-risposta tinkludi l-payment_url biex taqsamha mal-klijent u id uniku għat-traċċar:

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

Issejvja l-id — se tużah biex tiċċekkja l-istatus tal-link tal-ħlas aktar tard.

Oqsma Meħtieġa

QasamDeskrizzjoni
merchant_order_idL-ID ta' referenza tiegħek għal-link tal-ħlas
amountAmmont fl-unità minuri ISO 4217 tal-munita (eż., 9.95 EUR = 995)
currencyKodiċi tal-munita ISO 4217 (eż., EUR, GBP)

Oqsma Opzjonali

QasamDeskrizzjoni
descriptionDeskrizzjoni murija lill-klijent
expiration_periodTul ta' żmien ISO 8601. Default hija P30D (30 jum)
return_urlURL biex tirridirezzjona l-klijent wara ħlas li rnexxielu
failure_urlURL biex tirridirezzjona l-klijent f'każ ta' kanċellazzjoni, skadenza, jew żball
webhook_urlURL biex tirċievi notifiki ta' bidla fl-istatus
customerOġġett tad-dettalji tal-klijent (isem, email, eċċ.)

Jekk tipprovdi kemm return_url u failure_url, il-klijenti jiġu ridirezzjonati lejn failure_url meta l-istatus tal-ordni hija cancelled, expired, jew error. Inkella, ir-redirects kollha jmorru lejn return_url.

Ibgħat talba GET lejn /v1/paymentlinks/{id}/ bl-użu tal-id tal-link tal-ħlas mir-risposta tal-ħolqien:

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

Ir-risposta tinkludi l-istatus kurrenti u referenzi għall-ordnijiet kollha maħluqa mill-link, raggruppati skont l-istatus tagħhom:

Risposta (eżempju komplutat)
{
  "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"]
  }
}

F'dan l-eżempju, il-klijent għamel tentattiv wieħed li falli (ordni 0d79014c... bl-istatus error) qabel ma rnexxielu (ordni 3bb663cc... bl-istatus completed). Tista' tiġbed id-dettalji sħaħ ta' kwalunkwe ordni permezz ta' GET /v1/orders/{order_id}/.

StatusDeskrizzjoni
newIl-link inħoloq iżda l-ebda tentattiv ta' ħlas għadu ma sar.
processingTentattiv ta' ħlas bħalissa qed isir.
all_unsuccessfulIt-tentattivi ta' ħlas kollha s'issa fallew. Il-klijent xorta jista' jerġa jipprova (sa 25 tentattiv).
completedIl-ħlas irnexxielu. Il-link m'għadux attiv.
expiredIl-link skada qabel ma sar ħlas li rnexxielu.

L-istatus all_unsuccessful mhijiex status finali. Il-klijent xorta jista' jipprova jħallas mill-ġdid sakemm il-ħlas jirnexxielu, jintlaħaq in-numru massimu ta' tentattivi (25), jew il-link jiskadi.

Ladarba link tal-ħlas jilħaq l-istatus completed jew expired, ma jistax jintuża mill-ġdid. Oħloq link tal-ħlas ġdid jekk il-klijent ikollu bżonn iħallas mill-ġdid.

Eżempju ta' Workflow

  1. Oħloq link tal-ħlas permezz ta' POST /v1/paymentlinks/.
  2. Aqsam il-payment_url rritornata mal-klijent tiegħek (eż., permezz ta' email, SMS, jew fattura).
  3. Il-klijent jiftaħ il-link u jlesti l-ħlas.
  4. Cost+ tibgħat webhook lejn il-webhook_url tiegħek meta l-istatus tinbidel.
  5. Ivverifika l-istatus tal-link tal-ħlas permezz ta' GET /v1/paymentlinks/{id}/.
  6. Issodisfa l-ordni ladarba l-istatus hija completed.

Endpoints Relatati

On this page