Pre-Integration Setup

​

Essential Information

​

Prerequisites

1. Registered for a StablePay merchant account and completed the KYB (Know Your Business) verification
2. Created a store in the merchant dashboard, selected API as the channel type, and received approval
3. Generated and retrieved the following from the store’s “Key Management” menu:
   • 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 prettify)
• For GET/DELETE methods without a request body: Use an empty string for {requestBody}
• Signature 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 also requires an additional Idempotency-Key header. When retrying with the same key, the server returns the originally created subscription object.

​

Idempotency

​

Webhook Notifications

For event examples, frozen-risk handling, and the new status = "frozen" branch under payment.failed, see Webhook Notifications.

​

Event Types

​

Webhook Headers

​

Signature Verification Steps

1. Extract X-StablePay-Signature, X-StablePay-Timestamp, and X-StablePay-Nonce from the request headers
2. Verify the timestamp is within 5 minutes of the current time (replay attack prevention)
3. Verify the nonce length is between 16 and 64 characters
4. Take the raw request body bytes (do not parse and re-serialize), and concatenate as follows:
   sign_payload = {timestamp} + "." + {nonce} + "." + {raw_body}
   
5. Compute HMAC-SHA256 using your Secret Key, resulting in a lowercase hex string
6. Compare with the signature in the header using constant-time comparison (e.g., hmac.compare_digest)

import hashlib
import hmac
import time
from typing import Mapping


def verify_webhook(
    headers: Mapping[str, str],
    raw_body: bytes,
    secret_key: str,
    tolerance_seconds: int = 300,
) -> bool:
    """
    Verify StablePay webhook signature.

    Signature payload format:
        "{timestamp}.{nonce}.{raw_body}"

    Notes:
    - raw_body must be the original HTTP request body bytes.
    - do not parse JSON and serialize it again before verification.
    """

    if not secret_key:
        return False

    timestamp = headers.get("X-StablePay-Timestamp")
    nonce = headers.get("X-StablePay-Nonce")
    signature = headers.get("X-StablePay-Signature")

    if not timestamp or not nonce or not signature:
        return False

    try:
        ts = int(timestamp)
    except ValueError:
        return False

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

    if not (16 <= len(nonce) <= 64):
        return False

    signed_payload = (
        timestamp.encode("utf-8")
        + b"."
        + nonce.encode("utf-8")
        + b"."
        + raw_body
    )

    expected_signature = hmac.new(
        secret_key.encode("utf-8"),
        signed_payload,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected_signature, signature)

​

Response Requirements & Retry Policy

• Your service must return HTTP 2xx within 30 seconds
• Returning 429 or 5xx will trigger a retry, while other 4xx responses will not be retried
• Maximum of 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 on the 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
• For every received Webhook, perform signature verification + idempotent deduplication + business state validation (e.g., only process refunds if the order status is “paid”)
• Regularly rotate your API Keys and Secret Keys in the merchant dashboard