DocsAutorisationer, hævninger og annulleringer
Administrer betalingsautorisation, hævning og annulleringsflows
Nogle betalingsmetoder understøtter et to-trins flow: først autoriser (reserver midler), derefter hæv (opkræv midlerne) eller annuller (frigiv reservationen).
Hævningstilstande
Sæt capture_mode på ordren for at styre, hvornår midler hæves:
| Tilstand | Adfærd |
|---|---|
manual | Du hæver eksplicit, når du er klar (f.eks. efter forsendelse). Hvis du ikke hæver inden ordren udløber, mistes autorisationen og kan ikke hæves. |
delayed | Midler hæves automatisk, når expiration_period udløber. |
{
"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"
}
]
}Med manual hævning skal du hæve inden ordrens udløbsperiode slutter. Når den er udløbet, frigives autorisationen, og midlerne kan ikke hæves. Sæt en passende expiration_period for din leveringstidslinje.
Du kan sætte capture_mode på ordreniveau uden at angive transactions. Den hostede betalingsside vil derefter kun vise betalingsmetoder, der understøtter den angivne hævningstilstand.
Kontrol af hævbare beløb
Inden du hæver, kan du kontrollere, hvor meget der er tilgængeligt for hævning ved at anmode om amount_details:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"Svaret inkluderer et amount_details-objekt:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Ordrelinjer
Ved brug af hævninger og annulleringer per ordrelinje bruges disse typer:
| Type | Beskrivelse |
|---|---|
physical | Fysisk produkt |
discount | Rabatbeløb |
shipping_fee | Forsendelsesomkostning |
sales_tax | Moms |
digital | Digitalt produkt |
gift_card | Gavekort |
store_credit | Butikskredit |
surcharge | Tillæg |
Hævning af betalinger
Hævning per ordrelinje
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Hævning per beløb
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Annullering af betalinger
Annullering frigiver de autoriserede midler tilbage til kunden.
Annullering per ordrelinje
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Annullering per beløb
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Forespørgselsparametre
Tilføj forespørgselsparametre for at inkludere yderligere detaljer i svaret:
| Parameter | Beskrivelse |
|---|---|
?fields[]=order_line_details | Inkluder ordrelinjeopdeling |
?fields[]=amount_details | Inkluder beløbsopdeling |
Optimistisk låsning
Hævnings- og annulleringsendpoints understøtter ETag-baseret optimistisk låsning via if-match-headeren. Dette forhindrer race conditions, når flere systemer forsøger at hæve den samme transaktion.
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}'Hvis ETag'en ikke matcher (ordren er blevet ændret, siden du sidst hentede den), modtager du et 412 Precondition Failed-svar.
Cost+ understøtter én hævning per autorisation, og annulleringer kan kun behandles inden en hævning. Planlæg din hævningsstrategi i overensstemmelse hermed.
Relaterede endpoints
- Hæv per beløb — hæv et specifikt beløb fra en autoriseret ordre
- Hæv per ordrelinje — hæv specifikke ordrelinjer
- Annuller per beløb — annuller et specifikt beløb fra en autoriseret ordre
- Annuller per ordrelinje — annuller specifikke ordrelinjer