Cost+Docs

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

  1. Is-server tiegħek joħloq ordni billi jsejjaħ POST /v1/orders/.
  2. L-API tirritorna URL li tiponta lejn il-paġna ta' ħlas ospitata.
  3. Tirridirezzjona l-klijent lejn il-paġna ta' ħlas.
  4. Il-klijent jlesti l-ħlas fuq il-paġna ospitata ta' Cost+.
  5. Il-klijent jiġi ridirezzjonat lura lejn ir-return_url tiegħek (jew failure_url għal ħlasijiet li fallew).
  6. Cost+ tibgħat notifika webhook lejn il-webhook_url tiegħ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:

Talba
{
  "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"
}
Risposta
{
  "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:

Talba
{
  "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" }
  ]
}
Risposta
{
  "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

QasamMeħtieġDeskrizzjoni
currencyIvaKodiċi tal-munita ISO 4217 (eż., EUR, GBP, SEK)
amountIvaAmmont fl-unità minuri ISO 4217 tal-munita. Pereżempju, 12.95 EUR huwa rappreżentat bħala 1295
merchant_order_idLeL-ID ta' referenza tiegħek għall-ordni
return_urlLeURL biex tirridirezzjona l-klijent wara l-ħlas (default għall-istatus kollha)
failure_urlLeURL biex tirridirezzjona l-klijent b'status cancelled, expired, jew error (ara URLs ta' Ritorn hawn taħt)
localeLeLingwa għall-paġna ta' ħlas. Appoġġjati: en-GB, de-DE, nl-NL, nl-BE, fr-BE, sv-SE, no-NO, da-DK
descriptionLeDeskrizzjoni tal-ordni, murija lill-klijent
payment_methodsNruIffiltra 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_urlLeURL biex tirċievi notifiki ta' bidla fl-istatus
expiration_periodLeTul 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_url u failure_url huma ssettjati:

    • cancelled, expired, jew error → il-klijent jiġi ridirezzjonat lejn failure_url
    • L-istatus l-oħra kollha → il-klijent jiġi ridirezzjonat lejn return_url
  • Meta return_url biss hija ssettjata:

    • L-istatus kollha → il-klijent jiġi ridirezzjonat lejn return_url

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

On this page