Pre-Integration Setup

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.

​

Basic Information

​

Prerequisites

1. Registered a StablePay merchant account and completed the qualification review
2. Created a store in the merchant dashboard, selected API as the channel type, and waited for approval
3. Generated and obtained the following from the “Key Management” menu in your store:
   • API Key: Used in the Authorization header to identify the caller
   • Secret Key: Used to generate request signatures. Store this securely and never commit it to public repositories or share it with others

​

Authentication & Signing

​

Required Headers

​

Signature Payload Construction

sign_payload = {timestamp} + "." + {nonce} + "." + {requestBody}

• {requestBody}: For POST / PUT requests, use the raw JSON string (do not re-serialize or format)
• For GET / DELETE methods without a request body: Use an empty string for {requestBody}
• Signing algorithm: HMAC-SHA256(sign_payload, secret_key) → lowercase hex string

​

Code Examples

TIMESTAMP=$(date +%s)
NONCE=$(uuidgen)
BODY='{"amount":1999,"currency":"USD"}'
SIGN_PAYLOAD="${TIMESTAMP}.${NONCE}.${BODY}"
SIGNATURE=$(echo -n "${SIGN_PAYLOAD}" | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $2}')

curl -X POST https://api.stablepay.co/api/v1/checkout/sessions/create \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "X-StablePay-Timestamp: ${TIMESTAMP}" \
  -H "X-StablePay-Nonce: ${NONCE}" \
  -H "X-StablePay-Signature: ${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d "${BODY}"

​

Required Headers by Endpoint

POST /api/v1/subscriptions/create additionally requires the Idempotency-Key header. When retrying with the same key, the server will return the originally created subscription object.

​

Idempotency

​

Webhook Notifications

​

Event Types

​

Webhook Headers

​

Signature Verification Steps

1. Extract X-StablePay-Signature and X-StablePay-Timestamp from headers; optionally log X-StablePay-Nonce for additional replay protection or logging
2. Verify the timestamp is within 5 minutes of current time (replay protection)
3. Take the raw request body bytes (do not parse then re-serialize) and concatenate as follows:
   sign_payload = {timestamp} + "." + {raw_body}
   
4. Apply HMAC-SHA256 using your Secret Key to get a lowercase hex string
5. Compare with the signature in the header using constant-time comparison (e.g., hmac.compare_digest)

​

Verification Example (Python)

import hmac, hashlib, time

def verify_webhook(headers, raw_body: bytes, secret_key: str) -> bool:
    ts = headers["X-StablePay-Timestamp"]
    sig = headers["X-StablePay-Signature"]

    if abs(int(time.time()) - int(ts)) > 300:
        return False

    sign_payload = f"{ts}.".encode() + raw_body
    expected = hmac.new(
        secret_key.encode(), sign_payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

​

Response Requirements & Retry Policy

• Your server must return HTTP 2xx within 30 seconds
• 429 or 5xx responses enter the retry queue; other 4xx responses are not retried
• Maximum 10 retries with exponential backoff intervals (minutes): 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024

​

Idempotent Consumption

​

Error Responses

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: refund_id",
    "param": "refund_id",
    "doc_url": "https://docs.stablepayfi.ai/errors#parameter_missing"
  },
  "request_id": "req_xxx",
  "timestamp": 1774924800
}

​

Security Best Practices

• Secret Keys should only be used server-side and must never appear in frontend code, APKs, mini-program packages, or logs
• We recommend injecting Secret Keys via a Key Management Service (KMS/Vault/SSM) in your CI/CD pipeline
• Webhook callback URLs must use HTTPS
• Perform signature verification + idempotent deduplication + business state validation for every received Webhook (e.g., ensure an order is “paid” before processing a refund)
• Regularly rotate your API Keys and Secret Keys in the merchant dashboard