AllScale Open API
Version: v6
Last Updated: 2026-09-09

Overview

AllScale delivers event notifications to your server via Webhook callbacks. Each webhook request is authenticated using HMAC-SHA256 request signing, providing:

Sender authentication (shared secret)
Payload integrity (tamper-proof)
Replay attack protection (timestamp + nonce)
Stateless verification (no session required)

Webhook payloads are plaintext JSON (not encrypted).

Credentials

When your integration/store is created, you receive:

Field	Description
api_key	Public identifier
api_secret	Secret key used for signature verification

Important Notes

api_secret is shown only once
It cannot be retrieved again
Store it securely
Treat it like a password or private key

Webhook Request

Method

POST

Content-Type

application/json

Required Headers

Header	Description
X-API-Key	API key
X-Webhook-Id	Unique webhook ID
X-Webhook-Timestamp	Unix timestamp(seconds)
X-Webhook-Nonce	Unique per-request nonce
X-Webhook-Signature	HMAC signature

Signature Header Format

X-Webhook-Signature: v1=<signature>

Replay Protection

To prevent replay attacks:

Requirements

Timestamp must be within ±5 minutes
Each nonce must be used only once

Recommended Implementation

Store nonce in Redis
TTL: 600 seconds
Reject duplicate nonces

Canonical String (v1)

Webhook signatures are generated using a canonical string.

Canonical Format

allscale:webhook:v1
METHOD
PATH
QUERY_STRING
WEBHOOK_ID
TIMESTAMP
NONCE
BODY_SHA256

Field Description

Field	Description
METHOD	HTTP method (uppercase)
PATH	URL path only
QUERY_STRING	Query string without `?`
WEBHOOK_ID	From `X-Webhook-Id`
TIMESTAMP	From `X-Webhook-Timestamp`
NONCE	From `X-Webhook-Nonce`
BODY_SHA256	SHA256 hex of raw body bytes

⚠️ Important BODY_SHA256 must be calculated from the raw request body bytes,
before JSON parsing or re-serialization.

Signature Algorithm

Algorithm

HMAC-SHA256

Encoding

Base64

Formula

signature = Base64(
  HMAC_SHA256(api_secret, canonical_string_bytes)
)

Header Example

X-Webhook-Signature: v1=<signature>

Webhook Payload

The request body sent by AllScale is exactly the following JSON structure.

JSON Field Definitions

