Create Merchant Batch Transfer

Create merchant batch transfer

curl --request POST \
  --url https://openplatform.gateapi.io/v1/pay/batch/transfer \
  --header 'Content-Type: application/json' \
  --header 'X-GatePay-Certificate-ClientId: <x-gatepay-certificate-clientid>' \
  --header 'X-GatePay-Nonce: <x-gatepay-nonce>' \
  --header 'X-GatePay-Signature: <x-gatepay-signature>' \
  --header 'X-GatePay-Timestamp: <x-gatepay-timestamp>' \
  --data '
{
  "batchId": "237394559478075550",
  "bizscene": "DIRECT_TRANSFER",
  "merchant_batch_no": "RB202606300001",
  "currency": "USDT",
  "batchorderList": [
    {
      "user_id": 100001,
      "amount": "12.5",
      "currency": "USDT",
      "rewardId": "reward_001"
    },
    {
      "user_id": 100002,
      "amount": "8.8",
      "currency": "USDT",
      "rewardId": "reward_002"
    }
  ]
}
'

import requests

url = "https://openplatform.gateapi.io/v1/pay/batch/transfer"

payload = {
    "batchId": "237394559478075550",
    "bizscene": "DIRECT_TRANSFER",
    "merchant_batch_no": "RB202606300001",
    "currency": "USDT",
    "batchorderList": [
        {
            "user_id": 100001,
            "amount": "12.5",
            "currency": "USDT",
            "rewardId": "reward_001"
        },
        {
            "user_id": 100002,
            "amount": "8.8",
            "currency": "USDT",
            "rewardId": "reward_002"
        }
    ]
}
headers = {
    "X-GatePay-Certificate-ClientId": "<x-gatepay-certificate-clientid>",
    "X-GatePay-Signature": "<x-gatepay-signature>",
    "X-GatePay-Timestamp": "<x-gatepay-timestamp>",
    "X-GatePay-Nonce": "<x-gatepay-nonce>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-GatePay-Certificate-ClientId': '<x-gatepay-certificate-clientid>',
    'X-GatePay-Signature': '<x-gatepay-signature>',
    'X-GatePay-Timestamp': '<x-gatepay-timestamp>',
    'X-GatePay-Nonce': '<x-gatepay-nonce>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    batchId: '237394559478075550',
    bizscene: 'DIRECT_TRANSFER',
    merchant_batch_no: 'RB202606300001',
    currency: 'USDT',
    batchorderList: [
      {user_id: 100001, amount: '12.5', currency: 'USDT', rewardId: 'reward_001'},
      {user_id: 100002, amount: '8.8', currency: 'USDT', rewardId: 'reward_002'}
    ]
  })
};

fetch('https://openplatform.gateapi.io/v1/pay/batch/transfer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://openplatform.gateapi.io/v1/pay/batch/transfer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'batchId' => '237394559478075550',
    'bizscene' => 'DIRECT_TRANSFER',
    'merchant_batch_no' => 'RB202606300001',
    'currency' => 'USDT',
    'batchorderList' => [
        [
                'user_id' => 100001,
                'amount' => '12.5',
                'currency' => 'USDT',
                'rewardId' => 'reward_001'
        ],
        [
                'user_id' => 100002,
                'amount' => '8.8',
                'currency' => 'USDT',
                'rewardId' => 'reward_002'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-GatePay-Certificate-ClientId: <x-gatepay-certificate-clientid>",
    "X-GatePay-Nonce: <x-gatepay-nonce>",
    "X-GatePay-Signature: <x-gatepay-signature>",
    "X-GatePay-Timestamp: <x-gatepay-timestamp>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://openplatform.gateapi.io/v1/pay/batch/transfer")
  .header("X-GatePay-Certificate-ClientId", "<x-gatepay-certificate-clientid>")
  .header("X-GatePay-Signature", "<x-gatepay-signature>")
  .header("X-GatePay-Timestamp", "<x-gatepay-timestamp>")
  .header("X-GatePay-Nonce", "<x-gatepay-nonce>")
  .header("Content-Type", "application/json")
  .body("{\n  \"batchId\": \"237394559478075550\",\n  \"bizscene\": \"DIRECT_TRANSFER\",\n  \"merchant_batch_no\": \"RB202606300001\",\n  \"currency\": \"USDT\",\n  \"batchorderList\": [\n    {\n      \"user_id\": 100001,\n      \"amount\": \"12.5\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_001\"\n    },\n    {\n      \"user_id\": 100002,\n      \"amount\": \"8.8\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_002\"\n    }\n  ]\n}")
  .asString();

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://openplatform.gateapi.io/v1/pay/batch/transfer"

	payload := strings.NewReader("{\n  \"batchId\": \"237394559478075550\",\n  \"bizscene\": \"DIRECT_TRANSFER\",\n  \"merchant_batch_no\": \"RB202606300001\",\n  \"currency\": \"USDT\",\n  \"batchorderList\": [\n    {\n      \"user_id\": 100001,\n      \"amount\": \"12.5\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_001\"\n    },\n    {\n      \"user_id\": 100002,\n      \"amount\": \"8.8\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_002\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-GatePay-Certificate-ClientId", "<x-gatepay-certificate-clientid>")
	req.Header.Add("X-GatePay-Signature", "<x-gatepay-signature>")
	req.Header.Add("X-GatePay-Timestamp", "<x-gatepay-timestamp>")
	req.Header.Add("X-GatePay-Nonce", "<x-gatepay-nonce>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://openplatform.gateapi.io/v1/pay/batch/transfer")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-GatePay-Certificate-ClientId"] = '<x-gatepay-certificate-clientid>'
request["X-GatePay-Signature"] = '<x-gatepay-signature>'
request["X-GatePay-Timestamp"] = '<x-gatepay-timestamp>'
request["X-GatePay-Nonce"] = '<x-gatepay-nonce>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"batchId\": \"237394559478075550\",\n  \"bizscene\": \"DIRECT_TRANSFER\",\n  \"merchant_batch_no\": \"RB202606300001\",\n  \"currency\": \"USDT\",\n  \"batchorderList\": [\n    {\n      \"user_id\": 100001,\n      \"amount\": \"12.5\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_001\"\n    },\n    {\n      \"user_id\": 100002,\n      \"amount\": \"8.8\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_002\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "merchant_batch_no": "RB202606300001",
    "batch_id": "237394559478075550"
  }
}

