DocsAutorizări, Capturi și Anulări
Gestionați fluxurile de autorizare, captură și anulare a plăților
Unele metode de plată suportă un flux în doi pași: mai întâi autorizați (rezervați fonduri), apoi capturați (colectați fondurile) sau anulați (eliberați rezervarea).
Moduri de captură
Setați capture_mode pe comandă pentru a controla când sunt capturate fondurile:
| Mod | Comportament |
|---|---|
manual | Capturați explicit când sunteți pregătit (de ex., după expediere). Dacă nu capturați înainte ca comanda să expire, autorizarea este pierdută și nu poate fi capturată. |
delayed | Fondurile sunt capturate automat în momentul în care expiration_period se scurge. |
{
"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"
}
]
}Cu captura manual, trebuie să capturați înainte ca perioada de expirare a comenzii să se încheie. Odată expirată, autorizarea este eliberată și fondurile nu pot fi capturate. Setați o expiration_period adecvată pentru termenul dvs. de onorare.
Puteți seta capture_mode la nivel de comandă fără a specifica transactions. Pagina de plată găzduită va afișa atunci doar metodele de plată care suportă modul de captură specificat.
Verificarea sumelor disponibile pentru captură
Înainte de a captura, puteți verifica cât este disponibil pentru captură solicitând amount_details:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"Răspunsul include un obiect amount_details:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Linii de comandă
Când folosiți capturi și anulări pe linie de comandă, utilizați aceste tipuri:
| Tip | Descriere |
|---|---|
physical | Produs fizic |
discount | Sumă de reducere |
shipping_fee | Cost de expediere |
sales_tax | Taxă de vânzare |
digital | Produs digital |
gift_card | Card cadou |
store_credit | Credit de magazin |
surcharge | Suprataxă |
Capturarea plăților
Captură pe linie de comandă
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Captură pe sumă
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Anularea plăților
Anularea eliberează fondurile autorizate înapoi către client.
Anulare pe linie de comandă
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Anulare pe sumă
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Parametri de interogare
Adăugați parametri de interogare pentru a include detalii suplimentare în răspuns:
| Parametru | Descriere |
|---|---|
?fields[]=order_line_details | Include detalii pe linie de comandă |
?fields[]=amount_details | Include detalii despre sumă |
Blocare optimistă
Endpoint-urile de captură și anulare suportă blocare optimistă bazată pe ETag prin headerul if-match. Aceasta previne condițiile de cursă când mai multe sisteme încearcă să captureze aceeași tranzacție.
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}'Dacă ETag-ul nu corespunde (comanda a fost modificată de la ultima dvs. preluare), veți primi un răspuns 412 Precondition Failed.
Cost+ suportă o singură captură per autorizare, iar anulările pot fi procesate doar înainte de orice captură. Planificați strategia de captură în consecință.
Endpoint-uri asociate
- Captură pe sumă — capturați o sumă specifică dintr-o comandă autorizată
- Captură pe linie de comandă — capturați linii de comandă specifice
- Anulare pe sumă — anulați o sumă specifică dintr-o comandă autorizată
- Anulare pe linie de comandă — anulați linii de comandă specifice