Refund a payment or handle a chargeback

What you can refund on each method, how to reverse a Débito Inmediato (C2P) payment or refund a peso payment, and how card chargebacks hit your balance and get closed.

What you can refund

Method	Can you refund it?	How
Débito Inmediato (C2P)	Yes, in full	`POST /v1/payments/:id/reverse`
Colombian pesos	Yes, in full, within 96 hours of completion	`POST /v1/cop/payments/:id/refund`
USDT / USDC	No refund API	Send the buyer a normal stablecoin payout with `POST /v1/crypto/payouts` (payout fee applies)
Card	No refund API	Only bank chargebacks, which VEXPay records
Pago Móvil, débito inmediato (OTP)	No refund API	—

Partial refunds are not supported. Subscribe your webhook endpoint to payment.reversed, payment.chargeback and payment.chargeback_closed.

Steps: reverse a Débito Inmediato (C2P) payment

Check the payment
GET /v1/payments/:id must show a COMPLETED C2P payment that was not reversed before.
Reverse it
POST /v1/payments/:id/reverse (up to 5 per hour). If the bank refuses, you get a 400 with its message and nothing changes.
Confirm
The payment becomes REVERSED and payment.reversed arrives with reversalType: "reversal". The full amount leaves your balance and the VEXPay fee is returned. On a split payment, the seller's share is undone too.

curlbash

curl --request POST "${API_URL}/v1/payments/PAYMENT_ID/reverse" \
  --header "x-api-key: ${VEXPAY_API_KEY}"

Steps: refund a peso payment

Keep enough pesos
Your COP balance (available plus held) must cover the net that was credited. Pesos you already converted or withdrew do not count.
Refund it
POST /v1/cop/payments/:id/refund within 96 hours of completion.
Confirm
The payment shows refunded and payment.reversed arrives with status: "refunded". The COP fee is returned.

What happens on a card chargeback

The buyer disputes the charge
VEXPay records the chargeback on the payment and debits your bolívar balance (the original card fee is not returned). If the bank charges a chargeback fee, VEXPay passes on exactly that amount as a separate movement (feeVes, often 0), with nothing added. You receive payment.chargeback; a full chargeback also sends payment.reversed with reversalType: "chargeback".
Book it
GET /v1/payments/:id lists chargebacks[], and the movements appear in GET /v1/balance/transactions?paymentId=…. Book each one once using the ledgerEntryIds in the webhook.
VEXPay disputes it
When it is decided you receive payment.chargeback_closed with outcome. Won: the amount and any chargeback fee come back (held for 24 hours) and the payment returns to COMPLETED. Lost: nothing further moves.

Check that it worked

In Test, pay with the card 4000000000000259: about a minute later a test chargeback arrives with livemode: false.
The reversal, refund or chargeback appears in Portal → Balance movements and the payment shows its new status in Payments.

If something goes wrong

Symptom	Likely cause	What to do
400 "Reversal is not supported for method: …"	Only C2P payments can be reversed	See the table at the top.
400 "Only COMPLETED payments can be reversed"	Wrong status, or already reversed	Check `GET /v1/payments/:id`.
400 with a bank message	The bank refused the reversal	Contact VEXPay; the payment stays `COMPLETED`.
409 `onward_payout_in_progress`	The payment was already converted and sent on as USDT	Contact VEXPay.
429 on reverse	More than 5 reversals in an hour	Retry later.
409 `refund_window_expired`	More than 96 hours since the peso payment completed	No API refund is possible; contact VEXPay support.
409 `insufficient_balance` on a peso refund	Your COP balance does not cover it	Keep enough COP, then retry.