List Bills

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

curl --get 'https://api.stablepay.co/api/v1/bills' \
  --data-urlencode 'bill_date_from=2026-09-01' \
  --data-urlencode 'bill_date_to=2026-09-30' \
  --data-urlencode 'bill_types=payment,payment_fee' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "X-StablePay-Timestamp: ${TIMESTAMP}" \
  -H "X-StablePay-Nonce: ${NONCE}" \
  -H "X-StablePay-Signature: ${SIGNATURE}"

{
  "data": [
    {
      "bill_id": "1234567890",
      "bill_type": "payment",
      "bill_date": "2026-09-01",
      "currency": "USD",
      "transaction_count": 10
    }
  ],
  "total_count": 1,
  "page": 1,
  "page_size": 20
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid request parameters"
  },
  "request_id": "req_example",
  "timestamp": 1790812800
}

{
  "status": "error",
  "error": "Authentication failed"
}

GET

api

bills

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

curl --get 'https://api.stablepay.co/api/v1/bills' \
  --data-urlencode 'bill_date_from=2026-09-01' \
  --data-urlencode 'bill_date_to=2026-09-30' \
  --data-urlencode 'bill_types=payment,payment_fee' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "X-StablePay-Timestamp: ${TIMESTAMP}" \
  -H "X-StablePay-Nonce: ${NONCE}" \
  -H "X-StablePay-Signature: ${SIGNATURE}"

{
  "data": [
    {
      "bill_id": "1234567890",
      "bill_type": "payment",
      "bill_date": "2026-09-01",
      "currency": "USD",
      "transaction_count": 10
    }
  ],
  "total_count": 1,
  "page": 1,
  "page_size": 20
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid request parameters"
  },
  "request_id": "req_example",
  "timestamp": 1790812800
}

{
  "status": "error",
  "error": "Authentication failed"
}

List bills successfully generated for the current merchant, filtered by bill type and date, with pagination. The API Key identifies the merchant; no merchant ID is required.

bill_date_from and bill_date_to are required. The date range includes both endpoints and must not exceed 90 days. Omit bill_types to query all bill types.

Authentication and Headers

Authenticate with a Bearer API Key and include the signing headers below. GET requests use an empty requestBody, so the signature payload is {timestamp}.{nonce}.. Compute HMAC-SHA256 with the merchant API Secret and encode the result as lowercase hex. See Authentication and Signing.

string

required

Bearer API Key in the format Bearer sk_live_xxx.

string

required

Unix timestamp in seconds. It must be within 5 minutes of the server time.

string

required

Random string for replay protection, 16–64 characters long. Use a new UUID for each request. Minimum length: 16 characters. Maximum length: 64 characters.

string

required

HMAC-SHA256 of {timestamp}.{nonce}.{requestBody} using the merchant API Secret, encoded as lowercase hex. For GET requests, requestBody is an empty string.

Query Parameters

string[]

Optional list of bill type identifiers separated by commas, such as payment,payment_fee. Omit this parameter to query all bill types. At least 1 item.Stable bill type identifier maintained by BillProd. Current values: payment for online payments, payment_fee for payment fees, subscription for subscription payments, subscription_period for subscription periods, subscription_fee for subscription fees, payout for payouts, payout_fee for payout fees, and capital_flow for fund movements. New string values may be added; clients must handle unknown values. Pattern: ^[a-z][a-z0-9_]{0,63}$.

string

required

Start date for the bill query in YYYY-MM-DD format, inclusive. Format: date.

string

required

End date for the bill query in YYYY-MM-DD format, inclusive. The date range must not exceed 90 days. Format: date.

integer

default:1

Page number, starting at 1. Defaults to 1. Minimum: 1.

integer

default:20

Number of bills per page, from 1 to 100. Defaults to 20. Minimum: 1. Maximum: 100.

Success Response

HTTP 200, application/json. Query successful. If no bills match, data is an empty array.

object[]

required

Bills on the current page.

Show Fields

string

required

Bill ID, returned as a string to avoid integer precision loss in clients. Pattern: ^[0-9]+$.

string

required

Stable bill type identifier maintained by BillProd. Current values: payment for online payments, payment_fee for payment fees, subscription for subscription payments, subscription_period for subscription periods, subscription_fee for subscription fees, payout for payouts, payout_fee for payout fees, and capital_flow for fund movements. New string values may be added; clients must handle unknown values. Pattern: ^[a-z][a-z0-9_]{0,63}$.

string

required

Bill date. Format: date.

string

required

Bill currency.

integer

required

Number of transaction records in the bill. Format: int64.

integer

required

Total number of bills matching the filters. Format: int64. Minimum: 0.

integer

required

Current page number. Minimum: 1.

integer

required

Number of bills per page. Minimum: 1. Maximum: 100.

Error Responses

HTTP Status	Description
400	Invalid request parameters.
401	Authentication failed.
503	BillProd or another dependent service is temporarily unavailable.

Service Error Structure

object

required

Show Fields

string

required

Error code, such as invalid_parameter, resource_not_found, historical_report_unavailable, report_incomplete, or service_unavailable.

string

required

Error message.

string

required

Request ID.

integer

required

Time of the error, as a Unix timestamp in seconds. Format: int64.

Gateway Authentication Error Structure

Before a request reaches PaymentProd, the API gateway may return an HTTP 401 response with the following structure.

string

required

Value: error.

string

required

Reason for the authentication failure.

Next, use the returned bill_id to get a bill download URL.

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

curl --get 'https://api.stablepay.co/api/v1/bills' \
  --data-urlencode 'bill_date_from=2026-09-01' \
  --data-urlencode 'bill_date_to=2026-09-30' \
  --data-urlencode 'bill_types=payment,payment_fee' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "X-StablePay-Timestamp: ${TIMESTAMP}" \
  -H "X-StablePay-Nonce: ${NONCE}" \
  -H "X-StablePay-Signature: ${SIGNATURE}"

{
  "data": [
    {
      "bill_id": "1234567890",
      "bill_type": "payment",
      "bill_date": "2026-09-01",
      "currency": "USD",
      "transaction_count": 10
    }
  ],
  "total_count": 1,
  "page": 1,
  "page_size": 20
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid request parameters"
  },
  "request_id": "req_example",
  "timestamp": 1790812800
}

{
  "status": "error",
  "error": "Authentication failed"
}

Last modified on October 19, 2026

Getting Started

Payment API

Customer Deposits API

Global Accounts API

Refund API

Subscription API

Invoice API

Bills API

Payouts API

Authentication and Headers

Query Parameters

Success Response

Error Responses

Service Error Structure

Gateway Authentication Error Structure

​Authentication and Headers

​Query Parameters

​Success Response

​Error Responses

​Service Error Structure

​Gateway Authentication Error Structure

Authentication and Headers

Query Parameters

Success Response

Error Responses

Service Error Structure

Gateway Authentication Error Structure