Paġna ta' Ħlas Ospitata (HPP)
Aċċetta ħlasijiet bl-użu tal-paġna ta' ħlas ospitata ta' Cost+
Il-Paġna ta' Ħlas Ospitata (HPP) hija l-formola ta' ħlas konformi mal-PCI DSS ta' Cost+. Tippermetti li taċċetta ħlasijiet mingħajr ma tittratta data sensittiva tal-karti fuq is-servers tiegħek stess. Toħloq ordni permezz tal-API, tirridirezzjona l-klijent lejn il-paġna ospitata, u dawn jirritornaw fuq is-sit tiegħek wara l-ħlas.
Kif Taħdem
- Is-server tiegħek joħloq ordni billi jsejjaħ POST /v1/orders/.
- L-API tirritorna URL li tiponta lejn il-paġna ta' ħlas ospitata.
- Tirridirezzjona l-klijent lejn il-paġna ta' ħlas.
- Il-klijent jlesti l-ħlas fuq il-paġna ospitata ta' Cost+.
- Il-klijent jiġi ridirezzjonat lura lejn ir-
return_urltiegħek (jewfailure_urlgħal ħlasijiet li fallew). - Cost+ tibgħat notifika webhook lejn il-
webhook_urltiegħek bl-istatus tal-ordni.
Il-paġna ta' ħlas ospitata hija kompletament konformi mal-PCI DSS. Qatt m'għandek bżonn tittratta numri ta' karti mhux ipproċessati jew data sensittiva ta' ħlas fuq is-servers tiegħek.
Ħolqien ta' Ordni
Hemm żewġ approċċi biex tuża l-HPP:
Approċċ 1: Uri l-Metodi ta' Ħlas Kollha (L-Aktar Sempliċi)
Oħloq ordni mingħajr ma tispeċifika transactions. Ir-risposta tinkludi order_url — il-klijent jiġi ridirezzjonat hemm u jara l-metodi ta' ħlas kollha attivati għall-kont tiegħek:
{
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-order-id-1",
"description": "My amazing order",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook"
}{
"id": "43114fde-da30-4115-8004-b7f808f9b25c",
"status": "new",
"currency": "EUR",
"amount": 1295,
"order_url": "https://api.costplus.online/pay/43114fde.../select-payment-method/",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook"
}Irridirezzjona l-klijent lejn l-order_url. Fuq il-paġna ospitata, il-metodi ta' ħlas kollha attivati jidhru.
Approċċ 2: Agħżel il-Metodi ta' Ħlas Minn Qabel
Oħloq ordni **b'**array ta' transactions biex tikkontrolla liema metodi ta' ħlas jidhru u f'liema ordni. Kull tranżazzjoni tinkludi payment_method, u r-risposta tirritorna payment_url ġewwa l-oġġett tat-tranżazzjoni:
{
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-order-id-1",
"description": "My amazing order",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook",
"transactions": [
{ "payment_method": "credit-card" }
]
}{
"id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
"status": "new",
"currency": "EUR",
"amount": 1295,
"transactions": [
{
"id": "d291f03f-a406-428a-967a-4895a46e03fd",
"payment_method": "credit-card",
"status": "new",
"payment_url": "https://api.costplus.online/pay/4851e31c.../select-payment-method/credit-card/d291f03f.../"
}
]
}Irridirezzjona l-klijent lejn il-payment_url mit-tranżazzjoni.
Jekk tipprovdi entry waħda biss fl-array transactions, il-klijent jittieħed direttament għal dik il-metodu ta' ħlas mingħajr ma jara skrin ta' selezzjoni. L-array flags fih "is-test" meta tuża ċavetta API sandbox.
Oqsma tat-Talba
| Qasam | Meħtieġ | Deskrizzjoni |
|---|---|---|
currency | Iva | Kodiċi tal-munita ISO 4217 (eż., EUR, GBP, SEK) |
amount | Iva | Ammont fl-unità minuri ISO 4217 tal-munita. Pereżempju, 12.95 EUR huwa rappreżentat bħala 1295 |
merchant_order_id | Le | L-ID ta' referenza tiegħek għall-ordni |
return_url | Le | URL biex tirridirezzjona l-klijent wara l-ħlas (default għall-istatus kollha) |
failure_url | Le | URL biex tirridirezzjona l-klijent b'status cancelled, expired, jew error (ara URLs ta' Ritorn hawn taħt) |
locale | Le | Lingwa għall-paġna ta' ħlas. Appoġġjati: en-GB, de-DE, nl-NL, nl-BE, fr-BE, sv-SE, no-NO, da-DK |
description | Le | Deskrizzjoni tal-ordni, murija lill-klijent |
payment_methods | Nru | Iffiltra għal metodu ta' ħlas wieħed (eż. ["credit-card"]). Oqgħod barra milli turi l-metodi kollha attivati. Għal metodi speċifiċi multipli, uża l-firxa transactions minflok |
webhook_url | Le | URL biex tirċievi notifiki ta' bidla fl-istatus |
expiration_period | Le | Tul ta' żmien ISO 8601 għall-iskadenza tal-ordni. Default hija PT30M (30 minuta) |
Il-qasam amount huwa dejjem numru sħiħ fl-unità minuri ISO 4217 tal-munita. Għal EUR, 1295 tfisser 12.95 EUR; muniti żero u tliet deċimali jużaw l-esponent ISO 4217 tagħhom stess. Jekk tgħaddi valur deċimali bħal 1295.00 jew 12.95 jirriżulta fi żball jew ħlas mhux korrett.
Metodi ta' Ħlas Multipli
Hemm żewġ modi kif tikkontrolla liema metodi ta' ħlas jidhru fuq il-paġna ospitata:
Għażla A — payment_methods (filtru wieħed). Għaddi firxa ta' element wieħed biex tirrestrinġi l-ordni għal metodu wieħed ta' ħlas. Ħalli barra l-qasam għal kollox biex turi l-metodi kollha attivati għall-kont tiegħek.
Għażla B — Array transactions (rakkomandat għal metodi multipli). Żid dħul wieħed għal kull metodu ta' ħlas. Kull tranżazzjoni tieħu payment_url tagħha stess, u l-metodi jidhru f'ordni ta' firxa fuq il-paġna ospitata:
"transactions": [
{ "payment_method": "credit-card" },
{ "payment_method": "apple-pay" }
]Il-qasam payment_methods fuq ordnijiet jaċċetta l-iktar valur wieħed. Biex toffri metodi speċifiċi multipli, dejjem uża l-firxa transactions. Jekk għandek bżonn rabta li tista 'terġa' tintuża b'metodi ta 'ħlas multipli, ikkunsidra Payment Links minflok, li jappoġġjaw firxa payment_methods vera.
URLs ta' Ritorn
Wara l-ħlas, il-klijent jiġi ridirezzjonat skont l-istatus tal-ordni u liema URLs ipprovdejt:
-
Meta kemm
return_urlufailure_urlhuma ssettjati:cancelled,expired, jewerror→ il-klijent jiġi ridirezzjonat lejnfailure_url- L-istatus l-oħra kollha → il-klijent jiġi ridirezzjonat lejn
return_url
-
Meta
return_urlbiss hija ssettjata:- L-istatus kollha → il-klijent jiġi ridirezzjonat lejn
return_url
- L-istatus kollha → il-klijent jiġi ridirezzjonat lejn
Uża failure_url biex turi paġna ta' retry jew appoġġ għal ħlasijiet falluti, filwaqt li return_url turi konferma tal-ordni. Jekk għandek bżonn destinazzjoni waħda biss, return_url waħedha hija biżżejjed.
Imġiba tal-Buttuna Cancel
Il-paġna ta' ħlas ospitata tinkludi buttuna cancel. Meta l-klijent jikklikkjaha, jiġi ridirezzjonat lejn failure_url (jekk ipprovduta) jew return_url. L-istatus tal-ordni tinbidel għal cancelled. Dejjem ivverifika l-istatus tal-ordni permezz tal-API jew webhooks minflok tiddependi fuq ir-redirect biss.
Endpoints Relatati
- Oħloq Ordni — oħloq ordni ta' ħlas u rċievi l-
payment_url - Ikseb Ordni — iċċekkja l-istatus tal-ordni wara l-ħlas