Refunds

Refund a payment programmatically over the public merchant API. You can refund a payment in full or in part, and a partially-refunded payment can be refunded again (any number of times) until its full amount has been returned. The proportional processing fee is returned to you along with the refund.

A refund only ever touches a payment that belongs to your account — the payment id is resolved within your own merchant scope, so you can never refund another merchant's payment.

Required API-key permissions

This endpoint is part of the public merchant API and is API-key-authenticated. It requires the payment.refund scope. This scope is part of the default payment permission group, so most keys already have it — if yours does not, grant it to your key under Settings → Developer Settings:

• payment.refund — required for POST /merchant/payment/:id/refund.

Authentication

Calls authenticate exactly like the rest of the API: exchange your key + secret for a short-lived access token via POST /merchant/api-auth/login (with the x-api-key / x-api-secret headers), then send that token as Authorization: Bearer <token>. See the Authentication section for the full flow.

Refund a payment — POST /v1/merchant/payment/:id/refund

Requires the payment.refund scope.

:id is the payment's id — the same id returned when the payment (or secure-payment / embed checkout) was created, and the id listed by GET /v1/merchant/payment.

Request body

• amount (optional) — the amount to refund in major units (e.g. 10.00), in the same currency as the original payment. Omit it for a FULL refund of the remaining refundable balance. Include it for a PARTIAL refund — it must be greater than zero and ≤ the remaining refundable balance.
• reason (optional) — a short note recorded with the refund (e.g. "customer request").

Full refund (omit `amount`):

curl -X POST https://api.vezmo.com/api/v1/merchant/payment/PAYMENT_ID/refund \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "customer request" }'

Partial refund (include `amount`):

curl -X POST https://api.vezmo.com/api/v1/merchant/payment/PAYMENT_ID/refund \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10.00, "reason": "customer request" }'

Success response

200 OK:

{
  "success": true,
  "message": "Refund processed",
  "data": {
    "paymentId": "cmq17im8p0001abcd", // the payment that was refunded
    "amount": 10.00,                  // amount refunded by THIS call
    "currency": "USD",
    "fullyRefunded": false,           // true once the whole payment is refunded
    "refundedTotal": 10.00,           // running total refunded across all refunds
    "status": "partially_refunded"    // "refunded" | "partially_refunded"
  }
}

Field meanings:

• amount — the amount returned by this specific call.
• refundedTotal — the cumulative amount refunded on this payment so far (including this call).
• fullyRefunded — true when this call exhausted the remaining refundable balance; the payment's status becomes refunded. Otherwise it is partially_refunded and you can refund the remainder later.

Errors

The endpoint returns a clean, descriptive error in these cases:

• 404 — the payment was not found (or does not belong to your account).
• 422 — the requested amount exceeds the remaining refundable balance.
• 400 — an invalid amount (e.g. zero or negative), or the payment can't be refunded (for example: not a successful captured payment, already fully refunded, or under dispute).
• 401 — missing or invalid access token.
• 403 — your API key lacks the payment.refund permission.

404 — payment not found.

{
  "statusCode": 404,
  "message": "Payment not found."
}

422 — amount exceeds the refundable balance.

{
  "statusCode": 422,
  "message": "Refund amount exceeds the refundable balance."
}

400 — payment can't be refunded. (e.g. it is under dispute, already fully refunded, or was never a successful capture.)

{
  "statusCode": 400,
  "message": "This payment can't be refunded."
}

Test mode (sandbox)

Use a test API key against the same base URL https://api.vezmo.com — create a test payment, then refund it: omit amount for a full refund, or include it for a partial one and refund the remainder in a later call. Sandbox refunds work even while your account is still under review.

Keys and payments are mode-locked: a test key can only refund test payments, and a live key only live ones. Crossing modes returns 404 Payment not found — the same response as an unknown id.