Autorisaties, Captures & Voids

Sommige betaalmethoden ondersteunen een tweestaps-flow: eerst autoriseren (fondsen reserveren), daarna capturen (de fondsen innen) of voiden (de reservering vrijgeven).

Capture-modi

Stel capture_mode in op de bestelling om te bepalen wanneer fondsen worden geind:

Modus	Gedrag
`manual`	U capturt expliciet wanneer u klaar bent (bijv. na verzending). Als u niet capturt voordat de bestelling verloopt, gaat de autorisatie verloren en kan niet meer worden gecaptured.
`delayed`	Fondsen worden automatisch gecaptured op het moment dat de `expiration_period` verstrijkt.

POST /v1/orders/ (handmatige capture)

{
  "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"
    }
  ]
}

Bij manual capture moet u capturen voordat de verloopperiode van de bestelling eindigt. Eenmaal verlopen wordt de autorisatie vrijgegeven en kunnen de fondsen niet meer worden gecaptured. Stel een passende expiration_period in voor uw verwerkingstijdlijn.

U kunt capture_mode op bestellingsniveau instellen zonder transactions op te geven. De hosted payment page toont dan alleen betaalmethoden die de opgegeven capture-modus ondersteunen.

Captureerbare bedragen controleren

Voordat u capturt, kunt u controleren hoeveel beschikbaar is voor capture door amount_details op te vragen:

curl -u YOUR_API_KEY: \
  "https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"

De respons bevat een amount_details-object:

{
  "amount": 5000,
  "amount_details": {
    "capturable": 5000,
    "captured": 0,
    "refundable": 0,
    "refunded": 0,
    "voidable": 5000,
    "voided": 0
  }
}

Orderregels

Bij het gebruik van captures en voids per orderregel, gebruik deze typen:

Type	Beschrijving
`physical`	Fysiek product
`discount`	Kortingsbedrag
`shipping_fee`	Verzendkosten
`sales_tax`	Omzetbelasting
`digital`	Digitaal product
`gift_card`	Cadeaukaart
`store_credit`	Winkeltegoed
`surcharge`	Toeslag

Betalingen capturen

Capture per orderregel

POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines

Verzoekbody

{
  "description": "Shipping item #1",
  "order_line": {
    "merchant_order_line_id": "item-001",
    "quantity": 1
  }
}

Capture per bedrag

POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount

Verzoekbody

{
  "description": "Partial capture",
  "amount": 2500
}

Betalingen voiden

Void geeft de geautoriseerde fondsen terug aan de klant.

Void per orderregel

POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines

Verzoekbody

{
  "description": "Voiding item #2",
  "order_line": {
    "merchant_order_line_id": "item-002",
    "quantity": 1
  }
}

Void per bedrag

POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount

Verzoekbody

{
  "description": "Partial void",
  "amount": 1500
}

Queryparameters

Voeg queryparameters toe om aanvullende details in de respons op te nemen:

Parameter	Beschrijving
`?fields[]=order_line_details`	Orderregeluitsplitsing opnemen
`?fields[]=amount_details`	Bedraguitsplitsing opnemen

Optimistische vergrendeling

Capture- en void-eindpunten ondersteunen ETag-gebaseerde optimistische vergrendeling via de if-match-header. Dit voorkomt race conditions wanneer meerdere systemen proberen dezelfde transactie te capturen.

Capture met optimistische vergrendeling

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}'

Als de ETag niet overeenkomt (de bestelling is gewijzigd sinds u deze voor het laatst heeft opgehaald), ontvangt u een 412 Precondition Failed-respons.

Cost+ ondersteunt een capture per autorisatie, en voids kunnen alleen worden verwerkt voor een capture. Plan uw capture-strategie dienovereenkomstig.

Gerelateerde eindpunten

Capture per bedrag — een specifiek bedrag capturen van een geautoriseerde bestelling
Capture per orderregel — specifieke orderregels capturen
Void per bedrag — een specifiek bedrag voiden van een geautoriseerde bestelling
Void per orderregel — specifieke orderregels voiden

On this page