DocsAutorisierungen, Erfassungen & Stornierungen
Zahlungsautorisierung, Erfassung und Stornierungsabläufe verwalten
Einige Zahlungsmethoden unterstützen einen zweistufigen Ablauf: zuerst autorisieren (Geld reservieren), dann erfassen (Geld einziehen) oder stornieren (Reservierung freigeben).
Erfassungsmodi
Setzen Sie capture_mode in der Bestellung, um zu steuern, wann Gelder erfasst werden:
| Modus | Verhalten |
|---|---|
manual | Sie erfassen explizit, wenn Sie bereit sind (z. B. nach dem Versand). Wenn Sie vor Ablauf der Bestellung nicht erfassen, geht die Autorisierung verloren und kann nicht mehr erfasst werden. |
delayed | Gelder werden automatisch erfasst, wenn die expiration_period abläuft. |
{
"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"
}
]
}Bei manual Capture müssen Sie vor Ablauf der Bestellungsfrist erfassen. Nach Ablauf wird die Autorisierung freigegeben und die Gelder können nicht mehr erfasst werden. Setzen Sie eine angemessene expiration_period für Ihren Erfüllungszeitraum.
Sie können capture_mode auf Bestellungsebene setzen, ohne transactions anzugeben. Die gehostete Zahlungsseite zeigt dann nur Zahlungsmethoden an, die den angegebenen Erfassungsmodus unterstützen.
Erfassbare Beträge prüfen
Vor der Erfassung können Sie überprüfen, wie viel zur Erfassung verfügbar ist, indem Sie amount_details anfordern:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"Die Antwort enthält ein amount_details-Objekt:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Bestellpositionen
Bei der Verwendung von Erfassungen und Stornierungen nach Bestellposition verwenden Sie diese Typen:
| Typ | Beschreibung |
|---|---|
physical | Physisches Produkt |
discount | Rabattbetrag |
shipping_fee | Versandkosten |
sales_tax | Umsatzsteuer |
digital | Digitales Produkt |
gift_card | Geschenkkarte |
store_credit | Guthaben |
surcharge | Zuschlag |
Zahlungen erfassen
Erfassung nach Bestellposition
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Erfassung nach Betrag
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Zahlungen stornieren
Eine Stornierung gibt die autorisierten Gelder an den Kunden zurück.
Stornierung nach Bestellposition
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Stornierung nach Betrag
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Abfrageparameter
Fügen Sie Abfrageparameter hinzu, um zusätzliche Details in der Antwort einzuschließen:
| Parameter | Beschreibung |
|---|---|
?fields[]=order_line_details | Bestellpositionsaufschlüsselung einschließen |
?fields[]=amount_details | Betragsaufschlüsselung einschließen |
Optimistisches Sperren
Erfassungs- und Stornierungsendpunkte unterstützen ETag-basiertes optimistisches Sperren über den if-match-Header. Dies verhindert Race Conditions, wenn mehrere Systeme versuchen, dieselbe Transaktion zu erfassen.
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}'Wenn der ETag nicht übereinstimmt (die Bestellung wurde seit Ihrer letzten Abfrage geändert), erhalten Sie eine 412 Precondition Failed-Antwort.
Cost+ unterstützt eine Erfassung pro Autorisierung, und Stornierungen können nur vor einer Erfassung verarbeitet werden. Planen Sie Ihre Erfassungsstrategie entsprechend.
Verwandte Endpunkte
- Erfassung nach Betrag — einen bestimmten Betrag von einer autorisierten Bestellung erfassen
- Erfassung nach Bestellposition — bestimmte Bestellpositionen erfassen
- Stornierung nach Betrag — einen bestimmten Betrag einer autorisierten Bestellung stornieren
- Stornierung nach Bestellposition — bestimmte Bestellpositionen stornieren