Refunds V2 (Sandbox)

The Refunds API V2 lets you create total or partial refunds of an approved transaction, with support for up to 5 custom references and the ability to simulate deterministic scenarios in the Sandbox environment.

V2 Endpoint

The new refunds version is exposed at the POST /v1/refunds endpoint.

Sandbox applicability

The Sandbox simulator for refunds applies only to the new version (V2) exposed at POST /v1/refunds. The legacy version (V1) at POST /v1/transactions/:id/refunds does not process the extended reference attributes nor interact with the Sandbox V2 logic.

Authentication

The Refunds API V2 strictly requires a Private Key (prv_*) sent as a Bearer token.

• Required header: Authorization: Bearer <PRIVATE_KEY>
• Sandbox: prv_test_...
• Production: prv_prod_...

Security restriction

Unauthenticated requests or requests using a Public Key (pub_*) are not allowed and will return 401 Unauthorized / 403 Forbidden.

Request contract (Request Body V2)

Field	Type	Required	Description
transaction_id	string	Yes	ID of the approved transaction to be refunded.
amount_in_cents	integer	Yes	Total or partial amount, in cents, to refund. Example: for $100.00 use 10000.
reason	string	No	Refund reason.
reference	string	No	Custom reference 1.
reference_2	string	No	Custom reference 2.
reference_3	string	No	Custom reference 3.
reference_4	string	No	Custom reference 4.
reference_5	string	No	Custom reference 5.

{
  "transaction_id": "trx_test_123456789",
  "amount_in_cents": 15000,
  "reason": "Customer request",
  "reference": "REF_001",
  "reference_2": "REF_002",
  "reference_3": "REF_003",
  "reference_4": "REF_004",
  "reference_5": "REF_005"
}

Request example (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": "Customer request",
    "reference": "REF_001",
    "reference_2": "REF_002",
    "reference_3": "REF_003",
    "reference_4": "REF_004",
    "reference_5": "REF_005"
  }'

Successful response example

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

Sandbox test scenarios

In Sandbox you can deterministically simulate the five final states of a refund. Each state is reached via the test_scenario field in the request, and all requests must pass pre-validation checks.

Scenario	Sandbox test condition	Expected response	HTTP code
1. Approved (Successful)	test_scenario: "approved" + transaction_id of approved transaction + amount_in_cents valid according to check_amount_restriction	APPROVED status, assignment of v2_refund_id, and the references reflected in the response	201 Created
2. Declined (Time limit)	test_scenario: "declined"	DECLINED status, status_message: "Tiempo límite sin encontrar fondos excedido", cancelled_at: null	201 Created
3. Error (Technical)	test_scenario: "error"	ERROR status, status_message: "Error en la comunicación con el autorizador", cancelled_at: null	201 Created
4. Cancelled (By merchant)	test_scenario: "cancelled"	CANCELLED status, status_message: null, cancelled_at: [timestamp]	201 Created
5. Validation (More than 5 references)	Include more than 5 reference fields in the request	UNPROCESSABLE ENTITY status with error code INPUT_VALIDATION_ERROR	422 Unprocessable Entity

Regional availability

The Refunds API V2 is available for:

• Colombia (COP)
• Panama (USD)

API reference

See the full endpoint detail in the API reference.