Skip to main content
POST
Mark a payout batch as paid outside the engine (asynchronous)

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

Caller-chosen dedupe key, unique per payout you intend to make. Retrying the same request with the same key returns the same requestId and never starts a second run; the engine deduplicates on it. The key is bound to its request (the batchId and the body): the same key on another batch or with a different body is refused with 422 IDEMPOTENCY_KEY_REUSED. A NEW key is a NEW payout: always retry a timed-out or failed-to-connect request with its original key, never a fresh one, or the same items can be paid twice.

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

Body

application/json
markAsPaidMethod
string
required

How the batch was settled (free text, e.g. bankTransfer)

Maximum string length: 120
Example:

"bankTransfer"

markAsPaidComments
string
required

Recorded with the batch; legacy requires both fields

Maximum string length: 2000
Example:

"paid by wire on 2026-03-02"

Response

Replay of a run that already completed under this Idempotency-Key; nothing new was started and the stored result is returned

success
boolean
data
object