DocsAutorizace, zachycení a zrušení
Správa toků autorizace, zachycení a zrušení plateb
Některé platební metody podporují dvoukrokový tok: nejprve autorizace (rezervace prostředků), poté zachycení (stržení prostředků) nebo zrušení (uvolnění rezervace).
Režimy zachycení
Nastavte capture_mode na objednávce pro kontrolu, kdy jsou prostředky zachyceny:
| Režim | Chování |
|---|---|
manual | Prostředky zachytíte explicitně, když jste připraveni (např. po odeslání). Pokud nezachytíte před vypršením objednávky, autorizace je ztracena a nelze ji zachytit. |
delayed | Prostředky jsou automaticky zachyceny v okamžiku vypršení expiration_period. |
{
"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"
}
]
}S režimem manual zachycení musíte zachytit prostředky před vypršením doby platnosti objednávky. Po vypršení je autorizace uvolněna a prostředky nelze zachytit. Nastavte vhodný expiration_period pro váš proces plnění.
Můžete nastavit capture_mode na úrovni objednávky bez uvedení transactions. Hostovaná platební stránka pak zobrazí pouze platební metody, které podporují zvolený režim zachycení.
Kontrola zachytitelných částek
Před zachycením můžete zkontrolovat, kolik je k dispozici pro zachycení, dotazem na amount_details:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"Odpověď obsahuje objekt amount_details:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Řádky objednávky
Při použití zachycení a zrušení podle řádku objednávky používejte tyto typy:
| Typ | Popis |
|---|---|
physical | Fyzický produkt |
discount | Sleva |
shipping_fee | Náklady na dopravu |
sales_tax | DPH |
digital | Digitální produkt |
gift_card | Dárková karta |
store_credit | Kredit obchodu |
surcharge | Příplatek |
Zachycení plateb
Zachycení podle řádku objednávky
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Zachycení podle částky
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Zrušení plateb
Zrušení uvolní autorizované prostředky zpět zákazníkovi.
Zrušení podle řádku objednávky
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Zrušení podle částky
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Parametry dotazu
Přidejte parametry dotazu pro zahrnutí dalších detailů v odpovědi:
| Parametr | Popis |
|---|---|
?fields[]=order_line_details | Zahrnout rozpis řádků objednávky |
?fields[]=amount_details | Zahrnout rozpis částek |
Optimistické zamykání
Endpointy pro zachycení a zrušení podporují optimistické zamykání na základě ETag prostřednictvím hlavičky if-match. To zabraňuje race conditions, když se více systémů pokouší zachytit stejnou transakci.
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}'Pokud ETag neodpovídá (objednávka byla od vašeho posledního načtení změněna), obdržíte odpověď 412 Precondition Failed.
Cost+ podporuje jedno zachycení na autorizaci a zrušení lze zpracovat pouze před jakýmkoli zachycením. Plánujte svou strategii zachycení odpovídajícím způsobem.
Související endpointy
- Zachycení podle částky — zachycení konkrétní částky z autorizované objednávky
- Zachycení podle řádku objednávky — zachycení konkrétních řádků objednávky
- Zrušení podle částky — zrušení konkrétní částky z autorizované objednávky
- Zrušení podle řádku objednávky — zrušení konkrétních řádků objednávky