Cost+Docs

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
manualInt taqbad espliċitament meta tkun lest (eż., wara l-kunsinna). Jekk ma taqbadx qabel l-ordni tiskadi, l-awtorizzazzjoni tintilef u ma tistax tinqabad.
delayedIl-fondi jiġu maqbuda awtomatikament fil-mument li l-expiration_period jgħaddi.
POST /v1/orders/ (capture manwali)
{
  "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:

TipDeskrizzjoni
physicalProdott fiżiku
discountAmmont ta' skont
shipping_feeSpiża tal-kunsinna
sales_taxTaxxa fuq il-bejgħ
digitalProdott diġitali
gift_cardGift card
store_creditKreditu tal-ħanut
surchargeSurcharge

Qbid tal-Ħlasijiet

Aqbad bil-Linja tal-Ordni

POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines
Korp tat-talba
{
  "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
Korp tat-talba
{
  "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
Korp tat-talba
{
  "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
Korp tat-talba
{
  "description": "Partial void",
  "amount": 1500
}

Parametri tal-Query

Żid parametri tal-query biex tinkludi dettalji addizzjonali fir-risposta:

ParametruDeskrizzjoni
?fields[]=order_line_detailsInkludi t-tqassim tal-linji tal-ordni
?fields[]=amount_detailsInkludi 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.

Capture b'locking ottimistiku
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

On this page