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.
Ħolqien ta' Link tal-Ħlas
Ibgħat talba POST lejn /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:
{
"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
| Qasam | Deskrizzjoni |
|---|---|
merchant_order_id | L-ID ta' referenza tiegħek għal-link tal-ħlas |
amount | Ammont fl-unità minuri ISO 4217 tal-munita (eż., 9.95 EUR = 995) |
currency | Kodiċi tal-munita ISO 4217 (eż., EUR, GBP) |
Oqsma Opzjonali
| Qasam | Deskrizzjoni |
|---|---|
description | Deskrizzjoni murija lill-klijent |
expiration_period | Tul ta' żmien ISO 8601. Default hija P30D (30 jum) |
return_url | URL biex tirridirezzjona l-klijent wara ħlas li rnexxielu |
failure_url | URL biex tirridirezzjona l-klijent f'każ ta' kanċellazzjoni, skadenza, jew żball |
webhook_url | URL biex tirċievi notifiki ta' bidla fl-istatus |
customer | Oġġ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.
Iġbed Link tal-Ħlas
Ibgħat talba GET lejn /v1/paymentlinks/{id}/ bl-użu tal-id tal-link tal-ħlas mir-risposta tal-ħolqien:
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:
{
"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}/.
Statuses tal-Link tal-Ħlas
| Status | Deskrizzjoni |
|---|---|
new | Il-link inħoloq iżda l-ebda tentattiv ta' ħlas għadu ma sar. |
processing | Tentattiv ta' ħlas bħalissa qed isir. |
all_unsuccessful | It-tentattivi ta' ħlas kollha s'issa fallew. Il-klijent xorta jista' jerġa jipprova (sa 25 tentattiv). |
completed | Il-ħlas irnexxielu. Il-link m'għadux attiv. |
expired | Il-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
- Oħloq link tal-ħlas permezz ta'
POST /v1/paymentlinks/. - Aqsam il-
payment_urlrritornata mal-klijent tiegħek (eż., permezz ta' email, SMS, jew fattura). - Il-klijent jiftaħ il-link u jlesti l-ħlas.
- Cost+ tibgħat webhook lejn il-
webhook_urltiegħek meta l-istatus tinbidel. - Ivverifika l-istatus tal-link tal-ħlas permezz ta'
GET /v1/paymentlinks/{id}/. - Issodisfa l-ordni ladarba l-istatus hija
completed.
Endpoints Relatati
- Oħloq Link tal-Ħlas — oħloq link tal-ħlas li jista' jerġa jintuża
- Ikseb Link tal-Ħlas — iġbed l-istatus kurrenti ta' link tal-ħlas