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

# Submit Payout Batch

> Submit the current merchant's payout batch for immediate execution.

API submissions do not require manual approval in the Merchant Portal. A repeated request continues a batch awaiting execution or returns the current status of a batch that has already entered execution. After a timeout or connection interruption, query the batch status first.

Submit the specified batch for immediate execution without manual approval in the Merchant Portal. On retry, a batch in pending, pending\_approval, processing, partially\_completed, or completed status continues execution or returns its current status. If the request times out or the connection is interrupted, query the batch status first.

Merchant identity is determined by authentication through stablepay-auth. Do not include merchant\_id in request parameters. Batch statuses and business rules are determined by the StablePay Payout service.

## Authentication and Headers

Authenticate with a Bearer API Key and the three signing headers below. Compute HMAC-SHA256 over `{timestamp}.{nonce}.{requestBody}` with the API Secret, then encode the result as lowercase hex. Sign the exact request body bytes; use an empty string when no body is sent. See [Authentication and Signing](/en/api/getting-started#authentication-and-signing).

<ParamField header="Authorization" type="string" required>
  Bearer API Key: `Bearer sk_live_xxx`.
</ParamField>

<ParamField header="X-StablePay-Timestamp" type="string" required>
  Unix timestamp in seconds, within 5 minutes of the server time.
</ParamField>

<ParamField header="X-StablePay-Nonce" type="string" required>
  Random string for replay protection. Use a new nonce for each request. Minimum length: 16. Maximum length: 64.
</ParamField>

<ParamField header="X-StablePay-Signature" type="string" required>
  Request signature encoded as lowercase hexadecimal.
</ParamField>

## Path Parameters

<ParamField path="batch_id" type="string" required>
  Minimum length: 1. Maximum length: 64.
</ParamField>

## Success Response

HTTP `200`, `application/json`. The batch has entered execution, or had already entered execution.

Only the fields defined below are allowed.

<ResponseField name="batch_id" type="string" required />

<ResponseField name="status" type="string" required>
  Allowed values: `draft`, `needs_fix`, `pending`, `pending_approval`, `processing`, `partially_completed`, `completed`, `failed`, `canceled`, `rejected`.
</ResponseField>

<ResponseField name="currency" type="string" required>
  Allowed values: `USDT`, `USDC`.
</ResponseField>

<ResponseField name="network" type="string" required>
  Allowed values: `erc20`, `trc20`, `spl`.
</ResponseField>

<ResponseField name="total_count" type="integer" required>
  Minimum: 0.
</ResponseField>

<ResponseField name="valid_count" type="integer" required>
  Minimum: 0.
</ResponseField>

<ResponseField name="invalid_count" type="integer" required>
  Minimum: 0.
</ResponseField>

<ResponseField name="success_count" type="integer" required>
  Minimum: 0.
</ResponseField>

<ResponseField name="failed_count" type="integer" required>
  Minimum: 0.
</ResponseField>

<ResponseField name="total_amount" type="string" required>
  Nonnegative decimal amount represented as a string, with at most two decimal places. Pattern: `^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`.
</ResponseField>

<ResponseField name="service_fee_amount" type="string" required>
  Nonnegative decimal amount represented as a string, with at most two decimal places. Pattern: `^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`.
</ResponseField>

<ResponseField name="debit_amount" type="string" required>
  Nonnegative decimal amount represented as a string, with at most two decimal places. Pattern: `^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`.
</ResponseField>

<ResponseField name="frozen_amount" type="string" required>
  Nonnegative decimal amount represented as a string, with at most two decimal places. Pattern: `^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`.
</ResponseField>

<ResponseField name="charged_service_fee_amount" type="string" required>
  Nonnegative decimal amount represented as a string, with at most two decimal places. Pattern: `^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`.
</ResponseField>

<ResponseField name="can_submit" type="boolean">
  Whether the batch can currently be submitted. This field is omitted when status is canceled.
</ResponseField>

<ResponseField name="validation_errors" type="object[]" required>
  <Expandable title="Fields">
    Only the fields defined below are allowed.

    <ResponseField name="field" type="string" required />

    <ResponseField name="code" type="string" required />

    <ResponseField name="message" type="string" required />
  </Expandable>
</ResponseField>

<ResponseField name="description" type="string | null" />

<ResponseField name="created_at" type="integer" required>
  Format: `int64`.
</ResponseField>

<ResponseField name="submitted_at" type="integer | null">
  Format: `int64`.
</ResponseField>

<ResponseField name="completed_at" type="integer | null">
  Format: `int64`.
</ResponseField>

### Response Headers

| Header | Description |
| - | - |
| `X-Request-ID` | Request tracing ID. |
| `Cache-Control` | The response must not be cached. Allowed values: `no-store`. |

## Error Responses

| HTTP | Description |
| - | - |
| 400 | The request is invalid or the batch does not meet submission requirements. |
| 401 | Authentication failed or a trusted merchant identity is missing. |
| 403 | The current merchant is not authorized to access or operate on this resource. |
| 404 | The specified payout batch or item does not exist. |
| 409 | Another operation on the same resource is in progress. Try again later. |
| 500 | A payout business error that is not currently classified more specifically. |
| 503 | The payout service timed out or is temporarily unavailable. If this occurs during a write request, query the resource status before retrying. |

Only the fields defined below are allowed.

<ResponseField name="code" type="integer" required />

<ResponseField name="message" type="string" required />

<ResponseField name="errorCode" type="string" required />

<ResponseField name="data" type="null" required />

## Related Endpoints

* [Create Payout Batch](/en/api/payouts/create-batch)
* [Cancel Payout Batch](/en/api/payouts/cancel-batch)
* [Get Payout Batch](/en/api/payouts/get-batch)
* [List Payout Batches](/en/api/payouts/list-batches)
* [List Batch Items](/en/api/payouts/list-batch-items)
* [Get Payout Item](/en/api/payouts/get-item)

<RequestExample>
  Set `API_KEY` and `SECRET_KEY` before running this example. Set `BATCH_ID` or `ITEM_ID` when required by the endpoint.

  ```bash cURL theme={"system"}
  TIMESTAMP=$(date +%s)
  NONCE=$(uuidgen)
  BODY=''
  SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}.${BODY}" | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')

  curl --request POST "https://api.stablepay.co/api/v1/payout-batches/${BATCH_ID}/submit" \
    -H "Authorization: Bearer ${API_KEY}" \
    -H "X-StablePay-Timestamp: ${TIMESTAMP}" \
    -H "X-StablePay-Nonce: ${NONCE}" \
    -H "X-StablePay-Signature: ${SIGNATURE}"
  ```
</RequestExample>

<ResponseExample>
  ```json 400 Batch amount below the minimum theme={"system"}
  {
    "code": 400,
    "message": "batch total amount must be at least 3 USDC/USDT",
    "errorCode": "batch_amount_too_low",
    "data": null
  }
  ```

  ```json 401 theme={"system"}
  {
    "code": 401,
    "message": "authenticated merchant is required",
    "errorCode": "authentication_required",
    "data": null
  }
  ```

  ```json 403 theme={"system"}
  {
    "code": 403,
    "message": "access denied",
    "errorCode": "forbidden",
    "data": null
  }
  ```

  ```json 404 theme={"system"}
  {
    "code": 404,
    "message": "batch not found",
    "errorCode": "batch_not_found",
    "data": null
  }
  ```

  ```json 409 theme={"system"}
  {
    "code": 409,
    "message": "another operation is in progress, please try again later",
    "errorCode": "concurrent_operation",
    "data": null
  }
  ```

  ```json 500 theme={"system"}
  {
    "code": 500,
    "message": "payout request failed",
    "errorCode": "payout_error",
    "data": null
  }
  ```

  ```json 503 theme={"system"}
  {
    "code": 503,
    "message": "payout service is temporarily unavailable",
    "errorCode": "service_unavailable",
    "data": null
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.