Bidu Malajr
Aċċetta l-ewwel ħlas tiegħek fi 5 minuti
Din il-gwida tmexxik pass pass biex toħloq u tlesti ħlas ta' test bl-użu tal-API ta' Cost+. Fl-aħħar, ikollok integrazzjoni li taħdem li tista' tibni fuqha.
Prerekwiżiti
- Kont Cost+ b'website sandbox — oħloq waħda fil-Portal tal-Kummerċjant
- Iċ-ċavetta API sandbox tiegħek (tinsab taħt Websites → il-website sandbox tiegħek → Integration)
Mhux żgur kif tikseb iċ-ċavetta API tiegħek? Ara Ittestjar tal-Integrazzjoni għal istruzzjonijiet dettaljati dwar is-setup.
Pass 1: Oħloq Ordni
Ibgħat talba POST biex toħloq ordni ta' ħlas. Ibdel YOUR_API_KEY biċ-ċavetta API sandbox tiegħek:
curl -X POST https://api.costplus.online/v1/orders/ \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-first-order",
"description": "Test order",
"return_url": "https://example.com/return",
"webhook_url": "https://example.com/webhook",
"transactions": [
{
"payment_method": "credit-card"
}
]
}'Iż-amount huwa numru sħiħ fl-unità minuri ISO 4217 tal-munita. Għal EUR, 1295 tfisser 12.95 EUR.
L-API tirritorna l-oġġett sħiħ tal-ordni. L-oqsma ewlenin huma id, status, u l-payment_url ġewwa t-tranżazzjoni:
{
"id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
"status": "new",
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-first-order",
"description": "Test order",
"return_url": "https://example.com/return",
"webhook_url": "https://example.com/webhook",
"created": "2026-01-15T12:00:05.433502+00:00",
"modified": "2026-01-15T12:00:05.553125+00:00",
"expiration_period": "PT1H",
"transactions": [
{
"id": "d291f03f-a406-428a-967a-4895a46e03fd",
"payment_method": "credit-card",
"status": "new",
"amount": 1295,
"currency": "EUR",
"payment_url": "https://api.costplus.online/pay/4851e31c.../select-payment-method/credit-card/d291f03f...",
"is_capturable": false,
"expiration_period": "PT30M"
}
]
}Il-forma tar-rispons tiddependi fuq dak li tibgħat:
- B'array
transactions(din il-quickstart): kull oġġett ta' tranżazzjoni fihpayment_urltiegħu stess. Idderiġi lill-klijent hemmhekk. - Mingħajr
transactions: l-ordni għandu minflokorder_urlfl-ogħla livell, u l-klijent jagħżel metodu ta' ħlas fuq il-paġna ospitata minn Cost+. Ara l-gwida Hosted Payment Page għal dan il-fluss.
Issejvja l-id — se jkollok bżonnha fil-Pass 3.
Pass 2: Lesti l-Ħlas ta' Test
- Iftaħ il-
payment_urlmir-risposta fil-browser tiegħek - Fuq il-paġna tal-ħlas, daħħal id-dettalji tal-karta tat-test:
| Qasam | Valur |
|---|---|
| Numru tal-karta | 4111 1111 1111 1111 |
| Skadenza | Kwalunkwe data futura (eż. 12/28) |
| CVC | Kwalunkwe 3 ċifri (eż. 123) |
- Issottometti l-ħlas
- Se tiġi ridirezzjonat lura lejn ir-
return_urltiegħek
Tiddependix biss fuq ir-redirect biex tikkonferma l-ħlas. Il-klijent jista' jagħlaq il-browser qabel ma jiġi ridirezzjonat. Dejjem ivverifika permezz tal-API (Pass 3) jew webhooks (Pass 4).
Pass 3: Ivverifika l-Ħlas
Iġbed l-ordni biex tikkonferma li tlestiet:
curl -u YOUR_API_KEY: \
https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/Ħlas li rnexxielu jidher hekk:
{
"id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
"status": "completed",
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-first-order",
"completed": "2026-01-15T12:02:30.123456+00:00",
"transactions": [
{
"id": "d291f03f-a406-428a-967a-4895a46e03fd",
"payment_method": "credit-card",
"status": "completed",
"amount": 1295,
"currency": "EUR",
"payment_method_details": {
"truncated_pan": "1111",
"card_expiry": "122028"
}
}
]
}L-istatus tal-ordni hija "completed" — il-ħlas irnexxielu.
Pass 4: Ittratta l-Webhook (Rakkomandat)
Meta l-istatus tal-ħlas tinbidel, Cost+ tibgħat talba POST lejn il-webhook_url tiegħek:
{
"event": "status_changed",
"order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}Meta tirċievi dan:
- Sejjaħ
GET /v1/orders/{order_id}/biex tivverifika l-istatus kurrenti (qatt tafda l-payload tal-webhook waħdu) - Irritorna HTTP
200biex tikkonferma r-riċevuta - Issodisfa l-ordni jekk l-istatus hija
"completed"
Għall-iżvilupp lokali, uża tunnel bħal ngrok biex tesponi s-server lokali tiegħek u tirċievi webhooks.
Ara l-gwida tal-Webhooks għal-loġika tar-retry, l-aħjar prattiċi, u dettalji tal-payload.
Alternattiva: Links tal-Ħlas
Jekk m'għandekx bżonn loġika ta' redirect fuq is-server, links tal-ħlas joffru triq aktar sempliċi. Oħloq link, aqsam l-URL mal-klijent tiegħek, u ċċekkja l-istatus aktar tard.
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": 2500,
"currency": "EUR",
"description": "Invoice #1234"
}'Ir-risposta tinkludi payment_url li tista' taqsam permezz ta' email, SMS, jew chat. Il-klijent jista' jipprova l-ħlas diversi drabi (sa 25) sakemm il-link jiskadi jew il-ħlas jirnexxielu.
Ara l-gwida tal-Links tal-Ħlas għall-workflow sħiħ.
X'Jmiss?
Lestejt l-ewwel ħlas tiegħek. Hawn fejn tista' tmur minn hawn:
- Paġna ta' Ħlas Ospitata — referenza sħiħa tal-HPP bl-oqsma u l-opzjonijiet kollha tat-talba
- Ħlasijiet Rikorrenti — issettja abbonamenti u fatturazzjoni skedata
- Ħlasijiet b'Klikk Waħda — checkout malajr għal klijenti li jerġgħu jiġu
- Auth / Capture / Void — awtorizza l-ewwel, aqbad aktar tard (eż. meta tibgħat)
- Rifużjonijiet — ipproċessa rifużjonijiet sħaħ u parzjali
- SDKs — libreriji uffiċjali għal Node.js, Python, PHP, Java/Kotlin, C#/.NET, u Ruby
- Plugins — integrazzjonijiet lesti għal Shopify, WooCommerce, Magento, u aktar
Endpoints Relatati
- Oħloq Ordni — referenza sħiħa tal-API għall-ħolqien tal-ordni
- Ikseb Ordni — iġbed id-dettalji u l-istatus tal-ordni
- Oħloq Link tal-Ħlas — oħloq links tal-ħlas li jistgħu jerġgħu jintużaw