DocsAutorizaciones, capturas y anulaciones
Gestiona flujos de autorizacion, captura y anulacion de pagos
Algunos metodos de pago soportan un flujo en dos pasos: primero autorizar (reservar fondos), luego capturar (cobrar los fondos) o anular (liberar la reserva).
Modos de captura
Establece capture_mode en el pedido para controlar cuando se capturan los fondos:
| Modo | Comportamiento |
|---|---|
manual | Capturas explicitamente cuando estes listo (ej., despues del envio). Si no capturas antes de que expire el pedido, la autorizacion se pierde y no puede capturarse. |
delayed | Los fondos se capturan automaticamente en el momento en que transcurre el 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"
}
]
}Con captura manual, debes capturar antes de que termine el periodo de expiracion del pedido. Una vez expirado, la autorizacion se libera y los fondos no pueden capturarse. Establece un expiration_period adecuado para tu plazo de procesamiento.
Puedes establecer capture_mode a nivel de pedido sin especificar transactions. La pagina de pago alojada mostrara entonces solo los metodos de pago que soporten el modo de captura especificado.
Consultar importes capturables
Antes de capturar, puedes verificar cuanto esta disponible para captura solicitando amount_details:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"La respuesta incluye un objeto amount_details:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Lineas de pedido
Al usar capturas y anulaciones por linea de pedido, utiliza estos tipos:
| Tipo | Descripcion |
|---|---|
physical | Producto fisico |
discount | Importe de descuento |
shipping_fee | Coste de envio |
sales_tax | Impuesto sobre ventas |
digital | Producto digital |
gift_card | Tarjeta regalo |
store_credit | Credito de tienda |
surcharge | Recargo |
Capturar pagos
Captura por linea de pedido
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Captura por importe
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Anular pagos
La anulacion libera los fondos autorizados de vuelta al cliente.
Anulacion por linea de pedido
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Anulacion por importe
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Parametros de consulta
Agrega parametros de consulta para incluir detalles adicionales en la respuesta:
| Parametro | Descripcion |
|---|---|
?fields[]=order_line_details | Incluir desglose de lineas de pedido |
?fields[]=amount_details | Incluir desglose de importes |
Bloqueo optimista
Los endpoints de captura y anulacion soportan bloqueo optimista basado en ETag mediante el encabezado if-match. Esto previene condiciones de carrera cuando multiples sistemas intentan capturar la misma transaccion.
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}'Si el ETag no coincide (el pedido fue modificado desde la ultima vez que lo consultaste), recibiras una respuesta 412 Precondition Failed.
Cost+ soporta una captura por autorizacion, y las anulaciones solo pueden procesarse antes de cualquier captura. Planifica tu estrategia de captura en consecuencia.
Endpoints relacionados
- Captura por importe — capturar un importe especifico de un pedido autorizado
- Captura por linea de pedido — capturar lineas de pedido especificas
- Anulacion por importe — anular un importe especifico de un pedido autorizado
- Anulacion por linea de pedido — anular lineas de pedido especificas