Query a Batch Payout
Retrieves the current state and metadata of a batch payout, including its lifecycle timestamps, reference pricing summary, and (when applicable) the reason it was rejected under your approval policy. Poll this endpoint after Submit a Batch Payout to monitor progression through PENDING_APPROVAL → PROCESSING → COMPLETED. To inspect individual items, use List Batch Payout Items.
Request Parameters
idstring
required
Unique identifier of the batch payout to look up.
Response Parameters
resultResult
See Result.
idstring
Unique identifier of the batch payout.
statusstring
Current batch status. See BatchPayoutStatus.
createdAtdatetime
Time the batch was created, in ISO 8601 extended format.
updatedAtdatetime
Time the batch was most recently updated, in ISO 8601 extended format.
submittedAtdatetime
Time the batch was submitted. Returned when status is anything other than INIT.
completedAtdatetime
Time the batch finished processing. Returned when status is COMPLETED.
cancelledAtdatetime
Time the batch was cancelled. Returned when status is CANCELLED.
requestIdstring
Idempotency key supplied when the batch was created.
batchNamestring
Human-readable batch name, if provided at creation.
transferMemostring
Internal memo attached to the batch, if provided at creation.
businessSceneCodestring
Business scene code set on the batch, if provided at creation. See BusinessSceneCode.
paymentNetworkstring
Payment clearing network set on the batch, if provided at creation. See PaymentNetwork.
paymentTypestring
Payment channel type set on the batch, if provided at creation. See PaymentType.
fvtPreferencestring
Full value transfer (FVT) preference set on the batch, if provided at creation. See FvtPreference.
oboPreferencestring
On-behalf-of (OBO) routing preference set on the batch, if provided at creation. See OboPreference.
totalItemCountinteger
Total number of items currently in the batch. Range: 0 - 100.
validItemCountinteger
Number of items that passed validation. Range: 0 - 100.
calculationSummaryCalculationSummary
Latest reference pricing summary. Returned once calculate (or submit) has completed pricing. All totals and rates are indicative — final values are determined at payout processing.
rejectionReasonstring
Explanation returned when the approval workflow rejects the batch. Returned when status is REJECTED.
Error Codes
Definition
POST /api/open/v1/batchPayouts/queryRequest
{
"id": "20260808BATCH00001"
}Response
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"id": "20260808BATCH00001",
"status": "COMPLETED",
"createdAt": "2026-08-08T09:15:00+08:00",
"updatedAt": "2026-08-09T10:30:00+08:00",
"submittedAt": "2026-08-08T14:00:00+08:00",
"completedAt": "2026-08-09T10:30:00+08:00",
"requestId": "req_batch_20260808_0001",
"batchName": "Aug 8 supplier payouts",
"totalItemCount": 3,
"validItemCount": 2,
"calculationSummary": {
"lastCalculatedAt": "2026-08-08T13:55:00+08:00",
"currencyPairs": [
{
"currencyPair": "USD/USD",
"clientRate": "1.000000",
"sourceAmount": {
"currency": "USD",
"value": "5000.00"
},
"payoutAmount": {
"currency": "USD",
"value": "5000.00"
},
"feeRate": "0.001",
"feeAmount": {
"currency": "USD",
"value": "5.00"
},
"feeItemList": [
{
"feeItemType": "PAYOUT_SERVICE_FEE",
"feeItemAmount": {
"currency": "USD",
"value": "5.00"
}
}
]
},
{
"currencyPair": "USD/EUR",
"clientRate": "0.923400",
"sourceAmount": {
"currency": "USD",
"value": "3000.00"
},
"payoutAmount": {
"currency": "EUR",
"value": "2770.20"
},
"feeRate": "0.0005",
"feeAmount": {
"currency": "USD",
"value": "1.50"
},
"feeItemList": [
{
"feeItemType": "PAYOUT_SERVICE_FEE",
"feeItemAmount": {
"currency": "USD",
"value": "1.50"
}
}
],
"originalFeeRate": "0.001",
"originalFeeAmount": {
"currency": "USD",
"value": "3.00"
},
"promotionList": [
{
"promotionName": "August Fee Discount",
"promotionType": "FEE_DISCOUNT",
"activeTime": "2026-08-01T00:00:00+08:00",
"expiredTime": "2026-08-31T23:59:59+08:00"
}
]
}
]
}
}