A reversal refunds a successful payment back to your customer. Vendy returns the money to the customer's bank account or payment card.
How long it takesOnce Vendy receives a reversal, it begins processing it straight away. The money can take 7 to 14 business days to reach the customer's bank account or payment card, depending on the payment method used to complete the payment.
Process flow
flowchart TD
A["Successful payment"] --> B["POST /reversals/create"]
B -->|"Checks fail"| X["400 error, nothing changes"]
B -->|"Dashboard session and approval required"| P["202 Approval required"]
P -->|"Approved by your team"| C
B --> C["Wallet debited<br/>status: pending"]
C --> W1(["reversal_created"])
C --> D{"Vendy processes the reversal<br/>7 to 14 business days"}
D -->|"Money returned to the customer"| E["status: completed<br/>payment marked reversed"]
E --> W2(["reversal_processed"])
D -->|"Declined"| F["status: failed<br/>wallet credited back"]
F --> W3(["reversal_declined"])
- Find the payment. Get the
refidof a successful payment, for example from Get Transactions or atransaction_successwebhook. Only successful payments can be reversed. - Make sure your wallet can cover it. The wallet the payment was paid into must have enough available balance for the payment amount, less any fee you paid on it.
- Request the reversal. Call Create Reversal with the payment's
refidastranRef, the customer's reason and your own. Vendy checks the payment, debits your wallet, returns your fee, reverses any commission and creates the reversal with statuspending. If your business requires approval for reversals, requests from the dashboard wait for approval first. - Vendy processes it. Once the reversal is received, Vendy begins processing it and returns the money to the customer's bank account or payment card within 7 to 14 business days, depending on the payment method used to complete the payment.
- Track the outcome. Listen for reversal webhooks, or poll Get Reversals:
- Completed: the money has been returned to the customer. You receive
reversal_processedand the payment is marked as reversed. - Declined: the reversal is
failed, the money goes back into your wallet and you receivereversal_declinedwith the reason inmeta.admin_reason. You can request a new reversal for the payment.
- Completed: the money has been returned to the customer. You receive
One reversal per payment at a timeWhile a payment has a
pending,activeorprocessingreversal, another request for it is rejected. A payment that has been reversed (completed) can't be reversed again.
Authentication
Send your merchant keys as headers on every request:
--header 'AccessKey: YOUR_ACCESS_KEY' \
--header 'SecretKey: YOUR_SECRET_KEY'| Permission | Grants |
|---|---|
reversals:create | Create Reversal |
reversals:read | Get Reversals |
reversals:manage | Both |
Statuses
| Status | Meaning |
|---|---|
pending | Received; your wallet has been debited and processing is starting |
active, processing | Vendy is returning the money to the customer |
completed | The money was returned to the customer's bank account or payment card. Final |
failed | Declined; the money was returned to your wallet. Final, but you can request a new reversal |
cancelled | Cancelled before processing. Final |
blocked | Reversals aren't allowed for this payment |
Endpoints
| Endpoint | Description |
|---|---|
POST /reversals/create | Request a reversal |
GET /reversals | List your reversals |
Errors
Errors return HTTP 400 (or 403 for missing permissions) with status: false and a Vendy code:
{
"status": false,
"code": 367,
"msg": "Reversal already placed for this transaction"
}Each endpoint page lists the codes it can return.
