Reversals and Refunds

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 takes

Once 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"])
  1. Find the payment. Get the refid of a successful payment, for example from Get Transactions or a transaction_success webhook. Only successful payments can be reversed.
  2. 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.
  3. Request the reversal. Call Create Reversal with the payment's refid as tranRef, 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 status pending. If your business requires approval for reversals, requests from the dashboard wait for approval first.
  4. 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.
  5. Track the outcome. Listen for reversal webhooks, or poll Get Reversals:
    • Completed: the money has been returned to the customer. You receive reversal_processed and the payment is marked as reversed.
    • Declined: the reversal is failed, the money goes back into your wallet and you receive reversal_declined with the reason in meta.admin_reason. You can request a new reversal for the payment.
🚧

One reversal per payment at a time

While a payment has a pending, active or processing reversal, 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'
PermissionGrants
reversals:createCreate Reversal
reversals:readGet Reversals
reversals:manageBoth

Statuses

StatusMeaning
pendingReceived; your wallet has been debited and processing is starting
active, processingVendy is returning the money to the customer
completedThe money was returned to the customer's bank account or payment card. Final
failedDeclined; the money was returned to your wallet. Final, but you can request a new reversal
cancelledCancelled before processing. Final
blockedReversals aren't allowed for this payment

Endpoints

EndpointDescription
POST /reversals/createRequest a reversal
GET /reversalsList 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.