Field	Type	Required	Description
all_scale_transaction_id	string	✅	AllScale transaction ID for this payment/transfer
all_scale_checkout_intent_id	string	✅	AllScale checkout intent ID associated with the payment
webhook_id	string	✅	Unique webhook ID (must match `X-Webhook-Id`)
amount_cents	integer	✅	Always the integer the merchant submitted on `POST /v1/checkout_intents/`. For fiat-priced intents this is fiat cents; for stable-coin-priced intents it is stable-coin “cents” (1.00 coin = 100 cents, equivalent to `int(amount_coins * 100)`).
currency	integer \| null	➖	Currency enum value (int). Must be interpreted using AllScale Currency enum mapping. `null` when the intent was priced natively in a stable coin — read `coin_symbol` instead.
currency_symbol	string \| null	➖	Fiat currency symbol (e.g., `USD`, `CAD`, `CNY`). `null` when the intent was priced natively in a stable coin — read `coin_symbol` instead.
amount_coins	string	✅	Stablecoin amount as a decimal string (to avoid float issues), e.g. `"12.340000"`
coin_contract_address	string	✅	Official ERC-20 token contract address
coin_symbol	string	✅	Stablecoin symbol (e.g., `USDT`, `USDC`)
chain_id	integer	✅	EIP-155 chainId identifying the EVM network (https://chainid.network/)
tx_hash	string	✅	On-chain transaction hash
tx_from	string	✅	Sender wallet address
payment_method_type	integer	✅	Payment method type used for this transaction. Value must correspond to the `PaymentMethodType` enum: `0=UNKNOWN`, `1=WALLET_SCAN`, `2=WALLET_CONNECT`, `3=ALL_SCALE_PAY`.
user_id	string \| null	➖	Optional merchant/user identifier
order_id	string \| null	➖	Optional merchant order identifier
user_name	string \| null	➖	Optional customer/user display name
extra_obj	object \| null	➖	Optional arbitrary JSON object with extra fields
status	integer \| null	➖	Settlement state of the checkout at the moment the callback was built. `20` = confirmed (paid). Check `status == 20` before treating an order as paid — do not infer payment from the mere arrival of a callback. `null` only on callbacks emitted before this field existed. See Verifying a callback.
actual_paid_amount	string \| null	➖	Amount the buyer paid, as a decimal string in the same unit as `amount_coins`. This is not necessarily the amount credited to your wallet — see Verifying a callback. `null` when it was not recorded.

Verifying a callback

Two fields let you confirm a payment from the callback itself rather than assuming that receiving one means “paid”. status — check it before marking an order paid. A callback is only ever built on confirmed settlement, so in practice status is 20. Check it anyway: it is the field that makes the assumption explicit, and an integration that defaults a missing or unexpected status to “paid” will mark unpaid orders as paid. Treat anything other than 20 as not paid, and treat null the same way unless you are knowingly processing a historical callback from before this field shipped. actual_paid_amount — it is the buyer’s payment, not always your credit. Read it as “what the buyer sent”, and note that the two are not always equal:

When the buyer pays your wallet directly, no platform fee is deducted along the way, so this equals the amount credited to you.
When the payment is routed through an AllScale temporary wallet, this is the buyer’s gross deposit. AllScale deducts the platform fee before settling to you, so the amount credited to your wallet is lower than this value.

So use actual_paid_amount to check what the buyer paid against what you charged. Do not use it as the figure to reconcile your wallet balance against — use your own on-chain record of the settlement transfer for that. amount_cents and amount_coins remain the amount you requested, unchanged by what was actually paid; comparing actual_paid_amount against them is how you detect an underpayment or overpayment.

Actual Webhook Body Example (Matches Real Structure)

Fiat-priced intent (merchant created with `currency`)

{
  "all_scale_transaction_id": "txn_123",
  "all_scale_checkout_intent_id": "chk_456",
  "webhook_id": "whk_84f12a8d",

  "amount_cents": 1234,
  "currency": 1,
  "currency_symbol": "USD",

  "amount_coins": "12.340000",
  "coin_contract_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "coin_symbol": "USDT",

  "chain_id": 1,
  "tx_hash": "0x...",
  "tx_from": "0x...",

  "payment_method_type": 1,
  "user_id": "user_001",
  "order_id": "order_8899",
  "user_name": "Alice",
  "extra_obj": {
    "source": "mobile",
    "note": "promo-applied"
  },

  "status": 20,
  "actual_paid_amount": "12.340000"
}

Stable-coin-priced intent (merchant created with `stable_coin`)

amount_cents is still an integer and equals amount_coins * 100. currency and currency_symbol are null — the buyer paid the merchant directly in coin_symbol, no fiat currency is involved.

{
  "all_scale_transaction_id": "txn_123",
  "all_scale_checkout_intent_id": "chk_456",
  "webhook_id": "whk_84f12a8d",

  "amount_cents": 1000,
  "currency": null,
  "currency_symbol": null,

  "amount_coins": "10.000000",
  "coin_contract_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "coin_symbol": "USDC",

  "chain_id": 1,
  "tx_hash": "0x...",
  "tx_from": "0x...",

  "payment_method_type": 1,
  "user_id": "user_001",
  "order_id": "order_8899",
  "user_name": "Alice",
  "extra_obj": null,

  "status": 20,
  "actual_paid_amount": "10.000000"
}

Verification Flow (Your Server Side)

Extract headers
Validate timestamp (±300 seconds)
Validate nonce (store with TTL)
Read raw request body bytes (before parsing JSON)
Compute SHA256 of raw body
Rebuild canonical string
Compute expected signature
Timing-safe compare
Only after verification → process payload

Response Expectations

Your endpoint should respond:

200 OK if processed successfully
Non-200 if rejected (signature invalid, timestamp invalid, etc.)

AllScale will log the HTTP status and may retry depending on configured policy.

Best Practices

✅ Always verify X-Webhook-Signature before processing
✅ Validate timestamp within ±5 minutes
✅ Cache nonce for replay protection
✅ Use idempotency via webhook_id
✅ Convert amount_coins using Decimal (not float)
❌ Never log secrets or signatures

Troubleshooting

Issue	Cause	Fix
Signature mismatch	Body modified	Use raw bytes exactly as received
Signature mismatch	Wrong path/query	Use the exact request path and query string
Signature mismatch	Wrong secret	Verify correct `api_secret`
Timestamp rejected	Clock drift	Sync server time (NTP)
Replay rejected	Nonce reused	Generate unique nonce; store with TTL

End of Document

Getting Started

Checkout Intents

Claim Links

Webhooks

Checkout Webhook

Overview

Credentials

Important Notes

Webhook Request

Method

Content-Type

Required Headers

Signature Header Format

Replay Protection

Requirements

Recommended Implementation

Canonical String (v1)

Canonical Format

Field Description

Signature Algorithm

Algorithm

Encoding

Formula

Header Example

Webhook Payload

JSON Field Definitions

Verifying a callback

Actual Webhook Body Example (Matches Real Structure)

Fiat-priced intent (merchant created with `currency`)

Stable-coin-priced intent (merchant created with `stable_coin`)

Verification Flow (Your Server Side)

Response Expectations

Best Practices

Troubleshooting

​Overview

​Credentials

​Important Notes

​Webhook Request

​Method

​Content-Type

​Required Headers

​Signature Header Format

​Replay Protection

​Requirements

​Recommended Implementation

​Canonical String (v1)

​Canonical Format

​Field Description

​Signature Algorithm

​Algorithm

​Encoding

​Formula

​Header Example

​Webhook Payload

​JSON Field Definitions

​Verifying a callback

​Actual Webhook Body Example (Matches Real Structure)

​Fiat-priced intent (merchant created with currency)

​Stable-coin-priced intent (merchant created with stable_coin)

​Verification Flow (Your Server Side)

​Response Expectations

​Best Practices

​Troubleshooting

Overview

Credentials

Important Notes

Webhook Request

Method

Content-Type

Required Headers

Signature Header Format

Replay Protection

Requirements

Recommended Implementation

Canonical String (v1)

Canonical Format

Field Description

Signature Algorithm

Algorithm

Encoding

Formula

Header Example

Webhook Payload

JSON Field Definitions

Verifying a callback

Actual Webhook Body Example (Matches Real Structure)

Fiat-priced intent (merchant created with `currency`)

Stable-coin-priced intent (merchant created with `stable_coin`)

Verification Flow (Your Server Side)

Response Expectations

Best Practices

Troubleshooting