Reembolsos V2 (Sandbox)
La API de Reembolsos V2 te permite crear reembolsos totales o parciales de una transacción aprobada, con soporte para hasta 5 referencias personalizadas y la posibilidad de simular escenarios deterministas en el ambiente Sandbox.
La versión nueva de reembolsos se expone en el endpoint POST /v1/refunds.
El simulador de Sandbox para reembolsos aplica únicamente para la versión nueva (V2) expuesta en POST /v1/refunds. La versión anterior (V1) en POST /v1/transactions/:id/refunds no procesa los atributos extendidos de referencias ni interactúa con la lógica de Sandbox V2.
Autenticación
La API de Reembolsos V2 requiere estrictamente Llave Privada (prv_*) enviada como token Bearer.
- Header requerido:
Authorization: Bearer <LLAVE_PRIVADA> - Sandbox:
prv_test_... - Producción:
prv_prod_...
Las peticiones sin autenticación o con Llave Pública (pub_*) no están permitidas y retornarán 401 Unauthorized / 403 Forbidden.
Contrato de solicitud (Request Body V2)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
transaction_id | string | Sí | ID de la transacción aprobada que se quiere reembolsar. |
amount_in_cents | integer | Sí | Monto total o parcial, en centavos, a reembolsar. Ejemplo: para $100.00 se escribe 10000. |
reason | string | No | Motivo del reembolso. |
reference | string | No | Referencia personalizada 1. |
reference_2 | string | No | Referencia personalizada 2. |
reference_3 | string | No | Referencia personalizada 3. |
reference_4 | string | No | Referencia personalizada 4. |
reference_5 | string | No | Referencia personalizada 5. |
{
"transaction_id": "trx_test_123456789",
"amount_in_cents": 15000,
"reason": "Solicitud del cliente",
"reference": "REF_001",
"reference_2": "REF_002",
"reference_3": "REF_003",
"reference_4": "REF_004",
"reference_5": "REF_005"
}
Ejemplo de solicitud (cURL)
curl -i -X POST https://api-sandbox.wompi.pa/v1/refunds \
-H "Authorization: Bearer prv_test_XXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{
"transaction_id": "1688-1788842576-38603",
"amount_in_cents": 15000,
"reason": "Solicitud del cliente",
"reference": "REF_001",
"reference_2": "REF_002",
"reference_3": "REF_003",
"reference_4": "REF_004",
"reference_5": "REF_005"
}'
Ejemplo de respuesta exitosa
{
"data": {
"id": 1523,
"status": "APPROVED",
"status_message": "",
"v2_refund_id": "v2_refund_abc123",
"amount_in_cents": 15000,
"transaction_id": "1688-1788842576-38603",
"reference": "REF_001",
"reference_2": "REF_002",
"reference_3": "REF_003",
"reference_4": "REF_004",
"reference_5": "REF_005",
"created_at": "2024-01-15 14:30:45 UTC"
}
}
Escenarios de prueba en Sandbox
En Sandbox puedes simular los cinco estados finales del reembolso de forma determinista. Cada estado se alcanza mediante el campo test_scenario en la solicitud, y todas las solicitudes deben pasar validaciones previas.
| Escenario | Condición de prueba en Sandbox | Estado esperado | Código HTTP |
|---|---|---|---|
| 1. Aprobado (Exitoso) | test_scenario: "approved" + transaction_id de transacción aprobada + amount_in_cents válido según check_amount_restriction | Estado APPROVED, asignación de v2_refund_id y reflejo de las referencias en la respuesta | 201 Created |
| 2. Declinado (Por tiempo límite) | test_scenario: "declined" | Estado DECLINED, status_message: "Tiempo límite sin encontrar fondos excedido", cancelled_at: null | 201 Created |
| 3. Error (Técnico) | test_scenario: "error" | Estado ERROR, status_message: "Error en la comunicación con el autorizador", cancelled_at: null | 201 Created |
| 4. Cancelado (Por comercio) | test_scenario: "cancelled" | Estado CANCELLED, status_message: null, cancelled_at: [timestamp] | 201 Created |
| 5. Validación (Más de 5 referencias) | Incluir más de 5 campos reference en la solicitud | Estado UNPROCESSABLE ENTITY, código de error INPUT_VALIDATION_ERROR | 422 Unprocessable Entity |
Disponibilidad regional
La API de Reembolsos V2 está disponible para:
Referencia del API
Consulta el detalle completo del endpoint en la referencia del API.
