---
title: "Batch Refund Payments"
method: PUT
path: "/merchant/payments/refunds/batch"
tags: ["merchant"]
---

# Batch Refund Payments

`PUT /merchant/payments/refunds/batch`

Queues a full refund for each of the given payments. Every payment is refunded
independently - one refund job per payment, identical to refunding them one at a
time - so a payment that cannot be refunded is reported in `results` while the rest
still proceed.

Partial amounts are not supported here, and payments needing a destination wallet
are skipped with `skipped: true` on their result. Refund those payments
individually with `PUT /merchant/payments/{paymentId}/refund`.

## Headers

- `Authorization` string, required

## Request body

- BatchRefundRequest
  - `paymentIds` string[], required — Ids of the payments to refund in full. Maximum of 100 per request.
  - `refundReason` 'userCancellation' | 'failedFulfillment' | 'buyerFraud' | 'other', required

## Response `200`

Ok

- BatchRefundResponse
  - `queued` number, double, required — Number of refunds successfully queued.
  - `failed` number, double, required — Number of payments that failed to queue and may be worth retrying.
  - `skipped` number, double, required — Number of payments skipped because batch refunds cannot process them.
  - `results` BatchRefundResult[], required
    - `paymentId` string, required
    - `success` boolean, required
    - `jobId` string — Id of the queued refund job, present when the refund was queued.
    - `error` string — Why the refund could not be queued, present when it was not.
    - `skipped` boolean — True when this payment is unsupported by batch refunds and was skipped. Refund it on its own instead; retrying the batch will not help.

---

[API](https://skmtc.dev/coinflow/apis/api-reference.md) · [All operations](https://skmtc.dev/coinflow/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/coinflow/api-reference/revisions/430f04d8d2a9/schema)