> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Merchant Batch Transfer

> Create a merchant batch transfer order for reward distribution scenarios.

## Overview

This page documents the `POST /v1/pay/batch/transfer` endpoint, which creates a merchant batch transfer order for reward distribution scenarios. The full request schema, response structure, and examples are rendered from the linked OpenAPI definition above.

## Notes

* Authentication uses the standard GatePay signed headers.
* This endpoint is grouped under `Payout` → `Reward Distribution`.
* `X-GatePay-On-Behalf-Of` is optional for this endpoint. Pass it only when you need to specify the initiating account context in an institution-delegated scenario.
* For shared signing rules, see [/api-reference/version/100/en/common/securityAndSignature](/api-reference/version/100/en/common/securityAndSignature).


## OpenAPI

````yaml api-reference/version/100/en/openapi/withdraw-openapi.json POST /v1/pay/batch/transfer
openapi: 3.1.0
info:
  title: GatePay Withdrawal & Wallet API
  version: 1.0.0
  description: >-
    OpenAPI 3.1 specification for GatePay withdrawal and wallet APIs, based on
    the English withdrawal documentation. It covers batch withdrawals,
    withdrawal status query, supported chains by currency, total balance query,
    and withdrawal fee query.
servers:
  - url: https://openplatform.gateapi.io
    description: Production
security: []
paths:
  /v1/pay/batch/transfer:
    post:
      tags:
        - reward-distribution
      summary: Create merchant batch transfer
      description: >-
        Create a merchant batch transfer order for reward distribution
        scenarios.
      operationId: createMerchantBatchTransfer
      parameters:
        - $ref: '#/components/parameters/X-GatePay-Certificate-ClientId'
        - $ref: '#/components/parameters/X-GatePay-Signature'
        - $ref: '#/components/parameters/X-GatePay-Timestamp'
        - $ref: '#/components/parameters/X-GatePay-Nonce'
        - $ref: '#/components/parameters/X-GatePay-On-Behalf-Of-Optional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RewardDistributionCreateRequest'
            examples:
              default:
                summary: Default example
                value:
                  bizscene: REWARD
                  merchant_batch_no: RB202606300001
                  currency: USDT
                  name: June Reward Distribution
                  description: monthly incentive
                  batchorderList:
                    - user_id: 100001
                      amount: '12.5'
                      currency: USDT
                      rewardId: reward_001
                    - user_id: 100002
                      amount: '8.8'
                      currency: USDT
                      rewardId: reward_002
      responses:
        '200':
          description: Batch transfer creation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardDistributionCreateResponse'
              examples:
                success:
                  summary: Created successfully
                  value:
                    status: SUCCESS
                    code: '000000'
                    errorMessage: ''
                    data:
                      merchant_batch_no: RB202606300001
                      batch_id: '237394559478075550'
components:
  parameters:
    X-GatePay-Certificate-ClientId:
      name: X-GatePay-Certificate-ClientId
      in: header
      required: true
      description: >-
        The clientId assigned when the merchant registers an application in the
        Gate merchant console.
      schema:
        type: string
        example: 4186d0c6-6a35-55a9-8dc6-5312769dbff8
    X-GatePay-Signature:
      name: X-GatePay-Signature
      in: header
      required: true
      description: >-
        Request signature. GatePay uses this signature to verify whether the
        request is valid.
      schema:
        type: string
    X-GatePay-Timestamp:
      name: X-GatePay-Timestamp
      in: header
      required: true
      description: >-
        UTC timestamp in milliseconds when the request is generated. GatePay
        will not process requests where the difference from the receive time
        exceeds 10 seconds.
      schema:
        type: string
        example: '1672905655498'
    X-GatePay-Nonce:
      name: X-GatePay-Nonce
      in: header
      required: true
      description: >-
        Random string. Must comply with HTTP header rules; recommended length is
        within 32 characters, composed of digits and letters.
      schema:
        type: string
        example: '9578'
    X-GatePay-On-Behalf-Of-Optional:
      name: X-GatePay-On-Behalf-Of
      in: header
      required: false
      schema:
        type: string
      description: >-
        Optional delegated-subject header. Pass the initiating account ID only
        when an institution-delegated context needs to be identified; otherwise
        this header can be omitted.
  schemas:
    RewardDistributionCreateRequest:
      type: object
      description: Request body for creating a merchant batch transfer order.
      properties:
        bizscene:
          type: string
          description: Business scenario identifier.
        merchant_batch_no:
          type: string
          description: Merchant batch number. Must be unique on the merchant side.
        currency:
          type: string
          description: Batch transfer currency.
        name:
          type: string
          description: Display name of the batch transfer.
        description:
          type: string
          description: Description of the batch transfer.
        batchorderList:
          type: array
          description: List of transfer sub-orders.
          items:
            $ref: '#/components/schemas/RewardDistributionOrderItem'
        channelId:
          type: string
          description: Channel ID, optional.
        is_coupon:
          type: boolean
          description: Whether this is a coupon scenario. Optional, default is false.
      required:
        - merchant_batch_no
        - currency
        - batchorderList
    RewardDistributionCreateResponse:
      type: object
      description: Response body for creating a merchant batch transfer order.
      properties:
        status:
          type: string
          description: API response result, SUCCESS or FAIL.
        code:
          type: string
          description: Response error code.
        errorMessage:
          type: string
          description: Error description.
        data:
          $ref: '#/components/schemas/RewardDistributionCreateResult'
      required:
        - status
        - code
    RewardDistributionOrderItem:
      type: object
      description: Sub-order item in a merchant batch transfer request.
      properties:
        user_id:
          type: integer
          format: int64
          description: Receiver user ID.
        amount:
          type: string
          description: Transfer amount.
        currency:
          type: string
          description: Currency of the sub-order.
        rewardId:
          type: string
          description: Reward identifier or business-side sub-order identifier.
      required:
        - user_id
        - amount
    RewardDistributionCreateResult:
      type: object
      properties:
        merchant_batch_no:
          type: string
          description: Merchant batch number.
        batch_id:
          type: string
          description: Batch transfer ID generated by GatePay.

````