---
title: "Create a new payout batch for all CONVERTED cross-border transactions"
method: POST
path: "/api/v1/admin/merchants/{merchantId}/payouts"
tags: ["Payout", "Admin"]
---

# Create a new payout batch for all CONVERTED cross-border transactions

`POST /api/v1/admin/merchants/{merchantId}/payouts`

## Request

- Base URL: `https://core.quidkey.com`
- URL: `https://core.quidkey.com/api/v1/admin/merchants/{merchantId}/payouts`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/banqzinc/apis/quidkey-api/docs/api/v1/admin/merchants/:merchantId/payouts/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new payout batch for all CONVERTED cross-border transactions

## Path parameters

- `merchantId` string, uuid, required: The unique identifier of the merchant

## Response `201`

Created

- PayoutBatchResponse: Response containing a single payout batch
  - `success` boolean, required: Indicates if the request was successful
  - `data` object, required: A batch of transactions to be paid out to a merchant
    - `id` string, uuid, required: Unique identifier for the payout batch
    - `payment_reference` string, required: Short payment reference code for the payout batch
    - `merchant_id` string, uuid, required: Merchant ID for this payout batch
    - `source_account_id` string, uuid: ID of the receiving bank account used as the source for this payout
    - `status` union, required: Status of the payout batch
      - 'pending'
      - 'processing'
      - 'completed'
      - 'failed'
    - `currency` string, required: Currency of the payout
    - `gross_amount` string, required: Total transaction amount before fees, in the payout currency
    - `fees_total` string, required: Total fees deducted, in the payout currency
    - `net_amount` string, required: Net amount after fees (gross_amount - fees_total), in the payout currency
    - `transaction_count` number, required: Number of transactions included in this payout
    - `payout_amount` string: Amount transferred to the settlement account
    - `retained_amount` string: Amount retained for the refund account
    - `retention_rate` string: Retention rate applied (e.g. 0.1000 for 10%)
    - `retention_reference` string: Payment reference for the retention transfer
    - `retention_tm_transaction_id` string: TransferMate transaction ID for the retention transfer
    - `tm_transaction_id` string: TransferMate transaction ID for the payout
    - `error_message` string: Error message if the payout failed
    - `executed_at` string, date-time: When the payout was executed
    - `created_at` string, date-time, required: When the payout batch was created
    - `updated_at` string, date-time, required: When the payout batch was last updated

## Other responses

- `400`: Bad Request
- `401`: Unauthorized

## Changes

- **2026-06-17** `b372e7d5563d`: 1 info
  - endpoint added
- **2025-11-02** `919eb7a392aa`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/banqzinc/apis/quidkey-api/changes/api/v1/admin/merchants/:merchantId/payouts/post.md)

---

[API](https://skmtc.dev/banqzinc/apis/quidkey-api.md) - [All operations](https://skmtc.dev/banqzinc/apis/quidkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/banqzinc/apis/quidkey-api/revisions/f86d2bdbcb08?raw)