POST

pay

batch

transfer

Create merchant batch transfer

curl --request POST \
  --url https://openplatform.gateapi.io/v1/pay/batch/transfer \
  --header 'Content-Type: application/json' \
  --header 'X-GatePay-Certificate-ClientId: <x-gatepay-certificate-clientid>' \
  --header 'X-GatePay-Nonce: <x-gatepay-nonce>' \
  --header 'X-GatePay-Signature: <x-gatepay-signature>' \
  --header 'X-GatePay-Timestamp: <x-gatepay-timestamp>' \
  --data '
{
  "batchId": "237394559478075550",
  "bizscene": "DIRECT_TRANSFER",
  "merchant_batch_no": "RB202606300001",
  "currency": "USDT",
  "batchorderList": [
    {
      "user_id": 100001,
      "amount": "12.5",
      "currency": "USDT",
      "rewardId": "reward_001"
    },
    {
      "user_id": 100002,
      "amount": "8.8",
      "currency": "USDT",
      "rewardId": "reward_002"
    }
  ]
}
'

import requests

url = "https://openplatform.gateapi.io/v1/pay/batch/transfer"

payload = {
    "batchId": "237394559478075550",
    "bizscene": "DIRECT_TRANSFER",
    "merchant_batch_no": "RB202606300001",
    "currency": "USDT",
    "batchorderList": [
        {
            "user_id": 100001,
            "amount": "12.5",
            "currency": "USDT",
            "rewardId": "reward_001"
        },
        {
            "user_id": 100002,
            "amount": "8.8",
            "currency": "USDT",
            "rewardId": "reward_002"
        }
    ]
}
headers = {
    "X-GatePay-Certificate-ClientId": "<x-gatepay-certificate-clientid>",
    "X-GatePay-Signature": "<x-gatepay-signature>",
    "X-GatePay-Timestamp": "<x-gatepay-timestamp>",
    "X-GatePay-Nonce": "<x-gatepay-nonce>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-GatePay-Certificate-ClientId': '<x-gatepay-certificate-clientid>',
    'X-GatePay-Signature': '<x-gatepay-signature>',
    'X-GatePay-Timestamp': '<x-gatepay-timestamp>',
    'X-GatePay-Nonce': '<x-gatepay-nonce>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    batchId: '237394559478075550',
    bizscene: 'DIRECT_TRANSFER',
    merchant_batch_no: 'RB202606300001',
    currency: 'USDT',
    batchorderList: [
      {user_id: 100001, amount: '12.5', currency: 'USDT', rewardId: 'reward_001'},
      {user_id: 100002, amount: '8.8', currency: 'USDT', rewardId: 'reward_002'}
    ]
  })
};

