Awtorizzazzjonijiet, Captures u Voids
Immaniġġja l-flussi ta' awtorizzazzjoni, capture, u void tal-ħlas
Xi metodi ta' ħlas jappoġġjaw flusso f'żewġ passi: l-ewwel awtorizza (irriżerva l-fondi), imbagħad aqbad (iġbor il-fondi) jew annulla (irrilaxxa r-riżervazzjoni).
Modalitajiet ta' Capture
Issettja capture_mode fuq l-ordni biex tikkontrolla meta l-fondi jiġu maqbuda:
| Modalità | Imġiba |
|---|---|
manual | Int taqbad espliċitament meta tkun lest (eż., wara l-kunsinna). Jekk ma taqbadx qabel l-ordni tiskadi, l-awtorizzazzjoni tintilef u ma tistax tinqabad. |
delayed | Il-fondi jiġu maqbuda awtomatikament fil-mument li l-expiration_period jgħaddi. |
{
"currency": "EUR",
"amount": 5000,
"capture_mode": "manual",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook",
"transactions": [
{
"payment_method": "credit-card"
}
]
}B'capture manual, trid taqbad qabel ma jgħaddi l-perjodu ta' skadenza tal-ordni. Ladarba jiskadi, l-awtorizzazzjoni tiġi rilaxjata u l-fondi ma jistgħux jinqabdu. Issettja expiration_period xieraq għat-timeline tal-eżekuzzjoni tiegħek.
Tista' tissettja capture_mode fil-livell tal-ordni mingħajr ma tispeċifika transactions. Il-paġna ta' ħlas ospitata mbagħad turi biss metodi ta' ħlas li jappoġġjaw il-modalità ta' capture speċifikata.
Iċċekkja l-Ammonti li Jistgħu Jinqabdu
Qabel taqbad, tista' tiċċekkja kemm hemm disponibbli għall-capture billi titlob amount_details:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"Ir-risposta tinkludi oġġett amount_details:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Linji tal-Ordni
Meta tuża captures u voids bil-linja tal-ordni, uża dawn it-tipi:
| Tip | Deskrizzjoni |
|---|---|
physical | Prodott fiżiku |
discount | Ammont ta' skont |
shipping_fee | Spiża tal-kunsinna |
sales_tax | Taxxa fuq il-bejgħ |
digital | Prodott diġitali |
gift_card | Gift card |
store_credit | Kreditu tal-ħanut |
surcharge | Surcharge |
Qbid tal-Ħlasijiet
Aqbad bil-Linja tal-Ordni
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Aqbad bl-Ammont
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Annullar tal-Ħlasijiet
Il-void jirrilaxxa l-fondi awtorizzati lura lill-klijent.
Annulla bil-Linja tal-Ordni
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Annulla bl-Ammont
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Parametri tal-Query
Żid parametri tal-query biex tinkludi dettalji addizzjonali fir-risposta:
| Parametru | Deskrizzjoni |
|---|---|
?fields[]=order_line_details | Inkludi t-tqassim tal-linji tal-ordni |
?fields[]=amount_details | Inkludi t-tqassim tal-ammonti |
Locking Ottimistiku
L-endpoints ta' capture u void jappoġġjaw locking ottimistiku bbażat fuq ETag permezz tal-header if-match. Dan jipprevjeni kundizzjonijiet ta' tellieqa meta sistemi multipli jippruvaw jaqbdu l-istess tranżazzjoni.
curl -X POST https://api.costplus.online/v1/orders/{id}/transactions/{tid}/captures/amount \
-u {api_key}: \
-H "Content-Type: application/json" \
-H "if-match: \"etag-value\"" \
-d '{"description": "Capture", "amount": 2500}'Jekk l-ETag ma jaqbilx (l-ordni ġiet modifikata minn meta l-aħħar ġbidtha), tirċievi risposta 412 Precondition Failed.
Cost+ tappoġġja capture waħda għal kull awtorizzazzjoni, u l-voids jistgħu jiġu pproċessati biss qabel kwalunkwe capture. Ippjana l-istrateġija ta' capture tiegħek skont dan.
Endpoints Relatati
- Aqbad bl-Ammont — aqbad ammont speċifiku minn ordni awtorizzata
- Aqbad bil-Linja tal-Ordni — aqbad linji speċifiċi tal-ordni
- Annulla bl-Ammont — annulla ammont speċifiku minn ordni awtorizzata
- Annulla bil-Linja tal-Ordni — annulla linji speċifiċi tal-ordni