TIMESTAMP=$(date +%s)
NONCE=$(uuidgen)
BODY=''
SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}.${BODY}" | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')
curl --request GET --get "https://api.stablepay.co/api/v1/payout-items/${ITEM_ID}" \
-H "Authorization: Bearer ${API_KEY}" \
-H "X-StablePay-Timestamp: ${TIMESTAMP}" \
-H "X-StablePay-Nonce: ${NONCE}" \
-H "X-StablePay-Signature: ${SIGNATURE}"
{
"code": 401,
"message": "authenticated merchant is required",
"errorCode": "authentication_required",
"data": null
}
{
"code": 403,
"message": "access denied",
"errorCode": "forbidden",
"data": null
}
{
"code": 404,
"message": "batch not found",
"errorCode": "batch_not_found",
"data": null
}
{
"code": 500,
"message": "payout request failed",
"errorCode": "payout_error",
"data": null
}
{
"code": 503,
"message": "payout service is temporarily unavailable",
"errorCode": "service_unavailable",
"data": null
}
Payouts API
Get Payout Item
Get the current merchant’s payout item by item ID.
GET
/
api
/
v1
/
payout-items
/
{item_id}
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen)
BODY=''
SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}.${BODY}" | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')
curl --request GET --get "https://api.stablepay.co/api/v1/payout-items/${ITEM_ID}" \
-H "Authorization: Bearer ${API_KEY}" \
-H "X-StablePay-Timestamp: ${TIMESTAMP}" \
-H "X-StablePay-Nonce: ${NONCE}" \
-H "X-StablePay-Signature: ${SIGNATURE}"
{
"code": 401,
"message": "authenticated merchant is required",
"errorCode": "authentication_required",
"data": null
}
{
"code": 403,
"message": "access denied",
"errorCode": "forbidden",
"data": null
}
{
"code": 404,
"message": "batch not found",
"errorCode": "batch_not_found",
"data": null
}
{
"code": 500,
"message": "payout request failed",
"errorCode": "payout_error",
"data": null
}
{
"code": 503,
"message": "payout service is temporarily unavailable",
"errorCode": "service_unavailable",
"data": null
}
The response includes validation results, the transaction hash, and failure information. Optional fields that have not yet been produced are returned as
Only the fields defined below are allowed.
null.
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.
string
required
Bearer API Key:
Bearer sk_live_xxx.string
required
Unix timestamp in seconds, within 5 minutes of the server time.
string
required
Random string for replay protection. Use a new nonce for each request. Minimum length: 16. Maximum length: 64.
string
required
Request signature encoded as lowercase hexadecimal.
Path Parameters
string
required
Minimum length: 1. Maximum length: 64.
Success Response
HTTP200, application/json. Query successful.
Only the fields defined below are allowed.
string
required
string
required
string | null
string
required
string
required
string
required
Allowed values:
erc20, trc20, spl.string
required
string | null
string
required
Allowed values:
USDT, USDC.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})?$.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})?$.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})?$.string
required
Allowed values:
pending, processing, succeeded, failed.boolean
required
string | null
string | null
string | null
string | null
integer
required
Format:
int64.integer
required
Format:
int64.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 | Invalid HTTP request format or parameters, or the payout request failed business validation. Possible business error codes include address_risk_rejected, batch_amount_limit_exceeded, batch_amount_too_low, batch_cannot_submit, batch_empty_items, custody_balance_insufficient, insufficient_balance, and quota_blocked. |
| 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. |
| 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. |
integer
required
string
required
string
required
null
required
Related Endpoints
- Create Payout Batch
- Submit Payout Batch
- Cancel Payout Batch
- Get Payout Batch
- List Payout Batches
- List Batch Items
Set API_KEY and SECRET_KEY before running this example. Set BATCH_ID or ITEM_ID when required by the endpoint.TIMESTAMP=$(date +%s)
NONCE=$(uuidgen)
BODY=''
SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}.${BODY}" | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')
curl --request GET --get "https://api.stablepay.co/api/v1/payout-items/${ITEM_ID}" \
-H "Authorization: Bearer ${API_KEY}" \
-H "X-StablePay-Timestamp: ${TIMESTAMP}" \
-H "X-StablePay-Nonce: ${NONCE}" \
-H "X-StablePay-Signature: ${SIGNATURE}"
{
"code": 401,
"message": "authenticated merchant is required",
"errorCode": "authentication_required",
"data": null
}
{
"code": 403,
"message": "access denied",
"errorCode": "forbidden",
"data": null
}
{
"code": 404,
"message": "batch not found",
"errorCode": "batch_not_found",
"data": null
}
{
"code": 500,
"message": "payout request failed",
"errorCode": "payout_error",
"data": null
}
{
"code": 503,
"message": "payout service is temporarily unavailable",
"errorCode": "service_unavailable",
"data": null
}
Last modified on October 19, 2026
Was this page helpful?