fetch('https://openplatform.gateapi.io/v1/pay/batch/transfer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://openplatform.gateapi.io/v1/pay/batch/transfer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'batchId' => '237394559478075550',
    'bizscene' => 'DIRECT_TRANSFER',
    'merchant_batch_no' => 'RB202606300001',
    'currency' => 'USDT',
    'batchorderList' => [
        [
                'user_id' => 100001,
                'amount' => '12.5',
                'currency' => 'USDT',
                'rewardId' => 'reward_001'
        ],
        [
                'user_id' => 100002,
                'amount' => '8.8',
                'currency' => 'USDT',
                'rewardId' => 'reward_002'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-GatePay-Certificate-ClientId: <x-gatepay-certificate-clientid>",
    "X-GatePay-Nonce: <x-gatepay-nonce>",
    "X-GatePay-Signature: <x-gatepay-signature>",
    "X-GatePay-Timestamp: <x-gatepay-timestamp>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://openplatform.gateapi.io/v1/pay/batch/transfer")
  .header("X-GatePay-Certificate-ClientId", "<x-gatepay-certificate-clientid>")
  .header("X-GatePay-Signature", "<x-gatepay-signature>")
  .header("X-GatePay-Timestamp", "<x-gatepay-timestamp>")
  .header("X-GatePay-Nonce", "<x-gatepay-nonce>")
  .header("Content-Type", "application/json")
  .body("{\n  \"batchId\": \"237394559478075550\",\n  \"bizscene\": \"DIRECT_TRANSFER\",\n  \"merchant_batch_no\": \"RB202606300001\",\n  \"currency\": \"USDT\",\n  \"batchorderList\": [\n    {\n      \"user_id\": 100001,\n      \"amount\": \"12.5\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_001\"\n    },\n    {\n      \"user_id\": 100002,\n      \"amount\": \"8.8\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_002\"\n    }\n  ]\n}")
  .asString();

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://openplatform.gateapi.io/v1/pay/batch/transfer"

	payload := strings.NewReader("{\n  \"batchId\": \"237394559478075550\",\n  \"bizscene\": \"DIRECT_TRANSFER\",\n  \"merchant_batch_no\": \"RB202606300001\",\n  \"currency\": \"USDT\",\n  \"batchorderList\": [\n    {\n      \"user_id\": 100001,\n      \"amount\": \"12.5\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_001\"\n    },\n    {\n      \"user_id\": 100002,\n      \"amount\": \"8.8\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_002\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-GatePay-Certificate-ClientId", "<x-gatepay-certificate-clientid>")
	req.Header.Add("X-GatePay-Signature", "<x-gatepay-signature>")
	req.Header.Add("X-GatePay-Timestamp", "<x-gatepay-timestamp>")
	req.Header.Add("X-GatePay-Nonce", "<x-gatepay-nonce>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://openplatform.gateapi.io/v1/pay/batch/transfer")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-GatePay-Certificate-ClientId"] = '<x-gatepay-certificate-clientid>'
request["X-GatePay-Signature"] = '<x-gatepay-signature>'
request["X-GatePay-Timestamp"] = '<x-gatepay-timestamp>'
request["X-GatePay-Nonce"] = '<x-gatepay-nonce>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"batchId\": \"237394559478075550\",\n  \"bizscene\": \"DIRECT_TRANSFER\",\n  \"merchant_batch_no\": \"RB202606300001\",\n  \"currency\": \"USDT\",\n  \"batchorderList\": [\n    {\n      \"user_id\": 100001,\n      \"amount\": \"12.5\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_001\"\n    },\n    {\n      \"user_id\": 100002,\n      \"amount\": \"8.8\",\n      \"currency\": \"USDT\",\n      \"rewardId\": \"reward_002\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "merchant_batch_no": "RB202606300001",
    "batch_id": "237394559478075550"
  }
}

Overview

This page documents the POST /v1/pay/batch/transfer endpoint, which creates a batch transfer order from a merchant to multiple users. 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 in institution merchant APIs.
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.

Headers

X-GatePay-Certificate-ClientId

string

required

The clientId assigned when the merchant registers an application in the Gate merchant console.

Example:

"4186d0c6-6a35-55a9-8dc6-5312769dbff8"

X-GatePay-Signature

string

required

Request signature. GatePay uses this signature to verify whether the request is valid.

X-GatePay-Timestamp

string

required

Millisecond timestamp; the difference from server time must not exceed 30 seconds.

Example:

"1672905655498"

X-GatePay-Nonce

string

required

Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.

Example:

"9578"

X-GatePay-On-Behalf-Of

string

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.

Body

application/json

Request body for creating a merchant batch transfer order.

batchId

string

required

Internal batch correlation ID used to associate the batch record with its sub-orders. Keep it unique within the merchant account. It may use the same value as merchant_batch_no.

bizscene

enum<string>

required

Business scenario identifier. This endpoint currently supports only DIRECT_TRANSFER.

Available options:

DIRECT_TRANSFER

merchant_batch_no

string

required

Merchant-side business batch number used for request idempotency and merchant queries. It must be unique on the merchant side.

currency

string

required

Batch transfer currency.

batchorderList

object[]

required

List of transfer sub-orders.

Show child attributes

name

string

Display name of the batch transfer.

description

string

Description of the batch transfer.

channelId

string

Channel ID, optional.

is_coupon

boolean

Whether this is a coupon scenario. Optional, default is false.

Response

200 - application/json

Batch transfer creation result

Response body for creating a merchant batch transfer order.

status

string

required

API response result, SUCCESS or FAIL.

code

string

required

Response error code.

errorMessage

string

Error description.

data

object

Show child attributes

⌘I

Common

Balance

Institution

Payment

OTC

Convert

Payout

Gift Card

Subscription

Reconciliation

Notifications

Create Merchant Batch Transfer

Overview

Notes

Headers

Body

Response

​Overview

​Notes

Headers

Body

Response

Overview

Notes