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 '
{
  "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 = {
    "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({
    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([
    '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  \"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  \"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  \"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 '
{
  "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 = {
    "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({
    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([
    '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  \"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  \"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  \"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 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 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

UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 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.

merchant_batch_no

string

required

Merchant batch number. Must be unique on the merchant side.

currency

string

required

Batch transfer currency.

batchorderList

object[]

required

List of transfer sub-orders.

Show child attributes

bizscene

string

Business scenario identifier.

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

Query Withdrawal Status

Query Merchant Batch Transfer Order

⌘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