Оторизации, улавяния и анулирания
Управлявайте потоците за оторизация, улавяне и анулиране на плащания
Някои методи на плащане поддържат двустъпков поток: първо оторизиране (резервиране на средства), след това улавяне (събиране на средствата) или анулиране (освобождаване на резервацията).
Режими на улавяне
Задайте capture_mode на поръчката, за да контролирате кога се улавят средствата:
| Режим | Поведение |
|---|---|
manual | Вие изрично улавяте, когато сте готови (напр. след изпращане). Ако не уловите преди изтичане на поръчката, оторизацията е загубена и не може да бъде уловена. |
delayed | Средствата се улавят автоматично в момента на изтичане на 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"
}
]
}При manual улавяне трябва да уловите преди изтичане на периода на валидност на поръчката. След изтичане оторизацията се освобождава и средствата не могат да бъдат уловени. Задайте подходящ expiration_period за вашата времева рамка за изпълнение.
Можете да зададете capture_mode на ниво поръчка без да посочвате transactions. Хостваната страница за плащане тогава ще показва само методи на плащане, които поддържат посочения режим на улавяне.
Проверка на суми за улавяне
Преди улавяне можете да проверите колко е налично за улавяне, като поискате amount_details:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"Отговорът включва обект amount_details:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Редове на поръчката
При използване на улавяне и анулиране по ред на поръчка, използвайте следните типове:
| Тип | Описание |
|---|---|
physical | Физически продукт |
discount | Сума на отстъпка |
shipping_fee | Разходи за доставка |
sales_tax | Данък продажби |
digital | Дигитален продукт |
gift_card | Подаръчна карта |
store_credit | Кредит в магазина |
surcharge | Допълнителна такса |
Улавяне на плащания
Улавяне по ред на поръчка
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Улавяне по сума
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Анулиране на плащания
Анулирането освобождава оторизираните средства обратно на клиента.
Анулиране по ред на поръчка
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Анулиране по сума
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Параметри на заявката
Добавете параметри на заявката, за да включите допълнителни детайли в отговора:
| Параметър | Описание |
|---|---|
?fields[]=order_line_details | Включете разбивка по редове на поръчката |
?fields[]=amount_details | Включете разбивка на сумите |
Оптимистично заключване
Крайните точки за улавяне и анулиране поддържат оптимистично заключване на базата на ETag чрез хедъра if-match. Това предотвратява състезателни условия, когато множество системи се опитват да уловят една и съща транзакция.
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}'Ако ETag-ът не съвпада (поръчката е била модифицирана, откакто последно сте я извлекли), ще получите отговор 412 Precondition Failed.
Cost+ поддържа едно улавяне на оторизация, а анулирания могат да се обработват само преди каквото и да е улавяне. Планирайте стратегията си за улавяне съответно.
Свързани крайни точки
- Улавяне по сума — уловете конкретна сума от оторизирана поръчка
- Улавяне по ред на поръчка — уловете конкретни редове на поръчка
- Анулиране по сума — анулирайте конкретна сума от оторизирана поръчка
- Анулиране по ред на поръчка — анулирайте конкретни редове на поръчка