Skip to main content
POST
Retry a payout batch

Purpose

Retry a failed payout batch.

When to use

When Get a payout shows a batch with status: failed and canRetry: true. Part of the Pay vendors with the API flow.

Request and response

The parameters, request body, code examples (curl and other languages) and a full response example are shown below this section. They are generated from the OpenAPI spec.

Errors

Every error has the shape {"success": false, "error": {"code", "message", "errorId", "details"}}. Branch on error.code.

Previous step

List payout transactions

Next step

Get a payout (poll the retry)

Authorizations

x-access-token
string
header
required

JWT minted from a merchant API key (mk_live_…) by POST /authenticate. Send the token value directly, with no "Bearer" prefix. Tokens last 14 days and can be renewed at POST /refresh-token; revoking the key refuses the next request made with any token minted from it.

Headers

Idempotency-Key
string
required

Required. A unique string you choose, 8–128 characters (a UUID works). Use one key per request you intend to make. Same key and the same body while the first request is still processing: 409 IDEMPOTENCY_IN_PROGRESS. Same key and a different body: 422 IDEMPOTENCY_KEY_REUSED. A new key is a new request.

Required string length: 8 - 128

Path Parameters

batchId
string
required

The legacy batch id (a random 10-char string, not an ObjectId)

Required string length: 1 - 64

Response

Retry accepted; executing asynchronously. Poll GET /payouts/make-payment/{transactionId} for the latest status.

success
boolean
data
object