DocsAutoryzacje, przechwycenia i anulowania
Zarządzanie przepływami autoryzacji, przechwytywania i anulowania płatności
Niektóre metody płatności obsługują dwuetapowy przepływ: najpierw autoryzacja (rezerwacja środków), a następnie przechwycenie (pobranie środków) lub anulowanie (zwolnienie rezerwacji).
Tryby przechwytywania
Ustaw capture_mode na zamówieniu, aby kontrolować, kiedy środki są pobierane:
| Tryb | Zachowanie |
|---|---|
manual | Przechwytywanie następuje jawnie, gdy jesteś gotowy (np. po wysyłce). Jeśli nie przechwycisz przed wygaśnięciem zamówienia, autoryzacja zostaje utracona i nie można już pobrać środków. |
delayed | Środki są automatycznie pobierane w momencie upływu 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"
}
]
}Przy trybie manual musisz dokonać przechwycenia przed upływem okresu ważności zamówienia. Po wygaśnięciu autoryzacja jest zwalniana i środki nie mogą zostać pobrane. Ustaw odpowiedni expiration_period dostosowany do harmonogramu realizacji.
Możesz ustawić capture_mode na poziomie zamówienia bez określania transactions. Hostowana strona płatności wyświetli wtedy tylko metody płatności obsługujące wybrany tryb przechwytywania.
Sprawdzanie dostępnych kwot do przechwycenia
Przed przechwyceniem możesz sprawdzić, ile jest dostępne do pobrania, żądając amount_details:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"Odpowiedź zawiera obiekt amount_details:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Pozycje zamówienia
Podczas korzystania z przechwytywania i anulowania według pozycji zamówienia, użyj następujących typów:
| Typ | Opis |
|---|---|
physical | Produkt fizyczny |
discount | Kwota rabatu |
shipping_fee | Koszt wysyłki |
sales_tax | Podatek od sprzedaży |
digital | Produkt cyfrowy |
gift_card | Karta podarunkowa |
store_credit | Kredyt sklepowy |
surcharge | Dopłata |
Przechwytywanie płatności
Przechwycenie według pozycji zamówienia
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Przechwycenie według kwoty
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Anulowanie płatności
Anulowanie zwalnia zaautoryzowane środki z powrotem na konto klienta.
Anulowanie według pozycji zamówienia
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Anulowanie według kwoty
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Parametry zapytania
Dodaj parametry zapytania, aby uwzględnić dodatkowe szczegóły w odpowiedzi:
| Parametr | Opis |
|---|---|
?fields[]=order_line_details | Dołącz szczegółowy podział pozycji zamówienia |
?fields[]=amount_details | Dołącz szczegółowy podział kwot |
Optymistyczne blokowanie
Punkty końcowe przechwytywania i anulowania obsługują optymistyczne blokowanie oparte na ETag za pomocą nagłówka if-match. Zapobiega to wyścigom, gdy wiele systemów próbuje przechwycić tę samą transakcję.
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}'Jeśli ETag nie pasuje (zamówienie zostało zmodyfikowane od ostatniego pobrania), otrzymasz odpowiedź 412 Precondition Failed.
Cost+ obsługuje jedno przechwycenie na autoryzację, a anulowania mogą być przetwarzane tylko przed jakimkolwiek przechwyceniem. Zaplanuj odpowiednio swoją strategię przechwytywania.
Powiązane punkty końcowe
- Przechwycenie według kwoty — przechwycenie określonej kwoty z autoryzowanego zamówienia
- Przechwycenie według pozycji zamówienia — przechwycenie określonych pozycji zamówienia
- Anulowanie według kwoty — anulowanie określonej kwoty z autoryzowanego zamówienia
- Anulowanie według pozycji zamówienia — anulowanie określonych pozycji zamówienia