Query Batch Withdraw

Request Method and Path

POST /payout/v1/batch/query

Request Headers

Field Name	Type	Required	Description
content-type	string	Yes	application/json
x-api-key	string	Yes	Provided by Paydify, same as appId
x-api-timestamp	string	Yes	Timestamp in milliseconds
x-api-signature	string	Yes	Signature, see Signature Algorithm

Request Body

Field Name	Type	Required	Description
batchId	string	No	Paydify batch ID, either batchId or mchBatchId is required, batchId takes priority
mchBatchId	string	No	Merchant batch ID, either batchId or mchBatchId is required
detailStatus	string	No	Filter by detail status, returns all details if not provided
merchantId	string	No	Merchant ID of the batch owner (sub-merchant). Required when calling with a partner credential on behalf of a sub-merchant; can be omitted with a merchant-owned credential (defaults to the credential owner)
merchantAppId	string	No	App ID under the owner merchant, used for disambiguation when the owner merchant has multiple authorized apps. Required if the credential covers multiple apps of the owner merchant; can be omitted when only one app is authorized (resolved automatically).

At least one of batchId or mchBatchId must be provided, otherwise a parameter error will be returned.

Response Headers

Field Name	Type	Required	Description
x-api-key	string	Yes	Provided by Paydify, same as appId
x-api-timestamp	string	Yes	Timestamp in milliseconds
x-api-signature	string	Yes	Signature, see Signature Algorithm

Response

Field Name	Type	Description
code	string	Response code, SYS_SUCCESS indicates success
message	string	Response message
messageDetail	string	Detailed response message
success	boolean	Whether the request was successful
data.batchId	string	Paydify batch ID
data.mchBatchId	string	Merchant batch ID
data.batchName	string	Batch name
data.status	string	Batch status: CREATED/PROCESSING/COMPLETED/PARTIAL_SUCCESS/FAILED
data.currency	string	Currency
data.totalAmount	string	Total batch amount
data.totalCount	int	Total batch count
data.successCount	int	Success count
data.failedCount	int	Failed count
data.successAmount	string	Total success amount
data.failedAmount	string	Total failed amount
data.createTime	string	Creation timestamp in milliseconds
data.finishTime	string	Completion timestamp in milliseconds, empty when batch is not completed
data.transferDetailList	array	Detail list

transferDetailList Details

Field Name	Type	Description
detailId	string	Paydify detail ID
mchDetailId	string	Merchant detail ID
status	string	Detail status: INIT/PROCESSING/SUCCESS/FAILED
transferAmount	string	Transfer amount
mchFee	string	Merchant fee
network	string	Chain network
address	string	Recipient address
txnHash	string	On-chain transaction hash, returned after on-chain confirmation
remark	string	Remark
errorCode	string	Error code, returned only on failure
errorMsg	string	Error message, returned only on failure
finishTime	string	Detail completion timestamp in milliseconds

Example

# Request
{
  "batchId": "1236740866224164865",
  "mchBatchId": "",
  "detailStatus": ""
}

# Successful response
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "batchId": "4956970611319809537",
    "mchBatchId": "BATCH_20260313154751_9",
    "batchName": "Auto Test Batch 002",
    "status": "COMPLETED",
    "currency": "USDT",
    "totalAmount": "3.360000000000000000",
    "totalCount": 3,
    "successCount": 3,
    "failedCount": 0,
    "successAmount": "3.360000000000000000",
    "failedAmount": "0.000000000000000000",
    "createTime": "1773388072000",
    "finishTime": "1773392144000",
    "transferDetailList": [
      {
        "detailId": "4956970611319809538",
        "mchDetailId": "DETAIL_20260313154751_001",
        "status": "SUCCESS",
        "transferAmount": "1.110000000000000000",
        "mchFee": "0.112000000000000000",
        "network": "BSC",
        "address": "0x1111111111222222222233333333334444444444",
        "txnHash": "0xaaaaaaaaaaaabbbbbbbbbbbbccccccccccccddddddddddddeeeeeeeeeeee1111",
        "remark": "bsc transfer 1",
        "errorCode": "",
        "errorMsg": "",
        "finishTime": "1773392110000"
      },
      {
        "detailId": "4956970611319809539",
        "mchDetailId": "DETAIL_20260313154751_002",
        "status": "SUCCESS",
        "transferAmount": "1.120000000000000000",
        "mchFee": "0.113000000000000000",
        "network": "BSC",
        "address": "0x1111111111222222222233333333334444444444",
        "txnHash": "0xaaaaaaaaaaaabbbbbbbbbbbbccccccccccccddddddddddddeeeeeeeeeeee2222",
        "remark": "bsc transfer 2",
        "errorCode": "",
        "errorMsg": "",
        "finishTime": "1773392144000"
      },
      {
        "detailId": "4956970611319809540",
        "mchDetailId": "DETAIL_20260313154751_003",
        "status": "SUCCESS",
        "transferAmount": "1.130000000000000000",
        "mchFee": "0.113100000000000000",
        "network": "TRON",
        "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "txnHash": "ff078df57d8e5a92fc44f5683d5f988a3d20b5f28c4e764a6c25dea9a8e10a35",
        "remark": "bsc transfer 3",
        "errorCode": "",
        "errorMsg": "",
        "finishTime": "1773392110000"
      }
    ]
  },
  "success": true
}

# Failed response
{
  "code": "SYS_ERROR",
  "message": "System error",
  "messageDetail": "Error details",
  "data": null,
  "success": false
}