# Welcome to AllScale At **AllScale**, we believe the future of finance should be **borderless, instant, and inclusive**. We are building solutions to make stablecoin more accessible, intuitive, and compliant for small businesses and individuals, including end-to-end stablecoin-based invoicing, sales, and payroll. We power the last-mile of enterprise stablecoin adoption. ## Our Vision To create a world where **any business, anywhere**, can access fast, reliable, and low-cost financial tools—empowering teams and individuals with **financial freedom** and **global reach**. *** ## What We Value
🔗 Stablecoin-Driven Simplicity By using stablecoins, we cut out unnecessary friction — enabling **instant, low-fee, and currency-stable transactions** that work anywhere in the world.
🌐 Global Workforce Empowerment From startups to DAOs, we empower teams to **scale across borders** without the usual barriers — no matter where their employees, freelancers, or creators are located.
💸 Financial Inclusion for All We believe access to professional financial tools shouldn’t be limited by geography or banking infrastructure. AllScale opens doors for the **unbanked, underbanked**, and those building outside traditional systems.
🧠 Ease of Use, Built-In Whether it’s **sending payroll**, **collecting payments**, or **launching a storefront**, our products are designed to be **intuitive, fast, and no-code-friendly**—so you can focus on growing your business.
💼 Cost-Efficient & Scalable We replace hidden fees and outdated systems with **transparent, affordable pricing** and **modular tools** that grow with your needs — from solo-entrepreneurs to global organizations.
*** ## What We Offer
:money\_mouth: [**Payroll**](/allscale-payroll/allscale-payroll-introduction) Automate cross-border payroll in stablecoins—simplify contractor payments, eliminate costly intermediaries, and ensure instant global delivery. AllScale Payroll unifies hiring, HR management, invoicing, and compliance in one seamless, stablecoin-ready platform. Pay anyone, anywhere in minutes—not days—with enterprise-grade tools (including EOR services in 100+ countries). :receipt: [**Invoicing**](/allscale-pay/core-modules/invoicing) Create, e-sign, and send professional contracts and invoices in seconds. Get paid by clients in their preferred method (credit card, wire transfer, or crypto) and instantly receive stablecoins—maximizing liquidity, minimizing friction. No client AllScale account required. Payments settle directly into your self-custodial wallet regardless of how the payer funds the invoice. :shopping\_cart: [**Checkout**](/allscale-checkout/getting-started) Enable seamless, next-generation payments for your store or services with AllScale Checkout. Accept crypto or traditional methods with instant stablecoin settlement, web3 wallet support (auto-bridge & swap), built-in Auto-KYT compliance, and zero-knowledge data protection. Frictionless for customers, instant liquidity for you. :bank: [**Wallet**](/allscale-pay/core-modules/wallet/wallet-overview) A non-custodial wallet where the private key is in the hands of the user, but there is no need to record the mnemonic phrase! Powered by passkeys and account abstraction, you retain full control while logging in quickly with 2FA (or biometrics) to manage, receive, hold, and withdraw your stablecoin assets. *** ## Video overview {% embed url="" %} ## Quick Links {% content-ref url="/pages/3g2Zi2CFtDqjvV8Ioa7J" %} [Allscale Payroll Introduction](/allscale-payroll/allscale-payroll-introduction) {% endcontent-ref %} {% content-ref url="/pages/tJ6nCzZ7eTtYvSaH3VQZ" %} [AllScale Pay Introduction](/allscale-pay/allscale-pay-introduction) {% endcontent-ref %} # Getting Started ## Prerequisites * API credentials (API Key & Secret) * Webhook endpoint for payment notifications ## Environment Endpoints ### **Environment** ``` Base URL: https://openapi.allscale.io ``` *** ## Quick Start Guide ### **Step 1: Get Access** 1. Register and open , then navigate to **Settings → Commerce,** long-press the "Enable now" button to enable Checkout.
2. After enabling Checkout, you can follow the guidelines to set up your first store, freely choosing the store type and the specific stablecoins you wish to accept.
3. Obtain your API Key and API Secret; please be sure to save your API Secret immediately, then enter the confirmation phrase to successfully create the store.
**Optional: One-Click Setup with AI** Using Claude Code, Cursor, Windsurf, or any AI coding assistant? Just tell it: > read and install allscale.io/skill Your AI will fetch the guide and wire up authentication, intent creation, and webhook verification automatically. You can also point your assistant at — a single-file dump of the entire API documentation, optimized for LLM ingestion. ### **Step 2: Test Your Integration** **Before diving into payment flows, verify your setup with test endpoints:** Follow the [Authentication](/allscale-checkout/api-reference/api-doc-auth) Guide to implement API authentication, then [test](/allscale-checkout/api-reference/api-doc-test-route) these endpoints: 1. **GET /v1/test/ping** - Verify connection and authentication 2. **GET /v1/test/fail** - Test error handling 3. **POST /v1/test/post** - Test POST requests with payload ✅ Once all three test routes return expected responses, proceed to Step 3. See [Test Route Documentation](/allscale-checkout/api-reference/api-doc-test-route) for details. **Prefer Postman?** See [Get Started via Postman](/allscale-checkout/quickstart-with-postman) — import the collection, paste your keys, and every v1 endpoint is one click away with HMAC signing already wired up. No signing code required. ### **Step 3: Configure Webhooks** * Configure your webhook URL in the merchant dashboard
* Implement signature verification (see [**Webhook Signing**](/allscale-checkout/api-reference/api-doc-webhook-signing-and-payload-guide)) ### **Step 4: Implement Payment Flow** Review the [Integration Flow](/allscale-checkout/api-reference) and implement: * [Create Checkout Intent](/allscale-checkout/api-reference/api-doc-checkout-intent-routes-create-checkout-intent) * [Query Intent Status](/allscale-checkout/api-reference/api-doc-checkout-intent-routes-get-status) ### **Step 5:** Personalize your payment settings In "Store Settings," you can also adjust payment-related settings according to your preferences * **Enable Swidge**: Once enabled, you can accept payments in cryptocurrencies other than stablecoins; AllScale will automatically perform a "Swap + Bridge" to convert them into stablecoins and deposit the funds into your account. * **Pay with Card and Local Payment**: Enabling this feature allows your customers to pay with credit cards and local payment methods, Visa, Mastercard, Apple Pay and more are supported.
* **Claim Link:** Once enabled, you can generate large batches of claim links via the API; simply activate the feature in the settings and specify the amount and blockchain for each link to get started.
In addition, you can configure settings for features such as **Accepted Tokens**, **Webhook signatures**, **Response Signatures**, and **Enable Unique Order ID Check**. *** ## API Documentation ### **Single-File Reference for AI Tools** If you're using an AI coding assistant or want the entire API spec in one place, fetch — every doc page concatenated into a single LLM-friendly text file. **Core Concepts** | Module | Description | | ---------------- | ---------------------------------------- | | Authentication | Request signing using API Key and Secret | | Integration Flow | Complete end-to-end payment workflow | **Security** | Module | Description | | ---------------- | -------------------------------------------------- | | Response Signing | Optional: Verify the authenticity of API responses | | Webhook Signing | Required: Verify webhook callback signatures | **API Routes** | Route | Description | | ---------------------- | ------------------------------- | | Test Routes | Verify your integration setup | | Get Checkout Intent | Retrieve intent sessions | | Get Intent Status | Query the current intent status | | Create Checkout Intent | Create a new checkout intent | **Tooling** | Resource | Description | | ------------------------------------------------------- | ------------------------------------------------------------------------- | | Get Started via Postman | Import a pre-signed Postman collection to hit every v1 endpoint instantly | | [llms-full.txt](https://docs.allscale.io/llms-full.txt) | Full API documentation as a single file, for AI assistants | *** ### Support Contact your Relationship Manager for assistance. *** ## Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.allscale.io/allscale-checkout/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections. For bulk ingestion (loading the full spec into an AI assistant or local tooling), prefer — it ships every doc page as a single text file. # API Reference
# API Doc - Test Route **AllScale Open API**\ **Version:** v1\ **Last updated:** 2026-01-23\ **Base Path:** `/v1/test` *** ### Overview The Test API provides endpoints used to verify: * API authentication * Request signing * Replay protection * Error handling behavior * JSON body hashing and parsing All endpoints require valid authentication using the HMAC-based signing mechanism. *** ### Authentication All requests must include the following headers: | Header | Description | | ----------- | ------------------------- | | X-API-Key | API key | | X-Timestamp | Unix timestamp (seconds) | | X-Nonce | Unique request identifier | | X-Signature | HMAC signature | Requests missing any of these headers will be rejected. *** ### GET /v1/test/ping #### Description Health-check endpoint used to verify: * API connectivity * Signature correctness * Authentication configuration #### Request ``` GET /v1/test/ping ``` Headers: ``` X-API-Key: X-Timestamp: X-Nonce: X-Signature: v1= ``` #### Successful Response ```json { "code": 0, "payload": { "pong": "ok" }, "error": null, "request_id": "req_xxxxx" } ``` #### Response Fields | Field | Description | | ------------ | ------------------------- | | code | 0 indicates success | | payload.pong | Always returns "ok" | | error | Always null | | request\_id | Unique request identifier | #### Possible Errors | Code | Meaning | | ----- | ------------------------------ | | 20001 | Missing authentication headers | | 20002 | Invalid signature | | 30001 | Forbidden (IP not allowed) | | 40001 | Rate limit exceeded | *** ### GET /v1/test/fail #### Description This endpoint always returns a validation error.\ It is used to test client-side error handling and error parsing. #### Request ``` GET /v1/test/fail ``` Headers: ``` X-API-Key: X-Timestamp: X-Nonce: X-Signature: v1= ``` #### Error Response ```json { "code": 10001, "payload": null, "error": { "message": "Validation error", "details": {} }, "request_id": "req_xxxxx" } ``` #### Error Code | Code | Meaning | | ----- | ---------------- | | 10001 | Validation error | *** ### POST /v1/test/post #### Description Echo test endpoint. Used to verify: * Request signing * Body hashing * JSON parsing * Response format #### Request ``` POST /v1/test/post ``` Headers: ``` X-API-Key: X-Timestamp: X-Nonce: X-Signature: v1= Content-Type: application/json ``` Body (example): ```json { "everything": "is_fine" } ``` #### Successful Response ```json { "code": 0, "payload": { "your_request_body": { "everything": "is_fine" } }, "error": null, "request_id": "req_xxxxx" } ``` #### Notes * The request body may include any valid JSON object. * The response returns the request body under `payload.your_request_body`. #### Possible Errors | Code | Meaning | | ----- | ------------------------------------ | | 20001 | Missing authentication headers | | 20002 | Invalid signature | | 30001 | Forbidden (IP not allowed) | | 40001 | Rate limit exceeded | | 10001 | Validation error (invalid JSON body) | *** ### Usage Recommendations * Use `/v1/test/ping` to verify authentication setup * Use `/v1/test/post` to verify body signing (hashing) and JSON parsing * Use `/v1/test/fail` to test error parsing * Always log `request_id` for debugging * Ensure timestamps are in UTC * Never reuse nonces *** ### Notes * All test endpoints require valid authentication * Requests are subject to replay protection * Responses follow the standard API response format *** End of document. # API Doc - Auth AllScale Third-Party API\ Version: v1\ Last updated: 2026-01 *** ### Overview AllScale APIs use HMAC-SHA256 request signing to authenticate and authorize third-party requests. This mechanism provides: * Strong authentication (shared secret) * Replay-attack protection * Tamper-proof request integrity * Stateless verification * Enterprise-grade security Every API request must be signed using: * API Key * API Secret *** ### Credentials When your store or integration is created, you receive: | Field | Description | | ----------- | ---------------------------- | | api\_key | Public identifier | | api\_secret | Secret key (shown once only) | Important: * The API secret is shown only once * It cannot be retrieved later * Store it securely * Treat it like a password or private key *** ### Required Request Headers | Header | Required | Description | | ----------- | -------- | ------------------------ | | X-API-Key | Yes | Your API key | | X-Timestamp | Yes | Unix timestamp (seconds) | | X-Nonce | Yes | Random unique string | | X-Signature | Yes | HMAC signature | *** ### Request Signing Logic #### Canonical String Format ``` METHOD PATH QUERY_STRING TIMESTAMP NONCE BODY_SHA256 ``` Joined using newline characters. #### Example ``` POST /v1/payments currency=USD 1716501000 b4d9a2a1-9c2b-4df4-8b8e-2a13a45fd321 4e07408562bedb8b60ce05c1decfe3ad16b722309a7c4c5f64b1f4e48e8d8d69 ``` *** ### Signature Algorithm Algorithm: ``` HMAC-SHA256 ``` Encoding: ``` Base64 ``` Formula: ``` signature = Base64( HMAC_SHA256(api_secret, canonical_string) ) ``` Header format: ``` X-Signature: v1= ``` *** ### JavaScript / Postman Example ```javascript const API_KEY = pm.environment.get("API_KEY"); const API_SECRET = (pm.environment.get("API_SECRET") || "").trim(); async function hmacSha256Base64(key, msg) { const enc = new TextEncoder(); const cryptoKey = await crypto.subtle.importKey( "raw", enc.encode(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"] ); const sig = await crypto.subtle.sign("HMAC", cryptoKey, enc.encode(msg)); return btoa(String.fromCharCode(...new Uint8Array(sig))); } function sha256Hex(str) { return CryptoJS.SHA256(str).toString(CryptoJS.enc.Hex); } const method = pm.request.method.toUpperCase(); const path = pm.request.url.getPath(); const query = pm.request.url.getQueryString() || ""; const body = pm.request.body?.raw || ""; const bodyHash = sha256Hex(body); const timestamp = Math.floor(Date.now() / 1000).toString(); const nonce = crypto.randomUUID(); const canonical = [ method, path, query, timestamp, nonce, bodyHash ].join("\n"); const signature = await hmacSha256Base64(API_SECRET, canonical); pm.request.headers.upsert({ key: "X-API-Key", value: API_KEY }); pm.request.headers.upsert({ key: "X-Timestamp", value: timestamp }); pm.request.headers.upsert({ key: "X-Nonce", value: nonce }); pm.request.headers.upsert({ key: "X-Signature", value: `v1=${signature}` }); ``` *** ### Replay Protection All requests are protected using timestamp and nonce validation. Rules: * Timestamp must be within ±5 minutes * Each nonce can be used only once * Replayed requests are rejected *** ### IP Allowlist If configured, requests must originate from approved IP ranges. Examples: ``` 192.168.1.0/24 203.0.113.45/32 ``` Empty allowlist means all IPs are allowed. *** ### Error Response Format ```json { "code": 20002, "payload": null, "error": { "message": "Bad signature", "details": { "reason": "signature_mismatch" } }, "request_id": "req_xxx" } ``` #### Error Codes | Code | Meaning | | ----- | ------------------------------ | | 20001 | Missing authentication headers | | 20002 | Invalid signature | | 30001 | Forbidden | | 40001 | Rate limit exceeded | | 90000 | Internal server error | *** ### Rate Limiting Requests may be rate-limited. Example response: ```json { "code": 40001, "payload": null, "error": { "message": "Rate limit exceeded" }, "request_id": "req_xxx" } ``` *** ### Debugging Tips | Issue | Fix | | --------------- | -------------------- | | Body mismatch | Use raw JSON | | Query mismatch | Ensure order matches | | Wrong secret | Use original secret | | Timestamp drift | Sync system clock | | Nonce reused | Generate a new one | | CryptoJS | Use Web Crypto API | *** ### Best Practices * Always use HTTPS * Use UTC timestamps * Store secrets securely * Rotate secrets regularly * Log request IDs * Never expose secrets in frontend code * Never reuse nonces *** End of document. # API Doc - Webhook Signing & Payload Guide **AllScale Open API**\ **Version:** v5\ **Last Updated:** 2026-04-30 *** ### 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 ```http POST ``` #### Content-Type ```http 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 ```http X-Webhook-Signature: v1= ``` *** ### 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= ``` *** ## 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 () | | 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 | ### Actual Webhook Body Example (Matches Real Structure) #### Fiat-priced intent (merchant created with `currency`) ```json { "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" } } ``` #### 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. ```json { "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 } ``` *** ### Verification Flow (Your Server Side) 1. Extract headers 2. Validate timestamp (±300 seconds) 3. Validate nonce (store with TTL) 4. Read raw request body bytes (before parsing JSON) 5. Compute SHA256 of raw body 6. Rebuild canonical string 7. Compute expected signature 8. Timing-safe compare 9. 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 # API Doc - Checkout Intent Routes - Create Checkout Intent **AllScale Open API**\ **Version:** v4\ **Last updated:** 2026-05-06\ **Base Path:** `/v1/checkout_intents` *** ### Overview The Checkout Intent API allows merchants to create a checkout intent and obtain a hosted payment URL. This API is used to: * Create a checkout intent * Generate a hosted checkout URL * Price the order in either a **fiat currency** (converted to stable coin at the current FX rate) or **natively in a stable coin** (no FX, 1:1) * Receive stable-coin–based settlement *** ### Important Design Notes * All enum values are represented as **integers** in API requests and responses * API consumers must always send and receive **integer values** * **USDT** and **USDC** are supported as settlement stable coins *** ### Authentication All requests must include the following headers: | Header | Description | | ----------- | ------------------------- | | X-API-Key | API key | | X-Timestamp | Unix timestamp (seconds) | | X-Nonce | Unique request identifier | | X-Signature | HMAC signature | #### Notes * `X-Nonce` must be unique per request * `X-Timestamp` must be within allowed time window * Signature must be generated using **raw request body bytes** * Requests are protected against replay attacks *** ### POST /v1/checkout\_intents/ #### Description Create a checkout intent and return a hosted checkout URL. *** #### Request POST /v1/checkout\_intents/ **Headers** ``` X-API-Key: X-Timestamp: X-Nonce: X-Signature: v1= Content-Type: application/json ``` **Body Example — Fiat pricing (FX-converted)** ```json { "currency": 44, "amount_cents": 100, "order_id": "order_123", "order_description": "Monthly subscription", "user_id": "user_456", "user_name": "Tom", "redirect_url": "https://example.com/checkout/allscale", "extra": { "source": "web" } } ``` **Body Example — Native stable-coin pricing (no FX)** `amount_cents` is interpreted as stable-coin "cents": `1000` = `10.00 USDT`. `currency_rate` on the resulting intent is `null` because no FX conversion happens. ```json { "stable_coin": 1, "amount_cents": 1000, "order_id": "order_124", "redirect_url": "https://example.com/checkout/allscale" } ``` #### Request Fields | Field | Type | Required | Description | | ----------------------- | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | currency | int \| null | ⚠️ | Fiat currency enum value (see Appendix A). **Set exactly one of `currency` or `stable_coin`.** When set, `amount_cents` is FX-converted to the stable coin at the current rate. | | stable\_coin | int \| null | ⚠️ | Stable-coin enum value (see Appendix B). **Set exactly one of `currency` or `stable_coin`.** When set, `amount_cents` is the native stable-coin amount × 100 (no FX). | | amount\_cents | int | ✅ | Amount in cents (fiat cents when `currency` is set; stable-coin cents when `stable_coin` is set — `100` = `1.00` coin) | | order\_id | string \| null | ❌ | Merchant order ID | | redirect\_url | string \| null | ❌ | URL to which the user will be redirected after payment is completed | | order\_description | string \| null | ❌ | Merchant order description | | user\_id | string \| null | ❌ | Merchant user ID | | user\_name | string \| null | ❌ | Merchant user name | | extra | object \| null | ❌ | More metadata from merchant | | accepted\_stable\_coins | list\[int] \| null | ❌ | StableCoin enum values the payer may settle in (Appendix B; e.g. `[1]` USDT-only, `[2]` USDC-only, `[1, 2]` either). When omitted, the backend falls back to the merchant's store/business setting and finally to the global default (USDT). | ⚠️ **Important** * Exactly one of `currency` or `stable_coin` must be set. Sending both, or neither, returns a `10001` validation error. * `currency` and `stable_coin` must be integer values (Appendix A / B). Do NOT pass `"USD"` or `"USDT"` strings. * For native stable-coin pricing, **USDT (`1`)** and **USDC (`2`)** are accepted. Other stable-coin enum values are reserved for future rollout and will be rejected. * The payment amount must be **greater than** 0.1 USDT / 0.1 USDC. Orders at or below this floor are rejected with a `50002` error of the form `amount must be greater than 0.1 !`, where `` is the resolved settlement coin name (`USDT` or `USDC`). * For **fiat-priced** orders that should settle in a specific stable coin, send `accepted_stable_coins` — the **first entry** picks the settlement coin used for FX conversion. Example: `"currency": 1, "accepted_stable_coins": [2]` settles a USD-priced order in USDC. Without `accepted_stable_coins` the backend falls back to the merchant's configured default. * `accepted_stable_coins` must be non-empty when provided and contain only valid StableCoin enum values; otherwise the request is rejected with `10001`. *** #### Successful Response ```json { "code": 0, "payload": { "checkout_url": "https://checkout.allscale.io/abc123", "allscale_checkout_intent_id": "65b2f3d0d2d9c0a1b2c3d4e5", "amount_coins": "1.0000", "stable_coin_type": 1, "rate": "1.3500", "accepted_stable_coins": 1 }, "error": null, "request_id": "req_xxxxx" } ``` *** #### Response Fields | Field | Type | Description | | -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | code | int | 0 indicates success | | payload.checkout\_url | string | Hosted checkout URL | | payload.allscale\_checkout\_intent\_id | string | Checkout intent ID | | payload.amount\_coins | string | Stable coin amount | | payload.stable\_coin\_type | int | Stable coin enum value | | payload.rate | string \| null | Exchange rate | | payload.accepted\_stable\_coins | int \| null | StableCoinFlag bitmask of stablecoins the payer may settle in for this intent (`1` = USDT, `2` = USDC, `3` = either; bit `n` = StableCoin enum value `n+1`). `null` on intents created before the multi-coin rollout. | | error | object \| null | Error object | | request\_id | string | Request identifier | *** ### Possible Errors | Code | Meaning | | ----- | ------------------------------------------------------------------------- | | 10001 | Validation error | | 20001 | Missing authentication headers | | 20002 | Invalid signature | | 30001 | Forbidden (IP not allowed) | | 40001 | Rate limit exceeded | | 50002 | Create checkout intent error (e.g. amount at or below the 0.1-coin floor) | *** ### Notes * All enum values are integers * Do not send string enum names * Nonce must be unique per request * Timestamp must be UTC * Always log `request_id` for debugging *** ## Appendix A — Currency Enum (IntEnum) | Value | Code | Currency | | ----: | ---- | --------------------------------------- | | 1 | USD | US Dollar | | 2 | AED | United Arab Emirates Dirham | | 3 | AFN | Afghan Afghani | | 4 | ALL | Albanian Lek | | 5 | AMD | Armenian Dram | | 6 | ANG | Netherlands Antillean Guilder | | 7 | AOA | Angolan Kwanza | | 8 | ARS | Argentine Peso | | 9 | AUD | Australian Dollar | | 10 | AWG | Aruban Florin | | 11 | AZN | Azerbaijani Manat | | 12 | BAM | Bosnia and Herzegovina Convertible Mark | | 13 | BBD | Barbadian Dollar | | 14 | BDT | Bangladeshi Taka | | 15 | BGN | Bulgarian Lev | | 16 | BHD | Bahraini Dinar | | 17 | BIF | Burundian Franc | | 18 | BMD | Bermudian Dollar | | 19 | BND | Brunei Dollar | | 20 | BOB | Bolivian Boliviano | | 21 | BRL | Brazilian Real | | 22 | BSD | Bahamian Dollar | | 23 | BTN | Bhutanese Ngultrum | | 24 | BWP | Botswanan Pula | | 25 | BYN | Belarusian Ruble | | 26 | BZD | Belize Dollar | | 27 | CAD | Canadian Dollar | | 28 | CDF | Congolese Franc | | 29 | CHF | Swiss Franc | | 30 | CLP | Chilean Peso | | 31 | CNY | Chinese Yuan | | 32 | COP | Colombian Peso | | 33 | CRC | Costa Rican Colón | | 34 | CUP | Cuban Peso | | 35 | CVE | Cape Verdean Escudo | | 36 | CZK | Czech Koruna | | 37 | DJF | Djiboutian Franc | | 38 | DKK | Danish Krone | | 39 | DOP | Dominican Peso | | 40 | DZD | Algerian Dinar | | 41 | EGP | Egyptian Pound | | 42 | ERN | Eritrean Nakfa | | 43 | ETB | Ethiopian Birr | | 44 | EUR | Euro | | 45 | FJD | Fijian Dollar | | 46 | FKP | Falkland Islands Pound | | 47 | FOK | Faroese Króna | | 48 | GBP | British Pound | | 49 | GEL | Georgian Lari | | 50 | GGP | Guernsey Pound | | 51 | GHS | Ghanaian Cedi | | 52 | GIP | Gibraltar Pound | | 53 | GMD | Gambian Dalasi | | 54 | GNF | Guinean Franc | | 55 | GTQ | Guatemalan Quetzal | | 56 | GYD | Guyanese Dollar | | 57 | HKD | Hong Kong Dollar | | 58 | HNL | Honduran Lempira | | 59 | HRK | Croatian Kuna | | 60 | HTG | Haitian Gourde | | 61 | HUF | Hungarian Forint | | 62 | IDR | Indonesian Rupiah | | 63 | ILS | Israeli New Shekel | | 64 | IMP | Isle of Man Pound | | 65 | INR | Indian Rupee | | 66 | IQD | Iraqi Dinar | | 67 | IRR | Iranian Rial | | 68 | ISK | Icelandic Króna | | 69 | JEP | Jersey Pound | | 70 | JMD | Jamaican Dollar | | 71 | JOD | Jordanian Dinar | | 72 | JPY | Japanese Yen | | 73 | KES | Kenyan Shilling | | 74 | KGS | Kyrgyzstani Som | | 75 | KHR | Cambodian Riel | | 76 | KID | Kiribati Dollar | | 77 | KMF | Comorian Franc | | 78 | KRW | South Korean Won | | 79 | KWD | Kuwaiti Dinar | | 80 | KYD | Cayman Islands Dollar | | 81 | KZT | Kazakhstani Tenge | | 82 | LAK | Lao Kip | | 83 | LBP | Lebanese Pound | | 84 | LKR | Sri Lankan Rupee | | 85 | LRD | Liberian Dollar | | 86 | LSL | Lesotho Loti | | 87 | LYD | Libyan Dinar | | 88 | MAD | Moroccan Dirham | | 89 | MDL | Moldovan Leu | | 90 | MGA | Malagasy Ariary | | 91 | MKD | Macedonian Denar | | 92 | MMK | Myanmar Kyat | | 93 | MNT | Mongolian Tögrög | | 94 | MOP | Macanese Pataca | | 95 | MRU | Mauritanian Ouguiya | | 96 | MUR | Mauritian Rupee | | 97 | MVR | Maldivian Rufiyaa | | 98 | MWK | Malawian Kwacha | | 99 | MXN | Mexican Peso | | 100 | MYR | Malaysian Ringgit | | 101 | MZN | Mozambican Metical | | 102 | NAD | Namibian Dollar | | 103 | NGN | Nigerian Naira | | 104 | NIO | Nicaraguan Córdoba | | 105 | NOK | Norwegian Krone | | 106 | NPR | Nepalese Rupee | | 107 | NZD | New Zealand Dollar | | 108 | OMR | Omani Rial | | 109 | PAB | Panamanian Balboa | | 110 | PEN | Peruvian Sol | | 111 | PGK | Papua New Guinean Kina | | 112 | PHP | Philippine Peso | | 113 | PKR | Pakistani Rupee | | 114 | PLN | Polish Złoty | | 115 | PYG | Paraguayan Guaraní | | 116 | QAR | Qatari Riyal | | 117 | RON | Romanian Leu | | 118 | RSD | Serbian Dinar | | 119 | RUB | Russian Ruble | | 120 | RWF | Rwandan Franc | | 121 | SAR | Saudi Riyal | | 122 | SBD | Solomon Islands Dollar | | 123 | SCR | Seychellois Rupee | | 124 | SDG | Sudanese Pound | | 125 | SEK | Swedish Krona | | 126 | SGD | Singapore Dollar | | 127 | SHP | Saint Helena Pound | | 128 | SLE | Sierra Leonean Leone (new) | | 129 | SLL | Sierra Leonean Leone (old) | | 130 | SOS | Somali Shilling | | 131 | SRD | Surinamese Dollar | | 132 | SSP | South Sudanese Pound | | 133 | STN | São Tomé and Príncipe Dobra | | 134 | SYP | Syrian Pound | | 135 | SZL | Swazi Lilangeni | | 136 | THB | Thai Baht | | 137 | TJS | Tajikistani Somoni | | 138 | TMT | Turkmenistani Manat | | 139 | TND | Tunisian Dinar | | 140 | TOP | Tongan Paʻanga | | 141 | TRY | Turkish Lira | | 142 | TTD | Trinidad and Tobago Dollar | | 143 | TVD | Tuvaluan Dollar | | 144 | TWD | New Taiwan Dollar | | 145 | TZS | Tanzanian Shilling | | 146 | UAH | Ukrainian Hryvnia | | 147 | UGX | Ugandan Shilling | | 148 | UYU | Uruguayan Peso | | 149 | UZS | Uzbekistani Som | | 150 | VES | Venezuelan Bolívar | | 151 | VND | Vietnamese Dong | | 152 | VUV | Vanuatu Vatu | | 153 | WST | Samoan Tālā | | 154 | XAF | Central African CFA Franc | | 155 | XCD | East Caribbean Dollar | | 156 | XCG | Caribbean Guilder | | 157 | XDR | IMF Special Drawing Rights | | 158 | XOF | West African CFA Franc | | 159 | XPF | CFP Franc | | 160 | YER | Yemeni Rial | | 161 | ZAR | South African Rand | | 162 | ZMW | Zambian Kwacha | | 163 | ZWL | Zimbabwe Dollar | *** ## Appendix B — StableCoin Enum (IntEnum) | Value | Code | Name | Status | | ----: | ---- | --------------- | ----------- | | 1 | USDT | Tether USD | ✅ Supported | | 2 | USDC | USD Coin | ✅ Supported | | 3 | BUSD | Binance USD | ❌ Disabled | | 4 | DAI | Dai | ❌ Disabled | | 5 | TUSD | TrueUSD | ❌ Disabled | | 6 | PAX | Pax Dollar | ❌ Disabled | | 7 | GUSD | Gemini Dollar | ❌ Disabled | | 8 | USTC | TerraClassicUSD | ❌ Disabled | | 9 | FRAX | Frax | ❌ Disabled | | 10 | EURS | Stasis Euro | ❌ Disabled | *** ✅ **Current Behavior** Successful checkout intents return `stable_coin_type` equal to the resolved settlement coin: ```json "stable_coin_type": 1 // USDT "stable_coin_type": 2 // USDC ``` The value matches whichever supported coin was selected by the merchant via `stable_coin` (native pricing) or `accepted_stable_coins` (fiat pricing fallback order). Defaults to `1` (USDT) when neither is set. *** End of document. # API Doc - Checkout Intent Routes - Get Status **AllScale Open API**\ **Version:** v3\ **Last updated:** 2026-05-14\ **Base Path:** `/v1/checkout_intents` *** ### Overview The Checkout Intent Status API allows merchants to query the **current status** of a checkout intent. This API is used to: * Retrieve the checkout intent status by `checkout_intent_id` * Poll status after creating a checkout intent and redirecting users to hosted checkout *** ### Important Design Notes * All enum values are represented as **integers** in API requests and responses * API consumers must always send and receive **integer values** * This endpoint returns **only** the status integer (in `payload`) *** ### Authentication All requests must include the following headers: | Header | Description | | ----------- | ------------------------- | | X-API-Key | API key | | X-Timestamp | Unix timestamp (seconds) | | X-Nonce | Unique request identifier | | X-Signature | HMAC signature | #### Notes * `X-Nonce` must be unique per request * `X-Timestamp` must be within allowed time window * Signature must be generated using **raw request body bytes** * Requests are protected against replay attacks *** ### GET /v1/checkout\_intents/{checkout\_intent\_id}/status #### Description Get the checkout intent status as an integer. *** #### Request GET /v1/checkout\_intents/{checkout\_intent\_id}/status **Path Parameters** | Parameter | Type | Required | Description | | -------------------- | ------ | -------: | ---------------------------------------- | | checkout\_intent\_id | string | ✅ | AllScale checkout intent ObjectId string | **Headers** ``` X-API-Key: X-Timestamp: X-Nonce: X-Signature: v1= ``` > Note: This is a GET request, so there is no request body. *** #### Successful Response ```json { "code": 0, "payload": 2, "error": null, "request_id": "req_xxxxx" } ``` * `payload` is the **checkout intent status integer**. *** #### Response Fields | Field | Type | Description | | ----------- | -------------- | --------------------------------- | | code | int | 0 indicates success | | payload | int | Checkout intent status enum value | | error | object \| null | Error object | | request\_id | string | Request identifier | *** ### Possible Errors | Code | Meaning | | ----- | ------------------------------------------------------ | | 10001 | Validation error | | 20001 | Missing authentication headers | | 20002 | Invalid signature | | 30001 | Forbidden (no permission to view this checkout intent) | | 40001 | Rate limit exceeded | | 50001 | Checkout intent not found | | 90000 | Internal server error, pls contact us | | 99999 | Unknown error, pls contact us | *** ### Notes * This endpoint enforces permission checks: the checkout intent must belong to the authenticated store/business context. * Always log `request_id` for debugging. * Since `payload` is an int, do not expect `payload.status` or other nested fields. *** ## Appendix — Checkout Intent Status Enum | **Value** | **Name** | **Meaning** | **Terminal** | | --------- | ---------------------- | ------------------------------------------------------ | ------------ | | -1 | FAILED | Checkout failed due to internal or processing error | ✅ | | -2 | REJECTED | Rejected by KYT (Know Your Transaction) checks | ✅ | | -3 | UNDERPAID | Paid amount is less than required | ✅ | | -4 | CANCELED | User manually canceled the checkout | ✅ | | -5 | TIMEOUT | Checkout expired due to inactivity or time limit | ✅ | | 1 | CREATED | Checkout intent created, not yet viewed by user | ❌ | | 2 | VIEWED | Hosted checkout page has been opened by the user | ❌ | | 3 | TEMP\_WALLET\_RECEIVED | Temporary deposit wallet assigned (KYT flow only) | ❌ | | 4 | MANUAL\_OPERATION | Stuck in TEMP\_WALLET\_RECEIVED; pending manual review | ❌ | | 5 | SEND\_BACK | Refund in progress back to payer (KYT or underpaid) | ❌ | | 10 | ON\_CHAIN | On-chain transaction detected, awaiting confirmation | ❌ | | 20 | CONFIRMED | Payment confirmed successfully on-chain | ✅ | *** End of document. # API Doc - Checkout Intent Routes - Get Checkout Intent **AllScale Open API**\ **Version:** v5\ **Last updated:** 2026-05-06\ **Base Path:** `/v1/checkout_intents` *** ### Overview The Checkout Intent Query API allows merchants to retrieve the **full details** of a checkout intent. This API is used to: * Fetch complete checkout intent information by `checkout_intent_id` * Display order, user, and payment details * Inspect on-chain transaction metadata after payment * Debug or reconcile payment lifecycle issues *** ### Important Notes * All enum values are represented as **integers** in API requests and responses * Monetary values involving stable coins are returned as **strings** to preserve precision * This endpoint returns a **structured object** in `payload` * Permission checks are enforced at the **store/business** level *** ### Authentication All requests must include the following headers: | Header | Description | | ----------- | ------------------------- | | X-API-Key | API key | | X-Timestamp | Unix timestamp (seconds) | | X-Nonce | Unique request identifier | | X-Signature | HMAC signature | #### Notes * `X-Nonce` must be unique per request * `X-Timestamp` must be within the allowed time window * Signature must be generated using **raw request body bytes** * Requests are protected against replay attacks *** ### GET /v1/checkout\_intents/{checkout\_intent\_id} #### Description Retrieve the full checkout intent object, including payment configuration, order metadata, and on-chain transaction details (if available). *** #### Request ``` GET /v1/checkout_intents/{checkout_intent_id} ``` **Path Parameters** | Parameter | Type | Required | Description | | -------------------- | ------ | -------: | ---------------------------------------- | | checkout\_intent\_id | string | ✅ | AllScale checkout intent ObjectId string | **Headers** ``` X-API-Key: X-Timestamp: X-Nonce: X-Signature: v1= ``` > Note: This is a GET request, so there is no request body. *** ### Successful Response ```json { "code": 0, "payload": { "all_scale_checkout_intent_id": "65c9d4e5a9f4e0d2b6a1e123", "currency": 1, "currency_symbol": "USD", "amount_cents": 2500, "chain_id": 1, "amount_coins": "2.500000", "coin_symbol": "USDT", "coin_contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "currency_rate": "1.000000", "status": 20, "order_id": "order_8899", "order_description": "Premium subscription", "user_id": "user_001", "user_name": "Alice", "tx_hash": "0xabc123...", "tx_from": "0xSenderAddress", "tx_to": "0xReceiverAddress", "payment_method_type": 1, "actual_paid_amount": "2.500000", "net_income_amount": "2.400000", "service_fee_amount": "0.100000", "accepted_stable_coins": 1 }, "error": null, "request_id": "req_xxxxx" } ``` *** ### Response Fields #### Top-Level Fields | Field | Type | Description | | ----------- | -------------- | ---------------------- | | code | int | 0 indicates success | | payload | object | Checkout intent object | | error | object \| null | Error object | | request\_id | string | Request identifier | *** #### Payload — Checkout Intent Object | Field | Type | Description | | -------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | all\_scale\_checkout\_intent\_id | string | Checkout intent ID | | currency | int \| null | Fiat currency enum value. `null` when the intent was priced natively in a stable coin. | | currency\_symbol | string \| null | Fiat currency symbol (e.g. USD). `null` when the intent was priced natively in a stable coin. | | amount\_cents | int \| null | Amount in fiat cents. `null` when the intent was priced natively in a stable coin — the authoritative amount is `amount_coins`. | | chain\_id | int \| null | EIP-155 chain ID | | amount\_coins | string | Amount in stable coin | | coin\_symbol | string | Stable coin symbol (USDT / USDC) | | coin\_contract | string \| null | Stable coin contract address | | currency\_rate | string \| null | Fiat → stable coin conversion rate. `null` when the intent was priced natively in a stable coin (no FX occurred). | | status | int | Checkout intent status enum value | | order\_id | string \| null | Merchant order ID | | order\_description | string \| null | Merchant order description | | user\_id | string \| null | Merchant user ID | | user\_name | string \| null | Merchant user name | | error\_message | string \| null | Error message (if failed) | | tx\_hash | string \| null | On-chain transaction hash from the customer's wallet to the ephemeral wallet | | tx\_hash\_2 | string \| null | On-chain transaction hash of the second transfer, from the ephemeral wallet to the merchant's wallet | | tx\_from | string \| null | Customer's wallet address | | tx\_to | string | Merchant's AllScale wallet address | | actual\_paid\_amount | string \| null | Actual stablecoin amount paid by the user | | service\_fee\_amount | string \| null | AllScale service fee deducted from the payment amount | | net\_income\_amount | string \| null | Net stablecoin amount credited to the merchant. Calculated as `actual_paid_amount - service_fee_amount`. | | 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`. | | accepted\_stable\_coins | int \| null | StableCoinFlag bitmask of stablecoins the payer may settle in for this intent (`1` = USDT, `2` = USDC, `3` = either; bit `n` = StableCoin enum value `n+1`). `null` on intents created before the multi-coin rollout. | *** ### Possible Errors | Code | Meaning | | ----- | ------------------------------------------------------ | | 10001 | Validation error | | 20001 | Missing authentication headers | | 20002 | Invalid signature | | 30001 | Forbidden (no permission to view this checkout intent) | | 40001 | Rate limit exceeded | | 50001 | Checkout intent not found | | 90000 | Internal server error, pls contact us | | 99999 | Unknown error, pls contact us | *** ### Notes * This endpoint enforces **store/business ownership** checks * Enum fields (such as `currency` and `status`) are returned as **integers only** * Decimal values are returned as **strings** to avoid precision loss * Always log `request_id` when debugging production issues * If you only need the status value, prefer\ `GET /v1/checkout_intents/{checkout_intent_id}/status` for lower payload size *** ### Related APIs * `POST /v1/checkout_intents` * `GET /v1/checkout_intents/{checkout_intent_id}/status` *** ## Appendix — Checkout Intent Status Enum | **Value** | **Name** | **Meaning** | **Terminal** | | --------- | ---------------------- | ------------------------------------------------------ | ------------ | | -1 | FAILED | Checkout failed due to internal or processing error | ✅ | | -2 | REJECTED | Rejected by KYT (Know Your Transaction) checks | ✅ | | -3 | UNDERPAID | Paid amount is less than required | ✅ | | -4 | CANCELED | User manually canceled the checkout | ✅ | | -5 | TIMEOUT | Checkout expired due to inactivity or time limit | ✅ | | 1 | CREATED | Checkout intent created, not yet viewed by user | ❌ | | 2 | VIEWED | Hosted checkout page has been opened by the user | ❌ | | 3 | TEMP\_WALLET\_RECEIVED | Temporary deposit wallet assigned (KYT flow only) | ❌ | | 4 | MANUAL\_OPERATION | Stuck in TEMP\_WALLET\_RECEIVED; pending manual review | ❌ | | 5 | SEND\_BACK | Refund in progress back to payer (KYT or underpaid) | ❌ | | 10 | ON\_CHAIN | On-chain transaction detected, awaiting confirmation | ❌ | | 20 | CONFIRMED | Payment confirmed successfully on-chain | ✅ | *** End of document. # API Doc - Optional Response Signing AllScale Open API\ Version: v1\ Last updated: 2026-01-21 *** ## Overview **Applies only when `signed_response = true` for the store** *** AllScale supports optional response signing to allow clients to verify: * Response authenticity * Payload integrity * Request–response binding * Protection against replayed or substituted responses Response signing is **disabled by default**. It becomes active only when the store is created or configured with: ``` signed_response = true ``` *** ### When Response Signing Is Enabled When enabled, every API response includes additional headers that allow the client to verify the response cryptographically. *** ### Response Headers | Header | Required | Description | | -------------------- | ----------- | -------------------------------------------- | | X-Response-Timestamp | Yes | Unix timestamp (seconds) generated by server | | X-Response-Nonce | Yes | Unique nonce generated per response | | X-Response-Signature | Yes | HMAC signature of the response | | X-Request-Nonce | Recommended | Echo of request nonce | | X-Request-Id | Yes | Unique request identifier | *** ### Response Canonical String When `signed_response = true`, the response signature is computed using: ``` STATUS_CODE PATH REQUEST_NONCE REQUEST_BODY_SHA256 RESPONSE_TIMESTAMP RESPONSE_NONCE RESPONSE_BODY_SHA256 ``` Each field is joined using newline characters (`\n`). *** ### Field Definitions | Field | Description | | ---------------------- | ----------------------------------- | | STATUS\_CODE | HTTP status code (e.g. 200) | | PATH | Request path (e.g. /v1/payments) | | REQUEST\_NONCE | X-Nonce from the request | | REQUEST\_BODY\_SHA256 | SHA256 hash of raw request body | | RESPONSE\_TIMESTAMP | Server timestamp | | RESPONSE\_NONCE | Random nonce generated per response | | RESPONSE\_BODY\_SHA256 | SHA256 hash of raw response body | > ⚠️ Important: Hashes must be calculated using the exact raw request / response body bytes. *** ### Response Signature Algorithm **Algorithm** ``` HMAC-SHA256 ``` **Encoding** ``` Base64 ``` **Formula** ``` signature = Base64( HMAC_SHA256(api_secret, canonical_response_string) ) ``` **Header format** ``` X-Response-Signature: v1= ``` *** ### Response Example #### Response Headers ``` HTTP/1.1 200 OK X-Response-Timestamp: 1716501552 X-Response-Nonce: 8fae4c9d7e2b4b3aa1f2 X-Response-Signature: v1=dYlX5KQyZPzq2+7Gf+4... X-Request-Nonce: b4d9a2a1-9c2b-4df4-8b8e-2a13a45fd321 X-Request-Id: req_84f12a8d ``` #### Response Body ```json { "code": 0, "payload": { "pong": "ok" }, "error": null, "request_id": "req_84f12a8d" } ``` *** ### Client Verification Steps 1. Extract headers: * X-Response-Timestamp * X-Response-Nonce * X-Response-Signature * X-Request-Nonce 2. Compute: * REQUEST\_BODY\_SHA256 * RESPONSE\_BODY\_SHA256 3. Rebuild canonical string: ``` STATUS_CODE PATH REQUEST_NONCE REQUEST_BODY_SHA256 RESPONSE_TIMESTAMP RESPONSE_NONCE RESPONSE_BODY_SHA256 ``` 4. Compute: ```ini expected_signature = Base64(HMAC_SHA256(api_secret, canonical)) ``` 5. Compare: ```ini expected_signature = == X-Response-Signature ``` 6. Validate: * Timestamp within ±5 minutes * Response nonce not reused *** ### Postman Response Verification Script Place this in **Postman → Tests tab** ```javascript // ================================ // AllScale Response Signature Verify // ================================ const API_SECRET = (pm.environment.get("API_SECRET") || "").trim(); function sha256Hex(str) { return CryptoJS.SHA256(str || "").toString(CryptoJS.enc.Hex); } function hmacSha256Base64(key, msg) { const mac = CryptoJS.HmacSHA256(msg, key); return CryptoJS.enc.Base64.stringify(mac); } function getHeader(name) { return pm.response.headers.get(name) || ""; } pm.test("API_SECRET is set", function () { pm.expect(API_SECRET).to.not.eql(""); }); // ---- request-side values ---- const path = pm.request.url.getPath(); const requestNonce = pm.request.headers.get("X-Nonce") || ""; const requestBodyRaw = pm.request.body?.raw || ""; const requestBodySha = sha256Hex(requestBodyRaw); // ---- response-side values ---- const statusCode = pm.response.code; const responseTimestamp = getHeader("X-Response-Timestamp"); const responseNonce = getHeader("X-Response-Nonce"); const responseSigHeader = getHeader("X-Response-Signature"); const echoedRequestNonce = getHeader("X-Request-Nonce"); // ---- sanity checks ---- pm.test("Response signing headers present", function () { pm.expect(responseTimestamp).to.not.eql(""); pm.expect(responseNonce).to.not.eql(""); pm.expect(responseSigHeader).to.match(/^v1=.+/); }); // ---- timestamp check ---- pm.test("Response timestamp within ±5 minutes", function () { const now = Math.floor(Date.now() / 1000); const ts = parseInt(responseTimestamp, 10); pm.expect(Math.abs(now - ts)).to.be.below(300); }); // ---- response body hash ---- const responseBody = pm.response.text() || ""; const responseBodySha = sha256Hex(responseBody); // ---- canonical string ---- const canonical = [ String(statusCode), path, echoedRequestNonce || requestNonce, requestBodySha, String(responseTimestamp), responseNonce, responseBodySha, ].join("\n"); // ---- signature verification ---- const expectedSig = "v1=" + hmacSha256Base64(API_SECRET, canonical); pm.test("Response signature matches", function () { pm.expect(responseSigHeader).to.eql(expectedSig); }); // ---- optional replay protection ---- pm.test("Response nonce not replayed", function () { const key = "RESP_NONCE_CACHE"; const ttl = 600; const now = Math.floor(Date.now() / 1000); let cache = []; try { cache = JSON.parse(pm.environment.get(key) || "[]"); } catch { } cache = cache.filter(x => now - x.ts < ttl); pm.expect(cache.some(x => x.nonce === responseNonce)).to.eql(false); cache.push({nonce: responseNonce, ts: now}); pm.environment.set(key, JSON.stringify(cache)); }); ``` *** ### Replay Protection Responses are protected using: * Timestamp validation (±5 minutes) * Unique response nonce * Request–response binding via request nonce * Optional nonce replay cache on client side *** ### Error Handling Even error responses are signed. Example: ```json { "code": 20002, "payload": null, "error": { "message": "Bad signature", "details": { "reason": "signature_mismatch" } }, "request_id": "req_xxx" } ``` Clients must still verify the response signature before trusting the error. *** ### Important Notes #### ✔ When Response Signing Is Enabled * Client must verify signature * Client must validate timestamp * Client should cache nonces * Client must reject mismatched responses #### ✔ When Response Signing Is Disabled * No `X-Response-*` headers are returned * Client should skip verification * Suitable for: * Internal testing * Low-risk integrations * Legacy compatibility *** ### Best Practices * Always verify response signature before processing data * Cache response nonces for at least 5 minutes * Reject responses with invalid timestamps * Use raw response body for hashing * Log request\_id for debugging * Never disable verification in production *** End of document. # API Doc - Claim Link Routes - Create Auto-Payout **AllScale Open API**\ **Version:** v1\ **Last updated:** 2026-07-21\ **Base Path:** `/v1/claim_link_auto_payouts` *** ### Overview The Claim Link Auto-Payout API lets a merchant create a **single claim link and fund it automatically in one call** — no on-chain deposit step for the merchant. AllScale creates the link, then funds its pool wallet from the merchant's own custodied (Turnkey) wallet using a small-amount **passwordless** signing session, and returns the bearer claim URL. Use this endpoint to: * Create one claim link for a recipient (payout / disbursement) * Have AllScale fund it automatically from your custodied wallet (no manual deposit) * Get back a shareable **claim URL** (and the one-time bearer `token`) to deliver to the recipient * Make the call **idempotent** with a `reference_id` (**always required**) > The recipient later opens the claim URL to claim the funds. For the sender-funded flow where you deposit on-chain yourself, see the standard claim-link create (dashboard/GraphQL) or the Batch API. *** ### Availability & Prerequisites This endpoint is **deploy-flag gated** and **per-merchant authorized**. All of the following must hold (1–2 fail with `50104`, 3 fails with `30002` — both HTTP 403): 1. **Live signing is enabled** on the environment (`CLAIM_LINK_LIVE_SIGNING_ENABLED`). It is enabled on **gamma (staging)** and gated off on production until launch. 2. Your API key is a **production (non-sandbox)** key. Sandbox keys are rejected. 3. Your store has been granted the **`claim_link:auto_payout`** scope. This scope is provisioned only after your business completes the auto-payout **onboarding** (creating a Turnkey session user + amount-limit policy). The `*` wildcard scope does **not** grant it. Funding is capped per session by the amount-limit policy set during onboarding; a request over the cap is rejected by the signing policy. *** ### Important Design Notes * All enum values (`stable_coin`, `chain`) are **integers** in requests and responses. * `amount` is sent and returned as a **string** to preserve exact decimal precision — never a JSON number. * Settlement stable coins: **USDT (`1`)** and **USDC (`2`)**. * Chains: **EVM chains only** — Ethereum (`1`), Base (`5`), BNB (`6`), Arbitrum (`7`), Polygon (`8`), Optimism (`9`); Sepolia testnet (`11`) is additionally accepted on test environments. * The call is **synchronous**: it creates the link and blocks until the funding transaction settles (≈ up to \~90s), then returns the funded link. *** ### Authentication All requests must include the following headers (see the **Auth** doc for the full canonical-request + signing scheme): | Header | Description | | ----------- | ------------------------- | | X-API-Key | API key | | X-Timestamp | Unix timestamp (seconds) | | X-Nonce | Unique request identifier | | X-Signature | HMAC signature `v1=` | #### Notes * `X-Nonce` must be unique per request; `X-Timestamp` must be within the allowed window. * The signature is computed over the **raw request body bytes**. * Requests are protected against replay attacks. *** ### POST /v1/claim\_link\_auto\_payouts #### Description Create a claim link and auto-fund it from the merchant's custodied wallet. Returns the created (and funded) link, including the bearer claim URL. *** #### Request `POST /v1/claim_link_auto_payouts` **Headers** ``` X-API-Key: X-Timestamp: X-Nonce: X-Signature: v1= Content-Type: application/json ``` **Body Example** ```json { "amount": "10.50", "stable_coin": 1, "chain": 5, "receiver_email": "recipient@example.com", "sender_display_name": "Acme Payouts", "sender_message": "Your July payout", "reference_id": "payout_2026_07_0001" } ``` **Request Fields** | Field | Type | Required | Description | | --------------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | amount | string | ✅ | The recipient's claimable amount in **token units** (e.g. `"10.50"` = 10.50 USDT). Must be a finite, positive decimal and no finer than the token's on-chain decimals. | | stable\_coin | int | ✅ | Stable coin enum: `1` = USDT, `2` = USDC. | | chain | int | ✅ | Chain enum (EVM only): `1` ETH, `5` Base, `6` BNB, `7` Arbitrum, `8` Polygon, `9` Optimism. | | receiver\_email | string \| null | ❌ | Recorded on the link so the sender can see who it was meant for. **AllScale does not email the recipient** — you deliver the `claim_url` yourself. Max 254 chars. | | sender\_display\_name | string \| null | ❌ | Shown to the recipient as the sender. Max 100 chars. | | sender\_message | string \| null | ❌ | A short note shown to the recipient. Max 500 chars. | | reference\_id | string | ✅ | Your idempotency key. 1–128 printable ASCII (no spaces/control chars). **Always required** — a missing or blank value is rejected with `10001`. Re-sending the **same** `reference_id` returns the original link instead of creating a new one. | ⚠️ **Important** * `amount` must be **> 0** and match the token's on-chain precision **for the selected chain** (e.g. USDT/USDC allow 6 decimals on most chains, but 18 on BNB). An over-precise amount is rejected with `10001`. * `stable_coin` and `chain` are **integers**, not strings (`"USDT"` / `"BASE"` will be rejected). * `reference_id` is **always required** — it is the idempotency key that makes retries safe, and there is no opt-out. Because this call is **synchronous** (it blocks up to \~90s for the funding receipt), a client timeout + retry is the likeliest failure path, and the stable `reference_id` is exactly what stops that retry creating a **second** link and a **second** debit. A missing or blank `reference_id` is rejected with `10001`. *** #### Successful Response ```json { "code": 0, "payload": { "claim_link_id": "665b2f3d0d2d9c0a1b2c3d4e", "reference_id": "payout_2026_07_0001", "amount": "10.50", "token_symbol": "USDT", "chain_id": 8453, "status": "pending_deposit", "token": "clk_live_9f8a...c1", "claim_url": "https://claim.allscale.io/clk_live_9f8a...c1", "funding_tx_hash": "0xabc...def", "funded_amount": "10.50", "idempotent_hit": false }, "error": null, "request_id": "req_xxxxx" } ``` **Response Fields** | Field | Type | Description | | ------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | code | int | `0` indicates success. | | payload.claim\_link\_id | string | AllScale claim link id. | | payload.reference\_id | string \| null | Your reference id, echoed back. | | payload.amount | string | The claimable amount (token units). | | payload.token\_symbol | string | Stable coin symbol, e.g. `USDT`. | | payload.chain\_id | int | EIP-155 chain id of the funding/payout chain (e.g. `8453` for Base). | | payload.status | string | Link lifecycle status. After a successful auto-fund the link is funding-confirmed by the scanner shortly after. | | payload.token | string \| null | **Bearer claim token — returned once; treat as a secret.** Anyone with it can claim. **Always `null` on an idempotent replay** (as are `funding_tx_hash` and `funded_amount`); only `claim_url` is rebuilt. | | payload.claim\_url | string \| null | The shareable claim URL to deliver to the recipient (rebuilt from the token). | | payload.funding\_tx\_hash | string \| null | The on-chain funding transaction hash (present when this call funded the link). | | payload.funded\_amount | string \| null | The **principal** amount (USD-normalized) funded into the pool wallet by this call. Fees are settled separately and are **not** included here. `null` on an idempotent replay. | | payload.idempotent\_hit | bool | `true` when this call matched a prior `reference_id` and returned the existing link instead of creating a new one. | | error | object \| null | Error object (`null` on success). | | request\_id | string | Request identifier (echo it in support requests). | *** #### Error Response — funding/signing failure (`50103`) A create that fails at the funding stage returns `50103`, and `error.details` carries the underlying AllScale code (`plutus_code`) plus a human-readable `reason` telling you what to do next: ```json { "code": 50103, "payload": null, "error": { "message": "Claim link auto-payout create failed.", "details": { "reason": "The auto-payout authorization session has expired. Please re-authorize the merchant auto-payout session and retry.", "reason_code": "session_expired", "plutus_code": 8148 } }, "request_id": "req_xxxxx" } ``` **`plutus_code: 8148` — the payout could not be signed.** No funds moved: 8148 is always raised *before* broadcast, and the reserved budget is released, so your used-percentage is unaffected. All 8148s share the one code — the machine-readable **`reason_code`** tells the three cases apart: | `reason_code` | What happened | What to do | | ----------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session_expired` | Your auto-payout session lapsed, or none is provisioned. | Re-authorize the merchant auto-payout session, then retry. | | `policy_denied` | Your wallet policy declined the signature. | Check the request against the policy's limits (including the per-transaction amount ceiling) and that the policy is still verified for this wallet; re-authorize the policy if needed, then retry. | | `signer_error` | A temporary signer/infrastructure fault, or an authorization that completed concurrently. | Retry with the **same `reference_id`**. Contact support if it persists. | > **A policy rejection does not necessarily mean the amount was too high.** The wallet policy checks several things at once — the chain and verifying contract, the token, the sponsor, **and** the per-transaction amount ceiling — and the signer reports one rejected result without saying which check failed. So lowering the amount will not help if some other part of the policy was the cause; re-verify the policy as well. > **Retrying an 8148 is safe.** Nothing was signed or broadcast and the budget reservation is released, so re-sending the request with the **same `reference_id`** cannot double-pay: the endpoint is idempotent per `(business, store, reference_id)` and `reference_id` is always required. Always retry with the original `reference_id` — never mint a new one for a retry, which would be a genuinely new payout. > `reason` is human-readable guidance and its **exact wording may change** — do not match on the literal string. Branch on `code` / `plutus_code` / **`reason_code`** (a stable machine-readable category: `session_expired`, `policy_denied`, or `signer_error`), and surface `reason` (plus `request_id`) to whoever operates the integration. `reason_code` is present only when the failure maps to one of these categories. *** ### Possible Errors | Code | HTTP | Meaning | | ----- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 10001 | 400 / 422 | Validation error — missing/invalid `amount`, over-precision, missing/blank `reference_id` (always required), bad `reference_id`, or unsupported coin. Malformed JSON or wrong field types are returned as **422**. | | 20001 | 401 | Missing authentication headers. | | 20002 | 401 | Invalid signature. | | 30001 | 403 | Forbidden (client IP not in the store allowlist). | | 30002 | 403 | Scope forbidden — the store lacks the `claim_link:auto_payout` scope. | | 40001 | 429 | Rate limit exceeded. | | 50103 | 400 | Create/auto-fund error (e.g. insufficient wallet balance, session/policy not ready, signing gate). See `error.details.plutus_code`, `error.details.reason`, and `error.details.reason_code` — for `plutus_code: 8148` (signing failure) `reason_code` distinguishes `session_expired` / `policy_denied` / `signer_error`. | | 50104 | 403 | Auto-payout API disabled — live signing off for this environment, or a sandbox key was used. | | 50105 | 409 | Duplicate `reference_id` mid-flight — a concurrent create for the same reference is in progress. | | 50106 | 409 | `reference_id` reused with **different parameters** (chain / coin / amount). `error.details` carries the `reference_id`, the `existing` params, and the `request` params — resend the original params, or use a new `reference_id` for a genuinely new payout. | > This table lists the errors specific to this endpoint. Unexpected server-side failures may return a generic platform error code (e.g. `90000` / `99999`) with HTTP 500 — treat **any** non-zero `code` as a failure and surface `error` + `request_id` for support. *** ### Notes * **Deliver the `claim_url` (or `token`) to your recipient over a secure channel.** The token is a bearer credential shown **once**. * The endpoint is **idempotent per `(business, store, reference_id)`** — uniqueness is scoped to the **authenticating store**, not the whole business, so a business running several stores (each with its own API key) can reuse the same `reference_id` in different stores. A retry with the same `reference_id` **on the same store and the same (chain, coin, amount)** returns the original link (with `idempotent_hit: true`) — it never double-creates or double-debits. Reusing the reference with **different** parameters is rejected with `50106` (409), not replayed. * Funding draws from **your** custodied (Turnkey) wallet; ensure it holds enough of the stable coin to cover the payout **amount plus fees**. Funding is **gasless / sponsored** — you do **not** need to hold native gas in that wallet. A balance shortfall returns `50103`. * This endpoint is currently **live on gamma (staging)** and gated off on production until the launch flag is flipped. # API Doc - Claim Link Webhook **AllScale Open API**\ **Version:** v4\ **Last Updated:** 2026-07-15 *** ### Overview When a **Claim Link** reaches a terminal state **and the corresponding on-chain settlement succeeds**, AllScale POSTs a notification to your configured webhook endpoint. This lets your backend react to a claim, an expiry/refund, or a sender cancellation/refund without polling. There are exactly **three terminal events**: | `event` | Emitted when | | ----------- | ------------------------------------------------------------------------------------------------------------------- | | `claimed` | The recipient claimed the link **and** the payout transaction was persisted on-chain. | | `expired` | The link expired unclaimed **and** the refund transaction succeeded on-chain. | | `cancelled` | The **sender cancelled** (claimed back) a funded, unclaimed link **and** the refund transaction succeeded on-chain. | > ⚠️ **`cancelled` is new.** Earlier versions of this document stated that there is **no** `cancelled` event — that is **no longer true**. Sender cancel / claim-back is live (see the Cancel (Claim-Back) API), and its refund settles through the same path as an expiry refund, so it emits the same payload shape with `refund_tx_hash` set. **If your handler was written against the old two-event contract, it must now tolerate a third `event` value** — do not treat an unknown event as an error. > > **The callback fires after on-chain settlement, not on the status change alone.** A link whose status becomes expired or cancelled does **not** emit its event until the refund succeeds — if a refund is still pending or has failed, no callback is sent (yet). Do not treat "status = cancelled" as equivalent to "a `cancelled` webhook will arrive"; reconcile via the Claim Link status API for the authoritative state. The claim webhook reuses the **same HMAC-SHA256 request-signing scheme** as every other AllScale webhook — see Webhook Callback Signing & Payload Guide for the canonical-string construction, header definitions, and verification flow. This document covers only what is **specific to the Claim Link webhook**: which links emit it, the payload shape, and the delivery/retry behavior. *** ### Which links emit a webhook A callback is sent **only** when a webhook URL is configured for the link: | Link type | Webhook URL source | Payload identifier | Events | | ---------------------------------------------- | -------------------------------------- | ------------------ | --------------------------------- | | **Batch-created links** | `webhook_url` on the batch | `batch_id` | `claimed`, `expired` | | **Merchant single-create (auto-payout) links** | `claim_link_webhook_url` on your store | `store_id` | `claimed`, `expired`, `cancelled` | | In-app single links | — (never emit) | — | — | Exactly **one** of `batch_id` / `store_id` is populated in each payload, identifying how the link was created. The store-level `claim_link_webhook_url` must be an **`https://`** URL (plain `http://` is accepted only in the sandbox environment). > **`cancelled` only ever carries `store_id`.** A batch sub-link cannot be cancelled individually (its funds are pooled and returned through the batch's aggregate refund flow), so a `cancelled` event is never emitted for a batch link — `batch_id` is always `null` on a `cancelled` payload. The callback is signed with the **same store credentials** (`api_key` + `api_secret`) that authenticated the create request — i.e. the store that owns the batch or the single-create link. *** ### Webhook Request #### Method ```http POST ``` #### Content-Type ```http application/json ``` #### Required Headers Identical to all AllScale webhooks (see the signing guide): | Header | Description | | ------------------- | ------------------------------ | | X-API-Key | Your store's API key | | X-Webhook-Id | Unique webhook ID (dedupe key) | | X-Webhook-Timestamp | Unix timestamp (seconds) | | X-Webhook-Nonce | Unique per-request nonce | | X-Webhook-Signature | `v1=` | The signature is computed over the canonical string `allscale:webhook:v1\nPOST\n\n\n\n\n\n`, signed with your `api_secret`. **Always verify the signature against the raw request-body bytes before parsing the JSON.** *** ## Webhook Payload The request body is **exactly** the following JSON structure. All money values are **decimal strings in token units** (never floats). ### JSON Field Definitions | Field | Type | Required | Description | | ---------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | webhook\_id | string | ✅ | Unique webhook ID; must match `X-Webhook-Id`. Use it for idempotency (see below). | | event | string | ✅ | `"claimed"`, `"expired"`, or `"cancelled"`. Tolerate unknown values — new terminal events may be added. | | claim\_link\_id | string | ✅ | The Claim Link this event is about. | | occurred\_at | string | ✅ | Time AllScale **generated this callback**, ISO-8601 UTC with `Z` suffix (e.g. `"2026-07-14T03:21:07Z"`). This is the enqueue time, not the exact on-chain event time — on a retry or catch-up re-delivery it can be later than the actual claim/refund. For the precise on-chain moment, use the transaction hash. | | amount | string | ✅ | Claim/refund amount as a **decimal string** in token units (e.g. `"12.50"`). | | token\_symbol | string | ✅ | Stablecoin symbol, e.g. `"USDT"` / `"USDC"`. | | batch\_id | string \| null | ➖ | Set for batch-created links; `null` otherwise. Exactly one of `batch_id` / `store_id` is non-null. | | store\_id | string \| null | ➖ | Set for merchant single-create (auto-payout) links; `null` otherwise. | | reference\_id | string \| null | ➖ | Your per-link reference id, if one was supplied at create time; `null` otherwise. | | claim\_tx\_hash | string \| null | ➖ | On-chain payout tx hash. Set when `event = "claimed"`; `null` for `expired` / `cancelled`. | | refund\_tx\_hash | string \| null | ➖ | On-chain refund tx hash. Set when `event = "expired"` **or** `"cancelled"` (both settle via a refund); `null` for `claimed`. | > **Null keys are always present.** Fields that do not apply to a given event/link type are serialized as `null` (not omitted). Your parser should tolerate `null` for every optional field above. The HMAC covers the exact bytes sent, so do not re-serialize before verifying. ### Example — `claimed` (merchant single-create link) ```json { "webhook_id": "a3f8c1e2-...-uuid5", "event": "claimed", "claim_link_id": "clk_9f2b", "occurred_at": "2026-07-14T03:21:07Z", "amount": "12.50", "token_symbol": "USDT", "batch_id": null, "store_id": "store_001", "reference_id": "order_8899", "claim_tx_hash": "0xabc...", "refund_tx_hash": null } ``` ### Example — `expired` (batch-created link) ```json { "webhook_id": "b7d4e0a1-...-uuid5", "event": "expired", "claim_link_id": "clk_1a04", "occurred_at": "2026-07-21T00:00:00Z", "amount": "12.50", "token_symbol": "USDT", "batch_id": "batch_2025_q3", "store_id": null, "reference_id": null, "claim_tx_hash": null, "refund_tx_hash": "0xdef..." } ``` ### Example — `cancelled` (merchant single-create link) Emitted after you called the Cancel (Claim-Back) API and the refund settled on-chain. Note `batch_id` is always `null` here, and `refund_tx_hash` is set exactly as for `expired`. ```json { "webhook_id": "c2e9f5b3-...-uuid5", "event": "cancelled", "claim_link_id": "clk_9f2b", "occurred_at": "2026-07-15T09:14:22Z", "amount": "12.50", "token_symbol": "USDT", "batch_id": null, "store_id": "store_001", "reference_id": "order_8899", "claim_tx_hash": null, "refund_tx_hash": "0x123..." } ``` *** ### Idempotency & Dedupe `webhook_id` is **stable and deterministic** for a given `(claim_link_id, event)` pair — every retry and every at-least-once re-delivery of the same event carries the **same** `webhook_id`. * Treat `webhook_id` as the dedupe key: record processed IDs and ignore repeats. * Because delivery is **at-least-once**, you **will** occasionally receive the same event more than once (e.g. after a retry or a catch-up sweep). Idempotent handling is required. *** ### Delivery & Retry Behavior * **At-least-once, best-effort.** The first delivery attempt is synchronous; on any non-`200` response (or timeout / connection error) AllScale schedules **up to 35** exponential-backoff retries. * **Retry window.** Backoff grows (\~5s, 10s, 20s, 40s, 80s) then caps at 120s per attempt, giving a real delivery window of roughly **30 minutes (with jitter) up to \~1 hour** — enough to survive a brief outage or deploy on your side. * **No replay after exhaustion.** Once the retries are exhausted the job is dead-lettered and **not** re-delivered by any drain/replay mechanism. If your endpoint is down for longer than the retry window, you will miss that callback — reconcile via the Claim Link status API rather than relying solely on the webhook. * **Missed-`expired` catch-up.** For **batch** links, AllScale runs a catch-up sweep that re-enqueues `expired` webhooks that were missed within the last **7 days**. This is an additional at-least-once path (hence the dedupe requirement above); it does **not** cover the `claimed` or `cancelled` events, nor store single-create links. Because `cancelled` is store single-create only, it has **no** catch-up path — if your endpoint is down past the retry window you will miss it, so reconcile rather than relying on the callback alone. * **Request timeout.** Each attempt uses a **5-second** timeout; respond quickly (return `200` and process asynchronously if needed). *** ### Response Expectations Your endpoint should return: * `200 OK` — the callback is considered delivered; no retry. * Any non-`200` — treated as a failure; the callback is retried per the policy above. *** ### Best Practices ✅ Verify `X-Webhook-Signature` against the **raw body bytes** before processing\ ✅ Dedupe on `webhook_id` — you will receive duplicates\ ✅ Branch on `event` (`claimed` / `expired` / `cancelled`) and read the matching `*_tx_hash` (`claim_tx_hash` for `claimed`, `refund_tx_hash` for `expired` and `cancelled`)\ ✅ Treat an **unrecognized** `event` as a no-op you ack with `200`, not as an error — new terminal events may be added (as `cancelled` was)\ ✅ Parse `amount` with a Decimal type, not a float\ ✅ Return `200` fast; do heavy work asynchronously\ ✅ Reconcile against the Claim Link status API for anything longer than the \~1h retry window\ ❌ Never log `api_secret` or signatures *** End of Document # Quickstart with Postman Out-of-the-box Postman assets for QA and partner engineers. Import, fill in credentials, and you can hit every documented v1 endpoint with valid HMAC-signed requests. ### Files | File | What it is | | ------------------------------------------------------ | -------------------------------------------------------------------------------------- | | `AllScale_OpenAPI.postman_collection.json` | Collection — all v1 endpoints + collection-level request signer + response assertions. | | `AllScale_OpenAPI_Production.postman_environment.json` | Production environment (`https://openapi.allscale.io`). | ### Import (Postman desktop or web) 1. **File → Import** → drop all three JSON files in at once. 2. Top-right environment dropdown → pick **AllScale OpenAPI** 3. Open the environment, paste your `api_key` and `api_secret`, save. * `api_secret` is stored with Postman's `secret` type and is masked. * Both values are shown **once** in the merchant dashboard — keep them safe. `base_url` and `checkout_intent_id` are already wired up; you should not need to edit them. ### Suggested run order 1. **Test / GET `/v1/test/ping`** — confirms keys + clock + signing. 2. **Test / POST `/v1/test/post`** — confirms body hashing. 3. **Checkout Intent / Create — fiat** *or* **Create — native stable-coin** — creates an intent and auto-saves `checkout_intent_id` into the environment. * Fiat: send `currency` (IntEnum). Server FX-converts to the resolved settlement coin (USDT or USDC); use `accepted_stable_coins` to pick which (first entry wins; defaults to USDT when omitted). * Native stable-coin: send `stable_coin` — `1` (USDT) or `2` (USDC) are both accepted. `amount_cents` is stable-coin cents, no FX, and `currency_rate` will be `null`. * Send exactly one — both or neither returns `10001`. 4. **Checkout Intent / GET `/v1/checkout_intents/{id}/status`** — polls the lifecycle state. 5. **Checkout Intent / GET `/v1/checkout_intents/{id}`** — full detail. * For a native-stable-coin intent, the fiat fields (`currency`, `currency_symbol`, `amount_cents`, `currency_rate`) will be `null`; the authoritative amount lives in `amount_coins`. You can also run the whole collection with Postman's **Collection Runner** — every request has assertions attached, so the runner report is a usable QA smoke-test. ### How signing works (for the curious) A pre-request script lives at the **collection root**, so it runs before every request without per-request setup. For each call it: 1. Reads `api_key` / `api_secret` from the active environment. 2. Builds the canonical string `METHOD\nPATH\nQUERY\nTIMESTAMP\nNONCE\nBODY_SHA256` (body hash = `sha256_hex(raw_body_bytes)`; empty body hashes the empty string). 3. Signs it with HMAC-SHA256, base64-encoded. 4. Upserts the required headers: `X-API-Key`, `X-Timestamp`, `X-Nonce`, `X-Signature: v1=`. No need to touch the script for normal QA — but if a signature ever looks wrong, uncomment the two `console.log` lines at the bottom of the pre-request script to dump the canonical string and produced signature to the Postman console. ### Troubleshooting | Symptom | Likely cause | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `20001 missing_headers` | `api_key` / `api_secret` not set in the active environment. | | `20002 timestamp_out_of_window` | Your machine's clock is off; sync NTP (±5 min window). | | `20002 signature_mismatch` on POSTs only | Body was edited after the script ran, or Content-Type isn't `application/json`. Re-send; the script re-hashes on every send. | | `20002 replay_nonce` | Sending two requests with the same nonce within the replay window. The script generates a new UUID every send, so this should not happen — double-check you don't have the script disabled. | | `30001 ip_not_allowed` | Your egress IP isn't on the merchant IP allowlist. | | `40001` | Rate limited. Back off per the `retry_after` in the error details. | | `50001` | `checkout_intent_id` is unset or belongs to another merchant. Re-run **Create** to capture a fresh id. | | `50002` | `Create` rejected the request (e.g. `amount must be greater than 0.1 ` when the order is at or below the 0.1-coin floor). Read `error.details.reason` for the specifics. | ### Updating the package When endpoints change, edit `AllScale_OpenAPI.postman_collection.json` in this repo, then re-export the matching `.json` from Postman — or just keep editing JSON directly. Try to keep the canonical-string script in sync with `thirdparty_api/auth/__init__.py::_canonical_request`; they must produce byte-identical canonical strings. # AllScale\_OpenAPI.postman\_collection.json ``` { "info": { "_postman_id": "a11sc4le-0pen-4p1-0000-000000000001", "name": "AllScale OpenAPI (v1)", "description": "Ready-to-use Postman collection for AllScale's third-party OpenAPI.\n\n_Aligned with docs/openapi (Create v4 / Get v5 / Get-Status v2 — 2026-05-06)._\n\n**Setup**\n\n1. Import this collection **and** the companion environment file (`AllScale_OpenAPI.postman_environment.json`).\n2. Pick the environment (top-right dropdown).\n3. Fill in `api_key` and `api_secret` (shown once in the merchant dashboard — store them in the environment, not the collection).\n4. `base_url` defaults to the **sandbox** host; switch to the production host when ready.\n\n**How signing works**\n\nThe collection has a pre-request script at the root that runs before every request. It:\n\n- Reads `api_key` / `api_secret` from the active environment\n- Builds the canonical string `METHOD\\nPATH\\nQUERY\\nTIMESTAMP\\nNONCE\\nBODY_SHA256`\n- Signs it with HMAC-SHA256 + Base64\n- Upserts `X-API-Key`, `X-Timestamp`, `X-Nonce`, `X-Signature: v1=` headers\n\nYou should not need to touch the script for normal QA usage — just run a request.\n\n**Ordered happy-path**\n\n1. `Test / GET /v1/test/ping` — confirms connectivity + signing.\n2. `Test / POST /v1/test/post` — confirms body hashing.\n3. `Checkout Intent / Create — fiat` (or `Create — native stable-coin`) — creates an intent and auto-captures `checkout_intent_id` into the environment.\n4. `Checkout Intent / GET /v1/checkout_intents/{id}/status` — polls status.\n5. `Checkout Intent / GET /v1/checkout_intents/{id}` — full payload.\n\n**Pricing modes on Create** (pick exactly one per request):\n\n- `currency` (fiat IntEnum, Appendix A) → server FX-converts to the resolved settlement coin (USDT or USDC); use `accepted_stable_coins` to pick which.\n- `stable_coin` (IntEnum, Appendix B) → `1` (USDT) and `2` (USDC) are accepted; amount is stable-coin cents, no FX.\n\nSending both, or neither, returns `10001`.\n\n**Settlement:** USDT or USDC. `stable_coin_type` in the response matches the resolved coin (defaults to `1` USDT when neither `stable_coin` nor `accepted_stable_coins` is set).\n\n**Error codes** (from the server's unified envelope):\n\n| Code | Meaning |\n|-------|---------|\n| 0 | Success |\n| 10001 | Validation error |\n| 20001 | Missing auth headers |\n| 20002 | Bad signature |\n| 30001 | Forbidden (IP / ownership) |\n| 40001 | Rate limit exceeded |\n| 50001 | Checkout intent not found |\n| 50002 | Create checkout intent error (e.g. amount at or below the 0.1-coin floor) |\n| 90000 | Internal server error |\n", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "noauth" }, "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// AllScale HMAC-SHA256 request signing.", "// See docs/openapi/docs/API Doc - Auth.md for the canonical-string format.", "", "const apiKey = pm.environment.get('api_key') || pm.collectionVariables.get('api_key') || '';", "const apiSecret = (pm.environment.get('api_secret') || pm.collectionVariables.get('api_secret') || '').trim();", "", "if (!apiKey || !apiSecret) {", " console.warn('[AllScale] api_key or api_secret is empty — requests will be rejected (20001/20002).');", "}", "", "// Method", "const method = (pm.request.method || 'GET').toUpperCase();", "", "// Path — resolve {{var}} placeholders and :path params via pm.variables.replaceIn.", "const urlObj = pm.request.url;", "const rawPathSegments = (urlObj.path || []).map(function (seg) {", " return pm.variables.replaceIn(String(seg));", "});", "let path = '/' + rawPathSegments.join('/');", "// Postman treats a trailing slash in the URL as an empty segment; keep it so the canonical path", "// matches what Starlette sees on the server (e.g. /v1/checkout_intents/).", "", "// Query — use Postman's resolved query string so encoding matches what actually goes on the wire.", "let query = '';", "try {", " query = urlObj.getQueryString({ ignoreDisabled: true }) || '';", "} catch (e) {", " // Older Postman runtimes — fall back to manual build.", " const parts = [];", " (urlObj.query || []).each(function (q) {", " if (q.disabled) return;", " const k = pm.variables.replaceIn(q.key || '');", " const v = pm.variables.replaceIn(q.value || '');", " parts.push(k + '=' + v);", " });", " query = parts.join('&');", "}", "", "// Body — only raw JSON bodies are signed with content. Other modes sign an empty body.", "let body = '';", "if (pm.request.body && pm.request.body.mode === 'raw' && pm.request.body.raw) {", " body = pm.variables.replaceIn(pm.request.body.raw);", "}", "", "// Canonical pieces", "const bodyHash = CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);", "const timestamp = Math.floor(Date.now() / 1000).toString();", "", "function uuidv4() {", " if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {", " return crypto.randomUUID();", " }", " // RFC 4122 v4 fallback", " return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {", " const r = Math.random() * 16 | 0;", " const v = c === 'x' ? r : (r & 0x3 | 0x8);", " return v.toString(16);", " });", "}", "const nonce = uuidv4();", "", "const canonical = [method, path, query, timestamp, nonce, bodyHash].join('\\n');", "const signature = CryptoJS.HmacSHA256(canonical, apiSecret).toString(CryptoJS.enc.Base64);", "", "pm.request.headers.upsert({ key: 'X-API-Key', value: apiKey });", "pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });", "pm.request.headers.upsert({ key: 'X-Nonce', value: nonce });", "pm.request.headers.upsert({ key: 'X-Signature', value: 'v1=' + signature });", "", "// Uncomment for debugging:", "// console.log('[AllScale canonical]\\n' + canonical);", "// console.log('[AllScale signature] v1=' + signature);", "" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Collection-wide sanity checks.", "pm.test('Response is JSON', function () {", " pm.response.to.be.withBody;", " pm.response.to.be.json;", "});", "", "pm.test('Envelope has `code` and `request_id`', function () {", " const body = pm.response.json();", " pm.expect(body).to.have.property('code');", " pm.expect(body).to.have.property('request_id');", "});", "" ] } } ], "variable": [ { "key": "base_url", "value": "{{base_url}}", "type": "string" } ], "item": [ { "name": "Test", "description": "Smoke-test endpoints. Run these first to validate credentials, signing, and body hashing before touching real payment flows.", "item": [ { "name": "GET /v1/test/ping", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/test/ping", "host": ["{{base_url}}"], "path": ["v1", "test", "ping"] }, "description": "Health-check. Verifies that:\n\n- `api_key` / `api_secret` are valid\n- Your clock is in sync (±5 min window)\n- The signing pre-request script is producing a correct signature\n\nExpected: `{ \"code\": 0, \"payload\": { \"pong\": \"ok\" }, ... }`" }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('code == 0', function () {", " pm.expect(pm.response.json().code).to.eql(0);", "});", "pm.test('payload.pong == \"ok\"', function () {", " pm.expect(pm.response.json().payload.pong).to.eql('ok');", "});" ] } } ] }, { "name": "GET /v1/test/fail", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/test/fail", "host": ["{{base_url}}"], "path": ["v1", "test", "fail"] }, "description": "Always returns `10001 Validation error`. Use it to verify your error-handling branch parses the envelope correctly." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('code == 10001 (validation error)', function () {", " pm.expect(pm.response.json().code).to.eql(10001);", "});" ] } } ] }, { "name": "POST /v1/test/post", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"everything\": \"is_fine\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/test/post", "host": ["{{base_url}}"], "path": ["v1", "test", "post"] }, "description": "Echo endpoint. Verifies body-hash signing — if this passes but real endpoints return `20002`, the client almost certainly isn't hashing the body the same way the server does.\n\nThe server echoes the body back under `payload.your_request_body`." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('code == 0', function () {", " pm.expect(pm.response.json().code).to.eql(0);", "});", "pm.test('body was echoed', function () {", " pm.expect(pm.response.json().payload.your_request_body.everything).to.eql('is_fine');", "});" ] } } ] } ] }, { "name": "Checkout Intent", "description": "End-to-end checkout-intent lifecycle. Create → poll status → fetch full detail. `Create` captures the returned intent id into the `checkout_intent_id` environment variable so the two GETs work without manual copy-paste.\n\n**Two create flavors** (pick exactly one on each request):\n\n- **Fiat pricing** — send `currency` (IntEnum, Appendix A). The server FX-converts to the resolved settlement coin (USDT or USDC) at the current rate; `currency_rate` in the response is non-null. Use `accepted_stable_coins` (first entry wins) to pick the settlement coin; defaults to USDT.\n- **Native stable-coin pricing** — send `stable_coin` (IntEnum, Appendix B). `amount_cents` is stable-coin cents (`1000` = `10.00` of the chosen coin). No FX happens, so `currency_rate` in the response is `null`. Both `stable_coin = 1` (USDT) and `stable_coin = 2` (USDC) are accepted.\n\nSending both — or neither — of `currency`/`stable_coin` returns `10001`.", "item": [ { "name": "POST /v1/checkout_intents/ (Create — fiat)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"currency\": 1,\n \"amount_cents\": 100,\n \"order_id\": \"qa_order_{{$timestamp}}\",\n \"order_description\": \"QA test order\",\n \"user_id\": \"qa_user_001\",\n \"user_name\": \"QA Tester\",\n \"redirect_url\": \"https://example.com/checkout/allscale\",\n \"extra\": {\n \"source\": \"postman\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/checkout_intents/", "host": ["{{base_url}}"], "path": ["v1", "checkout_intents", ""] }, "description": "Create a checkout intent priced in fiat. Server FX-converts the amount into the resolved settlement coin (USDT or USDC) at the current rate.\n\n**Field notes**\n\n- `currency` is the fiat IntEnum (1 = USD, 44 = EUR, …). Full table in `API Doc - Checkout Intent Routes - Create Checkout Intent.md` → Appendix A.\n- `amount_cents` is integer **fiat** cents. The resulting stable-coin amount must be greater than `0.1` (USDT or USDC); orders at or below the floor are rejected with `50002`.\n- Do **not** also send `stable_coin` on this request — sending both returns `10001`.\n- `redirect_url` must be `https://…` in production; sandbox also allows `http://`.\n- Settlement coin is **USDT or USDC**. To pin it on a fiat-priced order, send `accepted_stable_coins: [1]` (USDT) or `[2]` (USDC); the first entry picks the settlement coin used for FX conversion. `stable_coin_type` in the response matches whichever was resolved (defaults to `1` USDT).\n\nThe post-response test captures `payload.allscale_checkout_intent_id` into `{{checkout_intent_id}}` for the follow-up GETs." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const body = pm.response.json();", "pm.test('code == 0', function () {", " pm.expect(body.code).to.eql(0);", "});", "pm.test('payload.allscale_checkout_intent_id exists', function () {", " pm.expect(body.payload).to.have.property('allscale_checkout_intent_id');", " pm.expect(body.payload.allscale_checkout_intent_id).to.be.a('string');", "});", "", "if (body && body.payload && body.payload.allscale_checkout_intent_id) {", " pm.environment.set('checkout_intent_id', body.payload.allscale_checkout_intent_id);", " console.log('[AllScale] captured checkout_intent_id = ' + body.payload.allscale_checkout_intent_id);", "}" ] } } ] }, { "name": "POST /v1/checkout_intents/ (Create — native stable-coin)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"stable_coin\": 1,\n \"amount_cents\": 1000,\n \"order_id\": \"qa_stable_{{$timestamp}}\",\n \"order_description\": \"QA native USDT order\",\n \"user_id\": \"qa_user_001\",\n \"user_name\": \"QA Tester\",\n \"redirect_url\": \"https://example.com/checkout/allscale\",\n \"extra\": {\n \"source\": \"postman\",\n \"pricing\": \"native_stable_coin\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/checkout_intents/", "host": ["{{base_url}}"], "path": ["v1", "checkout_intents", ""] }, "description": "Create a checkout intent priced **natively in a stable coin** — no FX happens.\n\n**Field notes**\n\n- `stable_coin` is the StableCoin IntEnum (see Appendix B). Both `1` (USDT) and `2` (USDC) are accepted; other values are reserved and will be rejected.\n- `amount_cents` is **stable-coin cents** of the chosen `stable_coin`: `1000` = `10.00` of that coin. The example above (`stable_coin: 1`) produces a `10 USDT` order; switch to `stable_coin: 2` for the equivalent USDC order.\n- Do **not** also send `currency` — sending both, or neither, returns `10001`.\n- The response's `currency_rate` will be `null` (no FX). In the full GET, the fiat fields (`currency`, `currency_symbol`, `amount_cents`, `currency_rate`) will all be `null`; the authoritative amount is `amount_coins`.\n\nThe post-response test captures `payload.allscale_checkout_intent_id` into `{{checkout_intent_id}}` just like the fiat flavor." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const body = pm.response.json();", "pm.test('code == 0', function () {", " pm.expect(body.code).to.eql(0);", "});", "pm.test('payload.allscale_checkout_intent_id exists', function () {", " pm.expect(body.payload).to.have.property('allscale_checkout_intent_id');", "});", "pm.test('rate is null for native stable-coin pricing', function () {", " pm.expect(body.payload.rate).to.be.oneOf([null, undefined]);", "});", "", "if (body && body.payload && body.payload.allscale_checkout_intent_id) {", " pm.environment.set('checkout_intent_id', body.payload.allscale_checkout_intent_id);", " console.log('[AllScale] captured checkout_intent_id = ' + body.payload.allscale_checkout_intent_id);", "}" ] } } ] }, { "name": "GET /v1/checkout_intents/{id}/status", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/checkout_intents/{{checkout_intent_id}}/status", "host": ["{{base_url}}"], "path": ["v1", "checkout_intents", "{{checkout_intent_id}}", "status"] }, "description": "Poll-friendly lightweight status check. `payload` is the status integer (see status enum in the doc).\n\nUse this instead of the full GET when all you need is the lifecycle state." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const body = pm.response.json();", "pm.test('code == 0', function () {", " pm.expect(body.code).to.eql(0);", "});", "pm.test('payload is integer status', function () {", " pm.expect(body.payload).to.be.a('number');", "});" ] } } ] }, { "name": "GET /v1/checkout_intents/{id}", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/checkout_intents/{{checkout_intent_id}}", "host": ["{{base_url}}"], "path": ["v1", "checkout_intents", "{{checkout_intent_id}}"] }, "description": "Full checkout intent object — order metadata, currency/coin fields, on-chain tx hashes when payment has settled. Ownership is enforced: the intent must belong to the store identified by `api_key`, otherwise `30001 Forbidden`." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const body = pm.response.json();", "pm.test('code == 0', function () {", " pm.expect(body.code).to.eql(0);", "});", "pm.test('payload has core fields', function () {", " const p = body.payload;", " pm.expect(p).to.have.property('all_scale_checkout_intent_id');", " pm.expect(p).to.have.property('currency');", " pm.expect(p).to.have.property('amount_cents');", " pm.expect(p).to.have.property('status');", " pm.expect(p).to.have.property('tx_to');", "});" ] } } ] } ] } ] } ``` # AllScale\_OpenAPI\_Production.postman\_environment.json ``` { "id": "a11sc4le-0pen-4p1-env2-000000000002", "name": "AllScale OpenAPI — Production", "values": [ { "key": "base_url", "value": "https://openapi.allscale.io", "type": "default", "enabled": true }, { "key": "api_key", "value": "", "type": "default", "enabled": true }, { "key": "api_secret", "value": "", "type": "secret", "enabled": true }, { "key": "checkout_intent_id", "value": "", "type": "default", "enabled": true } ], "_postman_variable_scope": "environment", "_postman_exported_using": "AllScale docs" } ``` # Get on board with AllScale Pay Create your account. Link your business. Start sending and receiving stablecoin payments with ease. **Click to our official website, enter your email address. You can choose two ways to register**
**A. Passkey** **Click the "Continue with Passkey", you can save your passkey on your phone, choose " iPhone, iPad, or Android device"**
**For iPhone users** * Scan the QR code with your camera * Approve the passkey login request **For Android users** * Scan the QR code with \*\*Google Authenticator (\*\*If the app isn’t installed, please download it from **Google Play** or your preferred app store) * Approve the passkey login request **To successfully use the passkey, please:** * Update your browser to the latest version * If using VPN, please ensure all your devices are using the same IP address
**B. Email** **Click the "Create with Email", the verification code will be sent to your email address. Enter the correct verification code to complete the registration**
**👣 First Steps After Login** Once you're in, here’s what we recommend: 1. **Set up your profile** — Add your name, avatar, and basic info 2. **Try creating a test invoice** — Learn how the flow works 3. **Check out the Contacts tab** — Add or import key relationships # Dashboard {% hint style="info" %} #### Welcome to Your AllScale Pay Dashboard Once you're logged in, your **dashboard** provides an overview of your account situations—account balance, transaction history, and quick link to creat invoice, all in one place. this page walks you through each core section of your AllScale Pay dashboard: {% endhint %} Once logged in, your dashboard shows a whole view of your account:
*** ## 💰 Your Wallet Balance At the top of the dashboard, you’ll find a real-time snapshot of your total asset value across supported stablecoins, displayed in native token amounts. And you can also deposit and withdraw your wallet here. {% hint style="info" %} The detail of the balance, as well as tutorials on depositing and withdrawing amounts, please refer to [Wallet Features](/allscale-pay/core-modules/wallet/wallet-features). {% endhint %}
*** ## 📜 Transaction History This displays whole your transaction history in Allscale Pay, including: * Invoices you've received or paid * Deposit and withdraw for the AllScale wallet
*** ## 🤝 Create New Invoices This is a quick navigation button that takes you to create the invoice. {% hint style="info" %} The tutorials on creating a new invoice, please refer to [Invoicing Features](/allscale-pay/core-modules/invoicing/invoicing-features#create-a-new-invoice)**.** {% endhint %}
*** ## 🤗Links Here you can find information about our community and links to our social media.
*** ## 📒 **Menu** This is the navigation of the Allscale Pay: * [**Wallet**](/allscale-pay/core-modules/wallet) displays all your stablecoins and the chains they reside on * [**Invoicing**](/allscale-pay/core-modules/invoicing) is a powerful feature that allows transactions without a third party * [**Contacts**](/allscale-pay/support-modules/contacts) can manage your contacts * [**Settings**](/allscale-pay/support-modules/settings) for managing your account information * [**Checkout**](/allscale-checkout/getting-started) is another payment collection product we have developed for merchants
# Core Modules # Wallet The following will introduce the wallet-related functions, which are the hub of other core modules of Allscale Pay. ## This chapter contains the following contents： {% content-ref url="/pages/f1t5YyCSPHBbYjiwYwWR" %} [Wallet Overview](/allscale-pay/core-modules/wallet/wallet-overview) {% endcontent-ref %} {% content-ref url="/pages/Jcf0V1Bttgqr5NSNpmuQ" %} [Wallet Features](/allscale-pay/core-modules/wallet/wallet-features) {% endcontent-ref %} # Wallet Overview Your digital wallet for stablecoin payments. One place to receive, hold, and withdraw funds globally. ## 🧭 What Is the Wallet? The **Wallet** is your central account inside AllScale Pay. It holds the stablecoins you receive from: * Paid invoices * Service orders from your Social Commerce page * Direct payments from other AllScale users * External crypto wallet Each token (like USDT, USDC, or other supported stablecoins) is tracked in its own line item, and you’ll also see a **real-time estimated USD value** of your total assets. *** ## 🔐 How It Works * You can **deposit** directly into your Balance via supported stablecoin wallets * You can **withdraw** your funds at any time — withdrawals are one-way and go to your connected wallet * All incoming payments from invoices or Social Commerce activity are automatically settled into your Balance * You always retain custody of your earnings until you choose to move them *** ## ⭐Key Features * Secure, self-custodial wallet system * Multi-stablecoin support * Estimated total value in USD * On-chain deposit & withdrawal support * Transaction history (incoming/outgoing) # Wallet Features ## 🔍 Balance At the middle of the Wallet page, you’ll find a real-time snapshot of your total asset value across supported stablecoins, displayed in estimated USD equivalent. **Key elements:** * Network-specific balances (e.g., ETH, BSC, etc.) * Estimated USD value calculated from live market prices
*** ## ➕ Depositing Stablecoins Users can easily deposit stablecoins into their AllScale Pay account by selecting the desired token and network, then transferring to the provided deposit address. **Supported features:** * Choose from supported tokens/networks * QR code and copyable address for convenience **Steps to Deposit:** 1. Click **Deposit** 2. Select the network 3. Send funds to the generated address 4. Wait for confirmation and balance update
*** ## ➖ Withdrawing Stablecoins Withdrawals are just as straightforward—users can send funds out of their AllScale Pay wallet to an external wallet address.We currently offer two withdrawal methods: withdrawing directly to a specific address, and using a claim link.
1. **Go directly to the wallet:** 1. Click **Wallet** 2. Enter wallet address and confirm 3. Choose token and withdrawal amount 4. Complete 2FA and wait for balance update
2. **Claim link:** 1. Click **Claim Link** 2. Choose token and withdrawal amount 3. Leave your message 4. Complete 2FA {% hint style="info" %} What is Claim link? —— You have a stablecoin balance in your account → generate a URL link and send it to anyone → the recipient clicks the link; those with a wallet simply enter their address to claim the funds, while those without one can log in via email to open an AllScale wallet and claim them. {% endhint %}
If you wish to distribute claim links in bulk, please refer to the [AllScale Checkout](/allscale-checkout/getting-started#step-5-personalize-your-payment-settings). *** ## 📜 Transaction History Every deposit and withdrawal will be tracked in a ledger under the **Wallet**: * Timestamp * Transaction type (Deposit / Withdrawal/ Invoice/ Checkout) * Network, token and amount **Additionally, by clicking on each transaction, you will see more information:** * Status (Pending / Confirmed / Failed) * Blockchain transaction ID
*** ## 🔒 Stability and Security * Assets are segregated by user and stored under multi-signature and cold wallet protocols (platform-specific, if applicable) * Incoming and outgoing transfers are monitored for compliance and risk * Only stablecoins are supported to minimize volatility exposure *** #### Coming Soon * Fiat on-ramp integrations * Wallet address book * Multi-chain support for new tokens/networks # Invoicing The following pages introduce the core module of Allscale Pay - Invoicing {% content-ref url="/pages/fejvff36xvbLBb7Alrug" %} [Invoicing Overview](/allscale-pay/core-modules/invoicing/invoicing-overview) {% endcontent-ref %} {% content-ref url="/pages/Lx6agqSGdH4e3t9ZOBIF" %} [Invoicing Features](/allscale-pay/core-modules/invoicing/invoicing-features) {% endcontent-ref %} # Invoicing Overview Send invoices. Get paid in stablecoins. No friction. ## 🧭 What Is It? AllScale Pay’s **Invoicing** feature allows you to issue professional payment requests directly from your dashboard — no third-party tools, no bank account required. Whether you’re billing a client for freelance work, requesting payment for a service, or managing vendor payouts, the invoicing system handles everything from creation to confirmation. You simply enter basic invoice details, and the recipient receives an email with secure, built-in payment options. Payments settle directly into your **AllScale Balance** in stablecoins. *** ## 🌍 Why It Matters Traditional invoicing tools weren’t built for stablecoin workflows. AllScale’s invoicing system is: * **Crypto-native** — designed for stablecoin payments from day one * **Client-friendly** — supports external recipients, no registration required * **Faster to settle** — avoid banking delays * **Fully integrated** — tied to your Contacts, Social Commerce, and Balance No more manual follow-ups, clunky templates, or missing payments. Just fast, global, and reliable invoicing built for modern work. *** ## 🔐 How It Works * **Create an Invoice:**\ Specify the recipient's email, amount, currency, due date, and description of services. * **Send via AllScale System:**\ AllScale sends the invoice by email or in-app notification (if linked to an AllScale Pay account). * **Recipient Pays:**\ The recipient chooses from available payment methods—no AllScale Pay account required. * **You Receive Stablecoins:**\ Regardless of how the invoice is paid, funds arrive in your AllScale Pay balance in stablecoin form. * **Track History:**\ View detailed invoice status, timestamps, and transaction logs under your **Invoice History** tab. *** ## 🖐 Key Features * Issue invoices in USDT, USDC, or other supported stablecoins * Accept payments from AllScale Pay users or external payers * Built-in email delivery with downloadable PDF * Flexible payment options (wallets, cards, wire) * Full payment history and status tracking # Invoicing Features ## 📝 Create a New Invoice {% hint style="warning" %} Before you create an invoice, you need to create an Allscale wallet as your address to receive transfers. For more information about wallets, please refer to [Wallet Features](/allscale-pay/core-modules/wallet/wallet-features). {% endhint %} The Invoice creation form is built for speed and flexibility. Whether you're billing a company, client, or individual, all you need is their email address. **During invoice creation, you'll need to provide the following information:** * Recipient details (email, address, name, etc.) * Item description * Amount * Due date * Notes Before sending, you can preview the invoice in PDF format to verify all the details.
*** ## 📤 Sending & Delivery Once submitted, your invoice is automatically delivered to the recipient by: * **Email** (if recipient is not on AllScale Pay) * **In-app notification** (if recipient has a connected AllScale Pay account) No matter which way, the recipient will receive a downloadable PDF (identical to the sender’s preview) along with clear payment instructions tailored to the available methods at that time.
*** ## 💳 Payment Methods Recipients can pay invoices through various methods, with funds automatically converted into stablecoins and credited to your AllScale Pay balance. **Supported payment options:** * AllScale Pay Balance (if both parties are users) * External Crypto Wallets * Crypto Wallets Extension No matter how the invoice is paid, the **issuer always receives stablecoins** directly into their AllScale Pay account.
*** ## 📈 Invoice Status Tracking Stay up to date with real-time invoice tracking through the **Invoice History** dashboard. If the user connects to AllScale Pay, they can track the invoice status in real-time within the website. 🤝**For Both Senders and Recipients:** **Status flow includes:** * Paid * Rejected * In progress * Failed **Each record shows:** * Amount * Status * Date issued & due * Share link To view the history of paid or received invoices, check the "History" section on the dashboard and wallet homepage.
*** ## 🔒 Security & Compliance * Payment routing is secure and monitored * Identity and AML checks apply to large invoices * Recipient doesn’t need an AllScale account to pay * You retain full control over cancellation or edits before payment *** #### Coming Soon * Recurring invoice templates * Payment reminders * Auto-conversion to other stablecoins # Social Commerce (Coming Soon) The next few pages will introduce an exciting feature of Allscale Pay - Social Commerce. ## This chapter contains the following contents： {% content-ref url="/pages/TSQcWBf96Hg1iMkkvi84" %} [Social Commerce Overview](/allscale-pay/core-modules/social-commerce-coming-soon/social-commerce-overview) {% endcontent-ref %} {% content-ref url="/pages/XD2mE49jAJUexIKrZZiw" %} [Social Commerce Features](/allscale-pay/core-modules/social-commerce-coming-soon/social-commerce-features) {% endcontent-ref %} # Social Commerce Overview Create Your Public Profile. Showcase Services. Get Paid Globally. ## 🧭 What Is Social Commerce? AllScale Pay’s **Social Commerce** feature lets you create a public-facing profile to showcase your services and accept payments — all through a streamlined, crypto-native checkout flow. You can share your personalized link with anyone. Visitors can browse your profile, view your listed services, and submit order requests — which generate pre-filled invoices you can approve and get paid on. *** ## 🌍 Why It Matters Freelancers today rely on patching together landing pages, DMs, PDFs, and spreadsheets. AllScale Social Commerce replaces all of that with one link. It’s your **crypto-native storefront**, built into the same place where you manage your finances and invoices. > No coding. No integrations. Just you, your services, and a direct line to global income. *** ## ⭐ Key Features * Public profile builder with social links * Service catalog with optional pricing * Instant ordering through pre-filled invoices * Random or custom shareable URL * Payment tracking and receipt in stablecoins # Social Commerce Features ## 👤 Create a Public Profile Your Social Commerce profile is your personalized, shareable page on AllScale Pay. It acts like a mini landing page that showcases who you are, what you do, and how people can pay you for services. **Profile Fields Include:** * Display Name * Avatar (profile image) * Description / Bio * Social Links (Twitter, LinkedIn, website, etc.) * Custom URL suffix (available with subscription)
*** ## 🛠 Add Services to Sell List the services you offer so that anyone visiting your page can understand what you do and request work right away. **Service Listings Include:** * Service Title * Description * Price (in stablecoin, fixed price or custom fair price input) Each service added will automatically generate a structured invoice request form for the visitor to complete when requesting your service.
*** ## 🔗 Share Your Public Link After your profile is published, you’ll receive a public URL (e.g., `allscale.io/yourname`) that you can share on social platforms, bios, or directly with clients. * Free users receive a **randomly generated suffix** * Subscribed users can **customize their link** (e.g., `allscale.io/johnfreelancer`)
*** ## 📥 Accepting Requests When a visitor clicks a service on your public page, they’ll be taken to a **pre-built invoice request form**. After they submit: * You’ll receive a notification * An invoice will be auto-generated for your review and approval * Once approved, the client receives payment instructions and can complete the payment *** ## 💸 Get Paid Instantly Payments submitted via your Social Commerce page are processed using the same invoice engine as the core Invoicing feature. You’ll receive: * Stablecoin funds in your AllScale balance * Real-time notifications * A linked transaction under both **Invoices** and **Contacts** *** ## 📊 Manage Your Offers and Orders Within your dashboard, you can: * Edit or remove services * Track pending requests * Monitor income per service * Adjust pricing at any time * Export service history for your records *** #### Coming Soon * Ratings and reviews * Service bundles * Real-time chat or message requests # Support Modules # Contacts The Contacts effectively support the smooth operation of Social Commerce and Invoicing.\ Next, we will introduce the design of the Contacts features. ## This chapter contains the following contents： {% content-ref url="/pages/Ni1eZU7xP5WBDqd9Q0hL" %} [Contacts Overview](/allscale-pay/support-modules/contacts/contacts-overview) {% endcontent-ref %} {% content-ref url="/pages/Nmham7lGFudpUSKgLVV5" %} [Contacts Features](/allscale-pay/support-modules/contacts/contacts-features) {% endcontent-ref %} # Contacts Overview Build Your Network. Streamline Payments. Stay Organized. ## 🧭 What Is the Contacts Feature? The **Contacts** section in AllScale Pay helps you manage the people and businesses you interact with financially. Any time you send or receive an invoice, the other party is automatically saved as a **Contact** — so the next transaction is faster and more seamless. You can also manually add contacts for recurring workflows or upcoming payments. *** ## 🗂️ What You Can Do * **Add people or businesses** to your contacts using their email or AllScale Pay account ID * **Save contact details** including names, notes, and payment preferences * **Initiate payments or invoices** directly from your contact list * (Coming Soon) **Set up recurring payments** for ongoing arrangements Whether you're paying a team member monthly or invoicing a long-term client, Contacts keeps everything organized, trackable, and just a few clicks away. *** ## 🔐 How It Works * **Add a Contact:**\ Use their email or AllScale ID to connect. Optionally, save custom labels and notes. * **Quick Actions:**\ Send invoices or make payments directly from the contact card. * **Track History:**\ View payment and invoice history associated with each contact. * **Coming Soon - Recurring Payments:**\ Automate routine payments for added efficiency. *** ## ⭐ Key Features * Contact list management with saved metadata * Quick access to payment and invoicing actions * Searchable and sortable list view * Relationship-based transaction history * Upcoming support for recurring payments # Contacts Features ## 📇 Add and Manage Contacts The Contacts page allows you to build a trusted network of collaborators—whether they’re contractors, clients, or recurring partners. **Ways to Add a Contact:** * Enter their email address (connected or not connected to AllScale Pay) * Add a name, optional note, and label (e.g., “Designer”, “Client - Retainer”) Each contact entry stores essential details to speed up future transactions.
*** ## ⚡ Quick Actions Each contact is equipped with action buttons so you can: * **Send a payment (Coming soon)** * **Issue an invoice** * **View past transactions** * **Edit or delete contact info** This allows for fast, frictionless workflows when working with your core team or regular payees.
*** ## 🔁 Recurring Payments (Coming Soon) We’re introducing a powerful automation layer for your contacts. With recurring payments, you’ll be able to: * Set a payment frequency (weekly, monthly, quarterly) * Define a fixed amount and token * Pause or modify ongoing schedules * Automatically notify recipients upon each scheduled payment **Use cases:** * Retainer-based service providers * Employee stipends * Long-term freelance arrangements *** ## 🔒 Privacy & Data * Contacts are visible only to you * No messages are sent unless you initiate a payment or invoice *** #### Coming Soon * Contact request approvals for network building * Import/export contact list # Settings The next few pages will introduce the **Settings**. Users can use the **Settings** to complete the configuration of their personal information and preferences. ### This chapter contains the following contents： {% content-ref url="/pages/ofZRZ5hA7yqG1APclPUX" %} [Settings Overview](/allscale-pay/support-modules/settings/settings-overview) {% endcontent-ref %} {% content-ref url="/pages/mHOkhrZfptuBVp7wiMjq" %} [Settings Features](/allscale-pay/support-modules/settings/settings-features) {% endcontent-ref %} # Settings Overview Manage Your Account. Customize Your Experience. Stay in Control. ## 🧭 What Is the Settings Section? The **Settings** section is your personal control panel inside AllScale Pay. It allows you to manage your account preferences, language, login credentials, subscriptions, and other core settings — helping tailor the platform to your workflow. Whether you're managing multiple services, switching languages, or upgrading your features, this is where it all starts. *** ## 🗂️ What You Can Do * **Edit your account details** such as name, email, and password * **Manage language and regional settings** * **Subscribe to premium features** like custom Social Profile URLs * **View billing and subscription status** * **Manage security features** (e.g., 2FA, recovery email – coming soon) This section is also where you'll handle notifications, privacy preferences, and access help resources as we continue to expand platform support. *** ## ⭐ Key Features * Personal information editing * Multi-language support (more coming soon) * Subscription and billing management * Security settings (more coming soon) * Notification and privacy controls (in development) # Settings Features ## 👤 Profile & Account Information This is where you manage your core account identity and preferences. **Editable fields include:** * Display Name * Email Address * Password (with reset and 2FA protection) * Country / Region (used for localization) You can also view your current account type (e.g., Free, Pro) and subscription status at a glance.
*** ## 🌐 Language & Regional Settings AllScale Pay supports multiple languages and local preferences. Easily adjust: * Dashboard language * Date and time formats * Currency display options (USD equivalent shown globally) This helps personalize your experience while keeping USD as the universal settlement base for your assets. *** ## 💼 Subscription & Billing Manage your current plan, upgrade to premium, or view your billing history. **Features Include:** * Overview of plan features (Free vs. Premium) * Payment method on file (if applicable) * Downloadable invoices for platform fees (e.g., for Social Commerce subscriptions) * Cancel or switch plans **Image Sample**\ \&#xNAN;*(Insert screenshot of Subscription tab with pricing tiers and billing table)* *** ## 🔔 Notification Preferences (Coming Soon) Fine-tune how and when you receive alerts from AllScale Pay: * Email notifications (e.g., invoice paid, funds received) * In-app alerts and banners * Push notifications (mobile app integration planned) You'll be able to opt in or out of specific categories. *** ## 🔒 Security Settings Your AllScale Pay account is protected with high-grade encryption and optional verification layers. **Coming security features:** * Two-Factor Authentication (2FA) * Login device history * Recovery email setup These controls will ensure your financial dashboard stays private and secure.
# Rewards ## 🧭What Is the Rewards? **Rewards** is an incentive system designed to recognize and give back to active users for their participation and contributions withinAllScale.By **completing tasks**, **inviting friends**, and **participating in our media activities,** you can earn corresponding **AllScale Points (ASP)**. These points represent your genuine interaction and contribution within the ecosystem. They serve as proof for **future reward redemptions**, **exclusive access**, or **participation in special campaigns**. Built on the spirit of Web3, the Rewards mechanism aims to turn every real user action into **long-term value and growth**, rather than just a one-time incentive. We believe the future of cross-border payments belongs to a network **co-built by its users**. Every point you earn and every reward you claim stands as proof of your early participation — and as a shared force driving the adoption of decentralized finance. ## 🔐What is ASP and Level in Rewards? ### **AllScale Points (ASP)** **AllScale Points (ASP)** are the core points in our Rewards system. It reflects your activity, contribution, and engagement across the platform. The more ASP you accumulate, the higher your level and the more awards you can enjoy ASP is divided into **Seasonal ASP** and **Total ASP**: * **Seasonal ASP** measures your recent activity during **specific campaign periods**. When a season ends, these points are converted into rewards and then reset to zero. * **Total ASP** is the cumulative amount of **all ASP** you’ve earned since your account was created. It does not decrease when a campaign ends and is directly linked to your user **level**.
### Level **Level** corresponds to your **Total ASP** and serves as an indicator of your overall contribution to the ecosystem. Higher levels grant users access to more **product benefits** and privileges, as well as eligibility for more airdrop rewards in the future. The following are the rules for **level upgrades**: | Level | ASP Range | | ------ | ------------------- | | Lv1 | 0 – 499 ASP | | Lv2 | 500 – 999 ASP | | Lv3 | 1,000 – 9,999 ASP | | Lv4 | 10,000 – 19,999 ASP | | Lv5 | 20,000 – 29,999 ASP | | ...... | ...... | ## ⭐How to Earn ASP Our ASP can be earned in 2 ways: **Tasks** and **Redeem Codes**. ### Tasks By completing the following tasks, users can earn the corresponding ASP： #### Fixed Tasks Fixed tasks are missions that can only be completed once and grant a fixed amount of ASP | Task | Reward | | ---------------------- | -------- | | Email Verification | +100 ASP | | First Payment Received | +400 ASP | #### Scalable Tasks Scalable tasks can be completed repeatedly, allowing users to continuously earn ASP | Task | Reward | | ------------------------------- | ----------------- | | Invoice Payments Received | +1 ASP/ 1 USDT | | 7-Day Login Streak | +300 ASP/ streak | | Referral First Payment Received | +400 ASP/ referal | {% hint style="info" %} ### Invite a Friend In our “Rewards”, you can simply copy the referral link and share it with your friends.

{% endhint %} ### **Redeem Codes** In addition to completing tasks and inviting friends, there are other ways to earn ASP. Follow our community channels (**Telegram / Discord**) and social media (**X**) — during our campaigns, we will select lucky participants to receive **redemption codes**. Enter these codes in the **“Redeem Code”** section of your rewards system, and you can receive the corresponding ASP.
# FAQ When at doubt, don't hesitate to contact our 24/7 support ## Account Registration & Compatibility
Why can't I complete registration? What platforms does AllScale Pay support? AllScale Pay uses PASSKEY for account verification, providing you with a more secure and convenient payment experience. Currently, only devices and systems compatible with PASSKEY standards are supported. **Supported System Versions:** * iOS 16.0 and above * Android 9.0 and above (requires Google Play Services) * Windows 11 **Supported Browser Versions:** * Chrome 67 and above * Safari 14 and above (iOS only - macOS Safari not currently supported) Other system versions and browsers are not currently supported. **If you cannot complete registration, please:** 1. **For Android users**: Ensure Google Play Services is installed and updated. Your device's camera app needs to support the latest security features (PRF functionality) to work properly. 2. **For macOS users**: Use Chrome browser instead of Safari (macOS Safari does not support PASSKEY features) 3. Check if your device's system version meets the minimum requirements listed above 4. Update your browser to the latest version 5. Ensure PASSKEY is enabled on your device (fingerprint or face recognition) 6. Try using browser's private/incognito mode 7. Temporarily disable third-party password manager extensions (such as Bitwarden, KeePass, etc.) **Still having issues?** Please fill out our [bug report form](https://docs.google.com/forms/d/e/1FAIpQLSf8GrgsRPEYPoxMIL8rnkwXAtxAwglv-NeeoqwgpoX5wnjIzg/viewform?pli=1) with your device and system information so we can better assist you. We are working to expand platform compatibility to serve more users with secure and convenient payment services.
## ​Wallet Features
I've deposited tokens, but why don't they show in my balance? Currently, the wallet interface only displays USDT balances. Display functionality for other tokens is under development - please stay tuned for future updates. Your tokens are safe; they're just temporarily not displayed in the interface.
If I deposited non-stablecoin tokens (such as SOL) or tokens on unsupported chains, how can I withdraw them? You can retrieve your tokens through the following steps: 1. Go to the \[**Security]** page 2. Click \[**Secret Phrase]** → \[**Export]** to export your private key
3. Import the private key into other wallet applications (such as [MetaMask,](https://metamask.io/) [Trust Wallet](https://trustwallet.com/) ) to manage your tokens
I have a balance in my wallet interface, but why can't I Send to other addresses? Currently, the Send function only supports the Ethereum (ETH) network. Support for other blockchain networks (including but not limited to BSC, Solana, etc.) is under development.
I deposited tokens on the APTOS chain, how can I withdraw them? You can retrieve your assets on the APTOS chain through the following steps: 1. Go to the \[**Security**] page 2. Click \[**Secret Phrase**] → \[**Export**] to export your private key
3. Import the private key into [APTOS-supported](https://aptosfoundation.org/ecosystem/projects/wallets) wallet applications (such as [Petra Wallet](https://petra.app/)) 4. You can then manage and transfer your APTOS chain assets in that wallet **Please rest assured that your assets are safe. We are currently developing support for APTOS and other blockchain networks.**
Does AllScale Pay know my private key? No. AllScale Pay is a 100% non-custodial wallet architecture solution leveraging PassKey technology, giving you complete control over your private keys. We cannot access your private keys, ensuring that your token security is entirely under your control.
## Invoice Features
Why does the amount shown on the Invoice differ from what I entered? The amount displayed on the Invoice includes your base amount plus gas fees and service fees.
Why do customers need to provide personal information when paying with credit cards? This information is required by third-party payment processors (such as credit card processing institutions) for: * Identity verification and anti-money laundering checks * Compliance with financial regulatory standards * Fraud prevention AllScale Pay does not store this sensitive information - all data is transmitted directly to licensed third-party processors. Any additional fees incurred during the payment process are charged by the third-party payment service providers, not by AllScale Pay.
I'm a Allscale Pay user, why can't I pay Invoices sent to me by others? Currently, AllScale Pay's invoice payment functionality only supports the **Ethereum (ETH) network**. To pay invoices, you need to have tokens on the Ethereum mainnet. **Solutions:** **Option 1: Transfer tokens to ETH network** Use cross-chain bridges or exchanges to convert your tokens from other networks (such as BSC, TRON, Solana, etc.) to Ethereum mainnet, then make the payment. **Option 2: Use alternative payment methods** * Credit card payment * Other supported payment options **Option 3: Wait for multi-chain support** We are developing support for additional blockchain networks. **Note:** If you accidentally deposited tokens to unsupported networks in your AllScale wallet, refer to our [withdrawal guide](#if-i-deposited-non-stablecoin-tokens-such-as-sol-or-tokens-on-unsupported-chains-how-can-i-withdraw) for recovery instructions.
## Upcoming Features We are actively developing the following features: * **Multi-currency display support**: Balance display for USDC and other stablecoins * **Multi-chain network support**: Send functionality for more blockchain networks * **Platform compatibility expansion**: Support for more operating systems and devices ## Need Help? If you encounter other issues or need technical support, you can: * Contact us through our Telegram Support channel or Discord channel * Check our user [documentation](/allscale-pay/allscale-pay-introduction) We are committed to providing you with the best stablecoin payment experience. # AllScale Pay Introduction An all-in-one payment and monetization dashboard for the modern, borderless workforce. ## Overview **AllScale Pay** is an open, all-in-one payment platform designed to serve individuals and businesses using stablecoins for transactions. Whether you're a freelancer or creator looking to get paid in stablecoins, or a contractor or supplier seeking a lightweight alternative, AllScale Pay has you covered. It helps you easily **create invoices, grow your business**, or **purchase services**. As a user, you can: > * **Create and send invoices** to anyone via email > * **Accept payments** in multiple stablecoins > * **Track all income and payouts** in your AllScale Balance > * **Withdraw funds** to crypto wallets or supported payout methods > * **Build a Social Commerce profile** and list services publicly > * **Manage contacts** for faster repeat payments *** ## 🧩 The Problems AllScale Pay Solves AllScale Pay addresses the growing disconnect between global digital work and traditional payment infrastructure. | 🚫 The Problem | ✅ AllScale Pay Solves It With | | -------------------------------------------------------- | ---------------------------------------------- | | International payments are slow and costly | Fast, borderless stablecoin payments | | Invoicing tools are disconnected from wallets | Built-in invoicing and payment tracking | | No easy way to sell services and accept payment | Social Commerce profiles with service listings | | Managing income and payouts across currencies is painful | Unified stablecoin Balance dashboard | | Traditional tools require bank access or fiat | Crypto-first, no bank account required | *** ## 🌍 Why It Matters Remote work is global. Clients and contractors often live in different countries, work in different currencies, and need tools that don’t rely on traditional banking. **AllScale Pay bridges that gap.**\ It makes cross-border work fast, flexible, and financially inclusive — no matter where you or your clients are. ## Get Started We've put together some helpful guides for you to get setup with our product quickly and easily. {% content-ref url="/pages/hYN3optPyq4iXqfctTIZ" %} [Get on board with AllScale Pay](/allscale-pay/get-on-board-with-allscale-pay) {% endcontent-ref %} {% content-ref url="/pages/8vVEufeLG39oNSBQn35K" %} [Dashboard](/allscale-pay/dashboard) {% endcontent-ref %} ## Quick links {% content-ref url="/pages/jXEjVLsc2zD9RLJs60HH" %} [Welcome to AllScale](/) {% endcontent-ref %} {% content-ref url="/pages/3g2Zi2CFtDqjvV8Ioa7J" %} [Allscale Payroll Introduction](/allscale-payroll/allscale-payroll-introduction) {% endcontent-ref %} # Allscale Payroll Introduction {% hint style="success" %} **Run Payroll. Manage Teams. Stay in Control.** {% endhint %} ## Overview Welcome to **AllScale Payroll**, your all-in-one platform for secure, global payroll management—built for teams operating in both fiat and stablecoins. Whether you're managing salaried employees or contractors, AllScale gives you the tools to seamlessly **fund your account**, **onboard your team**, **run and approve payroll**, and **track every transaction with confidence**. As a Team Manager, you’ll have access to a powerful dashboard where you can: > * View payroll cycles and deposit balances at a glance > * Fund your account via wire transfer (stablecoin deposits coming soon) > * Add, manage, and offboard employees > * Set up and approve payroll for different employee types > * Track payroll statuses from Draft to Paid > * Communicate with your team and access live support (coming soon) This guide is your step-by-step companion to getting started—from logging in for the first time to sending your first successful payroll. Let’s walk through each function so you can unlock the full power of your AllScale business account. ## Quick Links {% content-ref url="/pages/jXEjVLsc2zD9RLJs60HH" %} [Welcome to AllScale](/) {% endcontent-ref %} {% content-ref url="/pages/CDsF1x5XQl2eH8y0XXMQ" %} [Modules](/allscale-payroll/modules) {% endcontent-ref %} ## Get Started We've put together some helpful guides for you to get setup with our product quickly and easily. {% content-ref url="/pages/zpw2tC4Kol0DsyjproYo" %} [Get on board with AllScale Payroll](/allscale-payroll/get-on-board-with-allscale-payroll) {% endcontent-ref %} {% content-ref url="/pages/45bqWWtUxED62oo4G9VE" %} [Understanding Payroll](/allscale-payroll/understanding-payroll) {% endcontent-ref %} # Get on board with AllScale Payroll Welcome to AllScale Payroll! Please follow these five simple steps to start your Payroll journey： {% content-ref url="/pages/tEbEB4g5hN0WLZzPoTxd" %} [Step 1: Creating your organization](/allscale-payroll/get-on-board-with-allscale-payroll/step-1-creating-your-organization) {% endcontent-ref %} {% content-ref url="/pages/5VtVtmY0YT3uAOuTC3wa" %} [Step 2: Loging in](/allscale-payroll/get-on-board-with-allscale-payroll/step-2-loging-in) {% endcontent-ref %} {% content-ref url="/pages/yBfL1dLz2U5PR2oRttMo" %} [Step 3: Inviting your team](/allscale-payroll/get-on-board-with-allscale-payroll/step-3-inviting-your-team) {% endcontent-ref %} {% content-ref url="/pages/N9tgoROcfgQdTWZTQoYg" %} [Step 4: Making your first deposit](/allscale-payroll/get-on-board-with-allscale-payroll/step-4-making-your-first-deposit) {% endcontent-ref %} {% content-ref url="/pages/lyibd9F1anCzBvooD3Qm" %} [Step 5: Managing your payroll](/allscale-payroll/get-on-board-with-allscale-payroll/step-5-managing-your-payroll) {% endcontent-ref %} # Step 1: Creating your organization To get started, you'll need to submit your organization details to the AllScale team. Once submitted, our onboarding manager will verify the information and activate your business account. #### What You’ll Need to Provide: **🏢 Company Info** * [ ] **Payroll Start Date**: The day your team begins operations (not the payday). This helps us align your payroll cycle accurately. * [ ] **Payment Frequency**: Choose how often your team will be paid (e.g., Monthly, Biweekly, Weekly). * [ ] **Company Name**: Use your legal entity name as registered with your local government. * [ ] **Company Address**: Include full mailing address for verification. * [ ] **Country/Region**: Select your company's country of incorporation. * [ ] **Company Logo** *(optional)* **📇 Contact Info** * [ ] **Full Legal Name**: The legal name of the account owner or admin. * [ ] **Phone & Email**: Your primary contact info. We'll use this to send setup confirmations and onboarding help. * [ ] **Note** *(optional)*: Add any additional info you'd like our team to consider. {% hint style="success" %} #### 🚀 Once you provide all the information, our team will handle the rest and notify you when your dashboard is ready. {% endhint %} # Step 2: Loging in Once you receive account creation confirmation email, **go to**: [dashboard.allscale.io/login](https://dashboard.allscale.io/login)
* **Email**: Use the email address registered with AllScale. * **Temporary Password**: the confirmation email should contain a temporary password. Please update your password as soon as possible to unlock all the features. > ⚠️ **Important**: *You will be immediately prompted to change your password after your first login. Choose a strong password you don’t use elsewhere (e.g., one with uppercase, lowercase, numbers, and symbols). You will be able to create payrolls after you have successfully updated your password.* # Step 3: Inviting your team Follow instructions at [Adding New Members](/allscale-payroll/modules/people#adding-new-members) to add a new team member. #### ⚠️ Key Reminders * Employee start date is the date your team member starts working for your company. It must be **before their first payroll date.** * **Email must be valid** — it's their login and identity in the system * You **cannot edit member details or payroll settings** after onboarding yet — contact AllScale for any changes > **💡Company-Wide Payroll Schedule:** All employees are included in a single company payroll cycle. This means everyone will be paid on the same schedule, rather than individually. # Step 4: Making your first deposit Welcome to AllScale! Before running payroll or collecting payments, you’ll need to fund your account. Here's a quick guide to help you confidently complete your **first deposit**. *** #### 🧠 Before You Begin * ✅ Make sure you’re using a USD **business bank account** (personal accounts may be flagged or rejected). * 🕐 **Transfers may take up to 2 business days** to appear in your AllScale balance, depending on your bank and time zone. * 🔒 If you’re using a new sender bank account, ensure the name matches your registered AllScale entity. * 📩 You’ll be able to check your deposit status at [**Deposit History**](/allscale-payroll/modules/dashboard#view-deposit-history) (Submitted → In Progress → Deposited). *** 👉 Head to our [**Wire Transfer Deposit Tutorial**](/allscale-payroll/modules/dashboard#fiat-deposit-wire-transfer) #### 💬 Need Help? If you're unsure about any part of the process, contact the AllScale team directly—we’re always here to assist! # Step 5: Managing your payroll AllScale’s payroll runs automatically on your scheduled pay date. Here’s what you need to know to ensure smooth processing: 1. [**Maintain Sufficient Balance**](/allscale-payroll/modules/dashboard#balance) Make sure your account has enough funds before the scheduled pay date to cover all employee payments. 2. [**Approve Payment**](/allscale-payroll/modules/payroll#approve-payment) Go to your Dashboard and approve the payroll before the pay date. > ⚠️**What If There’s an Issue?** > > * If your balance is too low, your payroll will be marked **overdue** until the issue is resolved. > * For any other issues, AllScale will notify you directly so you can take action.
# Modules ## 📊 Dashboard A centralized view to monitor and manage payroll and account activity: * [**Upcoming Payment:**](/allscale-payroll/modules/dashboard#upcoming-payment) View upcoming payments. * [**Balance**:](/allscale-payroll/modules/dashboard#balance) View your account's current balance and make a deposit. * [**Team:**](/allscale-payroll/modules/dashboard#team) Overview of the team's current employees and their salaries. * [**Updates:**](/allscale-payroll/modules/dashboard#updates) Alerts for pending actions, errors, and important updates. * [**Menu**](/allscale-payroll/modules/dashboard#menu)**:** Navigation for the platform.
*** ## 💼 Payroll Run, review, and control your payroll operations: * [**Create Payroll**](/allscale-payroll/modules/payroll#create-payroll): Generate payments for full-time staff, contractors, or one-time payouts. * [**Approve Payment:**](/allscale-payroll/modules/payroll#approve-payment) Review and approve employees' monthly salaries. * [**Payroll History**](/allscale-payroll/modules/payroll#payroll-history): Audit trail of all payrolls—amounts, methods, and timestamps.
*** ## 👥 People Handle your team's payroll-related onboarding and settings: * [**Adding new Member**](/allscale-payroll/modules/people#adding-new-members): Onboard new team members. * [**Removing Team Members:**](/allscale-payroll/modules/people#removing-team-members) Remove members from the team.
*** ## 📞 Communication & Support (Coming Soon) Get help and stay connected with your team: * **FAQs & Guides**: Self-serve resources for onboarding and troubleshooting. * **Raise Ticket for Payment Issue**: Submit specific requests for support. # Dashboard {% hint style="info" %} #### Welcome to Your AllScale Payroll Dashboard Once you're logged in, your **dashboard** provides a high-level overview of your operations—everything you need to manage your team, monitor funds, and stay on top of payroll, all in one place. From tracking employee status to handling deposits, this page walks you through each core section of your AllScale Payroll dashboard: {% endhint %} Once logged in, your dashboard shows a high-level view of your operations:
*** ## 🧾**Upcoming Payment** * You can see the due date and amount of your upcoming payment. Click in "Invoice" to download the most up-to-date invoice.
*** ## 💰Balance * **Check Your Balance** - To view your current balance in fiat directly on the dashboard, just click the eye icon on the top right to reveal the actual amount. * **Fiat Deposit (Wire Transfer)** - Click the Deposit button and follow the instructions. Include the correct reference code and upload your wire transfer details accurately for faster processing. * **View Deposit History** - See all past deposits, their status, and methods under Deposit History. Track progress: *Submitted → Processing → Deposited*. * **Stablecoin Deposit (Coming Soon)** - You’ll soon be able to deposit stablecoins directly from your wallet.
### **Fiat Deposit (Wire Transfer)** **🔁 Step 1: Open Deposit & Initiate a Wire Transfer** 1. Click **“Deposit”** on your dashboard. 2. A tutorial window will appear guiding you through the process. 3. **Download the wire transfer details** provided in the window. 4. Make the transfer using your **business bank account**. 📌 **Important:** Include your **unique Business Reference Code** in the memo/notes field of your wire transfer. *Missing this code may cause delays in processing your deposit.*
**📤 Step 2: Click “I Transferred” and Submit Transfer Info** After completing the transfer: 1. Click the **"I Transferred"** button. 2. Fill in the **Confirm Your Wire Transfer** form: * **Amount Sent (in fiat)** * **Sender Bank Name** * **Sender Account Name** * **Transaction Reference Code** * **Business Number** (auto-filled) 3. Click **Submit**.
**📩 Step 3: Wait for Confirmation** AllScale will notify you via email once the deposit is confirmed. ⏱ This usually takes **less than 2 business days**. You can also track the status under "**Deposit History"**: **Submitted → In Progress → Deposited** ### **View Deposit History**
*** ## 🗂️**Team** * This section gives you a quick snapshot of everyone in your group — including their pay date, payment amount, and status. You can also click "Add Member" to add employees.
*** ## 📝**Updates** This is your real-time alert system. You'll receive: * **Reminders** for payrolls that need approval * **Error alerts** if a deposit or payment fails * **Important messages** from the AllScale team (e.g., product updates, compliance reminders, employee wallet address changes, etc)
*** ## 📒**Menu** This is the navigation of the Allscale Payroll: * **Dashboard** for high-level overview of your team * **Payroll** for managing payrolls and see histories * **People** for managing your team members and onboarding new members
*** # Payroll {% hint style="success" %} Once your employees are set up and your account is funded, you’re ready to manage team payments. This section guides you through approving/declining and tracking payrolls from start to finish. {% endhint %}
## 📥Create Payroll **Payroll is created automatically** once an employee has registered their wallet with AllScale. There’s no need to manually create a new payroll cycle. Please contact AllScale team to make any changes to your team's payroll. ## 🔩Approve Payment Before your team gets paid, every payroll run must be reviewed and approved to ensure everything is accurate and ready to go. **🔍 Step 1: Review the Payroll** For each payroll cycle, make sure to check: * **Total amount to be paid** * **Payment method**: Fiat or Stablecoin * **Scheduled pay date** 📌 *Double-check for any errors or missing information—this is your chance to make adjustments before funds are locked in.*
**🛠 Step 2: Approve the Payroll** Once everything looks correct: * Click **“Approve”** to confirm the payroll * This locks in the schedule and initiates processing ⚠️ *Your account must have **sufficient funds** prior to the pay date, or the payment will not execute on time.* ## 💸Payroll History The **Payroll** tab gives you full visibility into both **upcoming** and **past payroll runs**, so you can stay organized and in control. **🗓 What You Can View** * **Upcoming Payroll**: See scheduled payments and download **invoices** ahead of time.
* **Past Payroll**: Review completed payrolls and download payroll summary and AllScale service receipt for your records or accounting needs.
{% hint style="warning" %} **⚠️ If Something Goes Wrong** AllScale continuously monitors your payroll status and promptly alerts you to any issues requiring attention. Our team is here to support you and ensure a seamless payroll experience. {% endhint %} # People {% hint style="success" %} AllScale makes it easy to manage your team from one centralized place—whether you're onboarding, updating info, or reviewing individual payment history. Note, you must add team members with the correct payroll setting - you may need to contact AllScale admin to update payroll setting for now. {% endhint %}
## 👥Adding New Members ➕ **Step 1: Add Your Team** * Use the “Add Member” function on "people" tab to input basic information and payroll settings. ⚙️ **Step 2: Enter Accurate Information** When adding a team member, make sure to: * Use a **valid, company-controlled email address** * Choose the correct **role** and **payment type** * Double-check for **spelling errors or duplicate accounts**
> ⚠️ **Important**: Employee start date is the date they start working for your company. It must be before the **👥 Step 3: What Team Members Need to Do** As soon as a team member logs into their AllScale account for the first time, they’ll be prompted to: 1. Complete password update 2. Connect their wallet address
**✅ Step 4: What You Need to Approve** As a team manager, you are responsible for **reviewing and approving** each team member’s withdrawal method **before the payroll date**. This step is **mandatory** to: * ✅ Prevent fraud * ✅ Ensure funds are sent to the correct wallet or account * ✅ Avoid delays in payroll processing
**📩 How You’ll Be Notified** You’ll receive a notification when: * A new wallet is added * A change is requested **🔒 Step 5: Overview of your employees' status** In the "people" tab, you can see employees who have accepted invitations and those who have not yet accepted invitations.
{% hint style="info" %} To make it easier for companies to export employee information, we support batch import. Simply click "Import Members" in the "People" tab.

{% endhint %} ## ➖Removing Team Members * In the People tab, click the "..." button to the right of a person's name, then click "Remove account" to remove that member from the list.
{% hint style="info" %} 🔒 **Editing Info**: This feature is **coming soon**. If you need to update details like email, payroll amount, or contract type, please **contact the AllScale team directly**. {% endhint %} # Documents AllScale provides three essential documents to help your business manage and track payroll operations with clarity and compliance. Each serves a distinct purpose in your payroll workflow: 1. [**Invoice**](/allscale-payroll/documents/invoice) – Issued to your business to request pre-funding for upcoming payroll 2. [**Payroll Summary & Service Receipt** ](/allscale-payroll/documents/payroll-summary-and-receipt)– Confirms which employee payments were processed and provides an official receipt for AllScale’s service fee 3. [**Payslip**](/allscale-payroll/documents/payslip) – Issued to employees as a transparent record of their stablecoin payment These documents ensure transparency, traceability, and accountability across every step of the payroll cycle — from funding to disbursement to reporting. Use the following pages to understand what each document includes, how to explain them to your team, and how to use them effectively. # Invoice ### 📌 What Is This Document? The **Deposit Invoice** is a document issued by AllScale to notify your business of the total amount required to fund payroll for a given cycle. It includes both: 1. **Employee payouts** (i.e. salary disbursements) 2. **Service fees** charged by AllScale for facilitating payroll This invoice acts as a **pre-payment request**, ensuring that AllScale has the appropriate funds to execute payroll on your behalf.
*** ### 🧾 Breakdown of the Deposit Invoice | Section | Description | | ------------------------- | --------------------------------------------------------------------------------- | | **Invoice Title & Label** | Identifies the document as a *Deposit Invoice*, not a payroll invoice or payslip. | | **Payroll No.** | A unique reference number that links this invoice to a specific payroll cycle. | | **Issue Date** | The day the invoice was generated and sent to your business. | | **Billing Period** | The timeframe for which this payroll funding applies (e.g., May 01–May 30). | *** ### 🧍 Parties Involved | Role | Details | | ------------- | ------------------------------------------------------------- | | **Billed To** | Your company name and address (e.g., NovaEdge Solutions Inc.) | | **Issued By** | AllScale’s registered address and contact information | This section makes it clear that AllScale is issuing the invoice **on your behalf**, under a payroll service agreement. *** ### 📊 Funding Breakdown The main section of the deposit invoice includes: * **Team Member Details**\ A table listing each employee scheduled to receive payment: * Name * Payroll reference number * Payment period * Amount to be paid * **Subtotal**\ Total gross payroll amount to be distributed to your team members. * **Conversion Rate**\ Exchange rate if currency conversion applies (typically USD → stablecoin like USDT).\ E.g., `1 USD = 1 USDT`. * **Service Fee (e.g. 3%)**\ AllScale’s fee for facilitating the payroll transaction. * **Total**\ The full amount your business needs to deposit into your AllScale account.\ (Subtotal + Service Fee) > ⚠️ *Funds listed in the payroll section will be fully distributed to employees and are not recognized as AllScale revenue.* *** ### 💳 Payment Instructions A short note instructing your team to **complete payment** using the methods provided in your AllScale Dashboard. These might include stablecoin transfers, wire payments, or credit card options depending on your setup. *** ### ⚖️ Legal Disclaimer The bottom section outlines important legal clarifications: * AllScale is a **payment processor**, not the employer * The payroll amounts are processed *through* AllScale on behalf of your company * This document does **not** act as a tax certificate or proof of employment * All employment liabilities remain between your company and your employees > 📩 **Contact:** If you have questions about the invoice, email *** ### 🧑‍💼 What to Do as a Manager 1. **Review the invoice details:** Make sure all amounts and employee names match your records. 2. **Fund your account:** Deposit the total amount listed using the instructions in your dashboard. 3. **Confirm your payroll calendar:** Ensure timely funding to avoid delays in employee payments. 4. **Communicate clearly with your team:** Let them know payroll is being processed and when they can expect to receive their stablecoin payouts. *** ### 🧠 Summary | ✅ Use This Document To | ❌ Do Not Use It For | | -------------------------------------- | ------------------------ | | Fund your AllScale account for payroll | Tax filing | | Track total compensation owed to team | Employment verification | | Confirm service fees | Employee payslip records | # Payroll Summary and Receipt ## 📄 What it is The **Payroll Summary & Service Receipt** is a consolidated document issued by AllScale after each payroll cycle. While both appear in the same file, they serve **two different purposes**: * ✅ **Payroll Summary** – a record of all employee payments, including successful and failed transactions * 💳 **Service Receipt** – an official confirmation that AllScale has collected its service fee This guide explains both components in detail so you can effectively use the document for internal tracking, financial reporting, and reconciliation.
*** ### 📌 Document Overview | Section | Purpose | | ------------------- | ---------------------------------------------------------- | | **Payroll Summary** | Tracks all outgoing salary payments for the billing period | | **Service Receipt** | Confirms AllScale has deducted its service fee | *** ### 🧾 Payroll Summary (Section 1) #### 📍 What It Is The **Payroll Summary** provides a line-by-line record of team member payments for the payroll period. It separates: * ✅ **Successful Payments** – Transactions that were completed and sent to employee wallets * ❌ **Unsuccessful Payments** – Transactions that failed and were **not** deducted from your account #### 📊 Key Fields Explained | Field | Description | | ------------------------------ | ------------------------------------------------------------------- | | **Payroll No.** | Internal reference number for the payroll cycle | | **Paid Date** | Date payments were processed | | **Billing Period** | The period of work the payroll covers | | **Team Members** | List of employees associated with each transaction | | **Payroll No. (per employee)** | Reference ID for each payment record | | **Amount** | Total in USD for each payment | | **Remarks** | Notes about fund disbursement and retry options for failed payments | #### ⚠️ Notes for Managers * Unsuccessful payments are **not lost** — they remain in your account balance and can be retried via the AllScale dashboard. * The **total section** includes both successful and unsuccessful payment amounts, helping you reconcile your pre-funded amount. *** ### 💳 Service Receipt (Section 2) #### 📍 What It Is The **Service Receipt** portion confirms that AllScale has successfully charged your business a **payroll service fee**. This is your **official record** for financial and accounting purposes. #### 💰 Key Fields | Field | Description | | ----------------------- | --------------------------------------------------------------- | | **Service Fee Rate** | Typically 3% of total payroll processed | | **Amount Paid** | Total USD equivalent of the fee | | **Acknowledgment Note** | Confirms funds were deducted from your AllScale account balance | > 📘 This section is your **proof of payment** for AllScale’s payroll processing service and can be used for expense reporting or audits. *** ### ⚖️ Legal Disclaimer At the bottom of the document, you’ll find a standard disclaimer that clarifies: * AllScale is not your employee’s legal employer * The funds listed in payroll are **not AllScale revenue** * This document is **not** a tax certificate or proof of employment * All employment responsibilities remain with your business *** ### 📬 If You Need Help Reach out to AllScale's support team at:\ 📧 **** We’re here to help with failed payment retries, account balance questions, or service fee clarifications. *** ### ✅ Use This Document For: | Use Case | Applies To | | -------------------------- | ----------------- | | Verifying employee payouts | ✅ Payroll Summary | | Confirming fee deductions | ✅ Service Receipt | | Expense & audit reporting | ✅ Both | | Legal proof of employment | ❌ Neither | | Tax filing | ❌ Neither | # Payslip ### 🧾 What Is the Payslip? The payslip is a **digital payment confirmation** issued by AllScale. It shows how much your employee was paid, the time period covered, and how the payment was processed via blockchain. > 🛑 **Note:** AllScale is the payroll facilitator — not the employer. Your company remains the legal employer and is responsible for employment-related matters such as taxes, contracts, and benefits.
*** ### 📌 Sections of the Payslip Each payslip contains the following core sections: #### **1. Company Information** * Displays your business name and registered address * Communicates who initiated the payroll * Reassures employees that this document is linked to your business, not a third party #### **2. Employee Information** * Includes the employee’s name and address * Used to personalize the payslip and match the recipient with the payroll record
#### **3. Payroll Details** | Field | Description | | ---------------------------- | ------------------------------------------------------------- | | **Pay Period** | Indicates the start and end dates for the time worked | | **Amount Paid** | Total amount paid for the period, usually in stablecoins | | **Wallet Address** | Employee’s blockchain wallet where payment was sent | | **Transaction Hash** | A unique identifier showing the transaction on-chain | | **Blockchain Network** | Specifies the blockchain used (e.g., Ethereum, Polygon) | | **Payment Timestamp** | Exact date and time the payment was processed | | **Payroll Reference Number** | An internal tracking ID used for recordkeeping | | **Payment Method** | States the currency and channel used (e.g., USDT on Ethereum) |
#### **4. Legal Disclaimer** AllScale includes a legal disclaimer stating: * All payments were made on behalf of your business * AllScale is not the legal employer * Employment rights, obligations, and tax responsibilities remain with your company * The payslip is for informational purposes and does **not** replace a T4, tax form, or employment agreement\\ #### **5. Contact & Support Information** Employees are provided with a dedicated support email `payroll@allscale.io` to ask questions about the payslip or report discrepancies. *** ### 💡 How to Explain the Payslip to Your Employees When your employees receive their payslip, make sure to communicate the following: #### ✅ What it **is**: * A **confirmation of payment** processed via blockchain * A document that shows exactly when and how they were paid * A tool for transparency and recordkeeping #### ❌ What it **is not**: * Not a tax form * Not a contract * Not a proof of employment from AllScale *** ### 🗣 Sample Message for Team Leaders > “Hi team,\ > You’ll be receiving your payslip from AllScale. It shows your payment amount, the dates covered, and blockchain transaction details. > > This document is issued by AllScale on our behalf — they’re our payroll processor, not your employer. If anything looks off or you need help understanding the format, feel free to reach out to me or contact .” *** ### 📦 Summary | ✅ This Payslip Provides | ❌ This Payslip Does Not Provide | | ----------------------------------- | ------------------------------- | | Proof of stablecoin payment | Proof of employment | | Blockchain-verifiable record | Tax documentation | | Transparency in salary disbursement | Legal employment rights | # Understanding Payroll {% hint style="success" %} **AllScale tip:** AllScale’s payroll system runs **automatically**, but knowing what each status means helps you stay in control. Whether it's **setting up funds**, **approving a payment**, or **fixing a failed transfer**, this table walks you through what’s happening and what (if anything) you need to do. 📌 **Why it matters:** * Avoid missed or delayed payments * Know when to take action (and when to relax!) * Keep your team paid on time, every time 💬 *Tip: You’ll receive automatic email notifications whenever your payroll status changes—no need to constantly check back.* 👇 Refer to the table below for a breakdown of each payroll state. {% endhint %}
Payroll StateWhat It MeansBusiness Action
DraftPayroll is created after the last payroll due date but not yet approved.Approve the payroll. If not approved 48 hours before the due date, you will receive an email reminder.
ApprovedPayroll is approved by the business.Ensure sufficient funds before the due date. You can still cancel if needed. You’ll receive an email if funds are insufficient 48 hours prior to the due date.
ReadyPayroll is approved, funds are sufficient, and the scheduled pay date has arrived.No further action is needed unless you need to cancel. The payment should process within 24 hours.
PaidFunds have been successfully transferred.No action needed. Payroll is complete and cannot be reverted. You’ll be notified of successful payment.
OverduePayroll reached the pay date without sufficient funds.Top up your account and retry (moves to Ready), or cancel. You’ll be notified immediately.
FailedFund transfer attempt was unsuccessful.Retry (moves to Ready) or cancel. You’ll receive an email about the failed transaction.
CancelledPayroll was canceled by the business or admin.No action required unless you want to recreate the payroll. You’ll be notified of the cancellation.
#### 🔄 Payroll Flow Overview This chart shows the **lifecycle of a payroll run** in AllScale. * **Thick black lines** represent the **optimal path**:\ `Draft → Approved → Ready → Paid` * **Grey lines** indicate **edge cases or exception states**, such as: * **Overdue**: When there are insufficient funds by the pay date * **Cancelled**: When a payroll is manually stopped * **Failed**: When the payment transfer is unsuccessful
# Partner Program Overview The **AllScale Partner Program** is designed for individuals, communities, agencies, and business partners who help introduce new merchants to **AllScale Checkout**. Whether you are sharing AllScale with your network through a referral link or supporting merchants more directly through business development, the Partner Program gives you a structured way to collaborate with AllScale and participate in growth. At launch, the Partner Program includes two paths: * **Affiliate Program** — for partners who refer merchants through a unique referral link * **Broker Program** — for partners who support merchant sourcing and collaboration more directly These two paths are related, but they are **not the same program tier**. * The **Affiliate Program** is the standard referral model with a published commission schedule * The **Broker Program** is an application-based model that requires direct coordination with AllScale and may include custom commercial terms, pricing autonomy, and dedicated support *** ### Program Overview #### Affiliate Program The Affiliate Program is designed for partners who want a simpler and more standardized referral model. With the Affiliate Program: 1. You create or log in to your AllScale account 2. You receive your unique referral link 3. You share that link with eligible merchants 4. The merchant registers and activates **AllScale Checkout** 5. Once the merchant begins processing qualified transactions, you may become eligible to earn commission based on qualified platform fees #### Broker Program The Broker Program is designed for higher-conviction partners who work more directly with merchant acquisition, commercial structuring, and ongoing business relationships. With the Broker Program: 1. You reach out to AllScale and apply for the program 2. AllScale reviews your network, merchant profile, and potential volume 3. If approved, you may receive custom commercial terms 4. You onboard merchants through a more direct broker relationship with AllScale 5. You may receive broker-specific economics, dashboards, and support based on your agreement *** ### What Partners Receive #### For Affiliates Eligible affiliates can receive revenue share based on qualified platform fees generated by referred merchants, using the following schedule: * **Year 1:** 25% * **Year 2:** 15% * **Year 3:** 10% * **Year 4 onward:** 5% #### For Brokers Eligible brokers can receive autonomous fee margin, for example:
#### For Referred Merchants Eligible referred merchants can receive: * **10% fee discount** during their first **3 months**, subject to program terms and eligibility * **$2,000 cashback** as a one-off reward for reaching **$1,000,000** in settlement volume *** ### 🔎 Notes * Participation in the Broker Program is subject to approval, verification, and ongoing compliance review * Rewards are calculated only on **qualified referrals** and **qualified transactions** * Broker terms may be governed by separate commercial discussions or partnership agreements * AllScale reserves the right to review, withhold, adjust, or reverse rewards in cases of abuse, fraud, or rule violations * Program details may be updated over time as the Partner Program evolves *** Need help or want to join the program? Contact the AllScale team through your existing relationship manager or reach out through the official onboarding channel. # Affiliate vs. Broker The AllScale Partner Program includes two parallel paths: **Affiliate Program** and **Broker Program**. Both are designed to help partners introduce merchants to **AllScale Checkout**, but they differ in structure, entry path, and commercial model. *** ### 🧾 At a Glance
FeatureProfessional BrokerStandard Affiliate
Earning ModelAutonomous fee marginRevenue share on AllScale fees
CommissionCustom premium terms, case by case25% → 15% → 10% → 5%
Client PricingFull autonomyNot applicable
DashboardDedicated broker portalBasic referral tracking
Ideal ForAgencies, KOLs, C-level connectors, orgsIndividuals, creators, community leads
EntryApplication & approvalStandard signup / access flow
*** ### 🔗 Standard Affiliate The Affiliate Program is the more standardized path. It is designed for partners who want to: * share a referral link * introduce merchants to AllScale Checkout * earn commission based on AllScale platform fees * participate without negotiating custom pricing terms Affiliate commission follows the standard published schedule: * **Year 1:** 25% * **Year 2:** 15% * **Year 3:** 10% * **Year 4 onward:** 5% Each commission tier is calculated **per referred merchant**, starting from that merchant’s **AllScale Checkout activation date**. *** ### 🏢 Professional Broker The Broker Program is the more customized path. It is designed for partners who may: * work directly with merchant networks * influence pricing and commercial structure * require stronger operational visibility * collaborate with AllScale on a more tailored basis Depending on the partnership structure, brokers may receive: * custom commercial terms * pricing autonomy, subject to agreement * dedicated broker dashboard access * negotiated deal structures based on network quality, vertical, and volume potential Broker participation requires **direct outreach, application, and approval by AllScale**. *** ### 🎯 Which Path Is Right for You? Choose the **Affiliate Program** if you want a lighter-weight, standardized, referral-based path. Choose the **Broker Program** if you have a stronger merchant network, want a more tailored commercial model, and are ready to work directly with AllScale on approval and structure. *** # Affiliate Program The AllScale Checkout Affiliate Program is built to make merchant referrals simple and trackable. ### 1. Create Your AllScale Account To participate in the Affiliate Program, you must first register an **AllScale account**. If you already have an AllScale account, you can use your existing account to access the Partner Program when eligible. ### 2. Get Your Referral Link Once approved for the Affiliate Program, you will be able to access your **unique referral link**. This link is used to attribute eligible merchant registrations to your account. ### 3. Share with Merchants You can share your referral link with merchants, partners, clients, or ecosystem contacts who may benefit from accepting stablecoin payments through **AllScale Checkout**. Typical examples include: * Online merchants * Offline merchants * Platforms with merchant networks * Agencies or service providers working with merchants * Business partners exploring new payment options ### 4. Merchant Registers with AllScale When a merchant uses your referral link to register, the referral may be recorded and attributed to your account, subject to program rules. Merchant registration alone does not automatically guarantee commission eligibility. ### 5. Merchant Activates AllScale Checkout To become a **qualified referral**, the merchant must complete the required onboarding and activate **AllScale Checkout**. Depending on the merchant type and integration path, this may include: * Account registration * Required onboarding information * Checkout setup and activation * Ability to begin processing live payments ### 6. Merchant Starts Processing Qualified Transactions Once the referred merchant begins processing **qualified transactions**, the affiliate may become eligible to earn revenue share on the applicable platform fees based on the program schedule in effect for that specific referred merchant relationship. The commission schedule starts from the merchant’s **AllScale Checkout activation date**. At the same time, the referred merchant may receive a **10% fee discount** during the first **3 months**, subject to program terms. *** ### 📌 Notes * Referral attribution is subject to AllScale’s tracking and verification rules * Only eligible merchants and qualified transactions are counted * Rewards are not generated from incomplete onboarding, invalid accounts, test activity, or abusive behavior For details on eligibility, attribution, and exclusions, see: * Eligibility & Qualified Referrals * Commission & Payout * Program Terms & Anti-Abuse # Eligibility & Qualified Referrals ### 👤 Who Can Join the Affiliate Program? The Affiliate Program is intended for individuals and organizations that can help introduce new merchants to AllScale Checkout. This may include: * Existing AllScale users * Ecosystem partners * Communities and KOLs * Agencies and consultants * Business development partners * Operators with relevant merchant networks AllScale may approve, reject, suspend, or remove participation at its discretion. *** ### 🏪 What Is a Referred Merchant? A **referred merchant** is a merchant account that registers with AllScale through a valid affiliate referral link and is attributed to the affiliate under the applicable program rules. *** ### ⭐ What Is a Qualified Referral? A referral generally becomes **qualified** only when the referred merchant completes the required onboarding and successfully activates **AllScale Checkout**. This may include, where applicable: * Completing registration * Providing required onboarding or business information * Passing internal review or approval * Completing technical or operational setup * Becoming eligible to process live merchant transactions A merchant that only clicks a referral link or only creates an account is not necessarily a qualified referral. *** ### 💳 What Is a Qualified Transaction? A **qualified transaction** is a legitimate, completed, eligible transaction processed by a qualified referred merchant through AllScale Checkout and accepted by AllScale for commission calculation. AllScale may exclude transactions that are not considered valid for reward purposes. Examples of transactions that may be excluded include: * Test transactions * Refunded or reversed transactions * Failed or incomplete transactions * Fraudulent or suspicious transactions * Transactions associated with abuse, manipulation, or policy violations * Transactions otherwise determined by AllScale to be ineligible *** ### 🚫 What Is Not Allowed? The Affiliate Program is intended to reward genuine merchant referrals. The following are prohibited: * Self-referrals * Creating or using multiple accounts to generate artificial rewards * Referring merchants that are controlled by the same person or entity for the primary purpose of earning rewards * Fake, misleading, or fraudulent merchant acquisition * Any abusive activity designed to manipulate attribution, fees, or payout outcomes *** ### 🌍 Availability and Restrictions Participation may not be available in all regions, for all merchant categories, or for all use cases. Eligibility may depend on: * Merchant category * Jurisdiction * Compliance requirements * Product availability * Operational readiness AllScale may update the supported scope of the program at any time. *** ### 📌 Notes * AllScale determines whether a referral and transaction qualify under the program * Qualification may be subject to review, verification, and ongoing monitoring * Program participation does not guarantee commission on every referred account or every transaction # Commission & Payout ### 🧮 Reward Basis Unless otherwise stated by AllScale, affiliate rewards are based on: * Qualified referred merchants * Qualified transactions * Qualified platform fees recognized under the program The exact calculation logic, settlement treatment, and final recognized amounts are determined by AllScale. *** ### ⏱️ Payout Timing Affiliate rewards are not necessarily issued in real time. Payout timing may depend on: * Transaction settlement status * Internal reconciliation * Fraud and compliance review * Minimum payout threshold * Program operations and payout schedule AllScale may define or update the payout schedule from time to time. *** ### 💼 Payout Method Where applicable, affiliate payouts may be made through one of the following methods: * Account balance * Stablecoin payout * Other payout method designated by AllScale The supported payout method may vary depending on region, account status, or operational setup. *** ### 🚫 Exclusions and Adjustments Commission may be withheld, adjusted, canceled, or reversed in cases including but not limited to: * Ineligible referrals * Ineligible transactions * Refunds, reversals, or disputes * Fraud, abuse, or suspicious activity * Violations of the Partner Program rules * Errors in attribution, reporting, or calculation *** ### 📌 Notes * The Affiliate Program is designed to reward real merchant growth, not artificial activity * Final reward amounts are always subject to AllScale verification and reconciliation * AllScale may revise commission structure, payout timing, or incentive design as the program evolves For definitions and qualification rules, see [Eligibility & Qualified Referrals](/allscale-partner-program/affiliate-program/eligibility-and-qualified-referrals). # Affiliate FAQ ### Account & Participation #### Why can't I access the Affiliate Program yet? The Affiliate Program may be rolled out in stages. Access may depend on account status, region, eligibility, or internal approval. #### Do I need an AllScale account to join? Yes. You must have an AllScale account in order to participate in the Affiliate Program. #### Can any user become an affiliate? Yes. However, AllScale reserves the right to deny participation based on program requirements. *** ### Referral Attribution #### When does a referral count? A referral generally counts only when the referred merchant is successfully attributed to your referral link and becomes a qualified referral under the program rules. The commission schedule for that referral starts when the merchant activates **AllScale Checkout**. #### Does merchant registration alone count as a successful referral? No. Registration alone does not necessarily qualify. The merchant must usually complete onboarding and activate AllScale Checkout. #### What if multiple people refer the same merchant? Credit goes to the first affiliate who referred the merchant, as long as the referral remains active. *** ### Rewards #### How much can I earn? Eligible affiliates may earn revenue share based on qualified platform fees from qualified referred merchants according to the following schedule: * **Year 1:** 25% * **Year 2:** 15% * **Year 3:** 10% * **Year 4 onward:** 5% Each commission tier is calculated **per referred merchant**, starting from that merchant’s **AllScale Checkout activation date**. #### What benefit does the referred merchant receive? Eligible referred merchants may receive a **10% fee discount** during their first **3 months**, subject to program terms and eligibility. Also, merchant can get a one-off **$2,000** **cashback** upon reaching $1,000,000 in processed settlement volume. #### Do I earn rewards on every transaction from a referred merchant? Not always. Only qualified transactions that meet program requirements are included. #### When will I receive my payout? Payout timing depends on reconciliation, settlement status, internal review, and the applicable payout schedule. Currently it's settled on a monthly basis. *** ### Restrictions #### Can I refer myself? No. Self-referrals and similar abusive behaviors are not allowed. #### Can I create multiple accounts to earn more rewards? No. Creating or using multiple related accounts to generate artificial rewards is prohibited. #### Why were some rewards not counted or adjusted? Rewards may be withheld, excluded, or adjusted if the associated referral or transaction is found to be ineligible, suspicious, refunded, reversed, or otherwise non-compliant. *** ### Support #### Where can I ask for help? If you need support, please contact the AllScale team through your existing relationship manager or official support channel. * Email: * Discord: # Broker Program The **AllScale Broker Program** is designed for higher-touch partners who work more directly with merchant acquisition, commercial discussions, and long-term revenue opportunities. Unlike the standard Affiliate Program, the Broker Program is **not self-serve**. Broker participation requires: * direct outreach to AllScale * application and review * approval by the AllScale team * commercial terms defined through the broker relationship *** ### 💼 What Makes the Broker Program Different? Depending on your approved structure, the Broker Program may include: * **custom premium terms** negotiated case by case * **pricing autonomy** for broker-managed merchant relationships, subject to agreement * **dedicated dashboard access** for broker reporting and visibility * a more direct working relationship with the AllScale team This model is intended for partners with stronger merchant networks, deeper commercial involvement, or a more professional channel role. *** ### 👤 Who Is It For? The Broker Program may be a fit for: * agencies * KOLs with strong merchant access * operators with direct merchant networks * consultants and channel partners * C-level connectors * organizations with recurring merchant deal flow *** ### 📌 Important Notes * Broker Program participation is subject to application and approval * Broker economics are not identical to Affiliate economics * Final terms may be governed by a separate partnership agreement or case-by-case discussion # Onboarding Flow ### 1. Reach Out to AllScale To join the Broker Program, you must first contact the AllScale team and express interest in becoming a broker partner. * Email: * Telegram: @leowry123 ### 2. Apply and Get Approved AllScale reviews your profile, merchant network, industry focus, and potential transaction volume. Broker participation is subject to approval. ### 3. Receive Your Commercial Structure If approved, AllScale will define the broker structure applicable to your relationship. Depending on the agreement, this may include: * base settlement terms * broker economics * pricing flexibility * dashboard access * reporting structure ### 4. Onboard and Support Merchants As a broker, you may bring merchants to AllScale through a more direct and commercially involved process than the standard Affiliate path. ### 5. Earn According to Your Broker Terms Broker rewards are governed by the applicable commercial structure agreed with AllScale. Broker terms may differ from the standard Affiliate commission schedule. # Benefits & Commercial Structure The AllScale Broker Program is designed for partners who want a more tailored commercial model than the standard Affiliate path. Depending on the broker relationship and approved structure, brokers may receive enhanced commercial benefits and operational support. *** ### 🌟 Broker Benefits Approved brokers may receive one or more of the following benefits: * **Custom premium terms** defined case by case * **Pricing autonomy** for broker-managed merchant relationships, subject to agreement * **Dedicated dashboard access** for tracking merchant activity, transaction volume, and broker economics * **Direct collaboration with AllScale** on merchant onboarding and commercial execution * **More tailored partnership structure** based on network quality, merchant profile, and volume potential The exact benefit package may vary by broker profile and agreement. *** ### 🧮 Commercial Structure Unlike the standard Affiliate Program, the Broker Program does not follow a single published commission schedule for all participants. Instead, broker economics may be structured through a broker-specific commercial model agreed with AllScale. Depending on the relationship, this may include: * a defined **base settlement rate** or cost structure * the ability to set or influence the final fee offered to broker-managed merchants, subject to agreement * a broker margin or other revenue structure derived from the agreed commercial model * custom deal terms based on industry, merchant type, or expected transaction volume *** ### 🏷️ Pricing Flexibility Where applicable and approved by AllScale, brokers may have more pricing flexibility than standard affiliates. This means the broker relationship may allow the partner to: * manage merchant pricing within an approved framework * operate under negotiated commercial terms * participate in a margin-based structure rather than only a standard referral share model Pricing flexibility is not automatic and is subject to AllScale approval and the applicable broker agreement. *** ### 📊 Reporting & Visibility Approved brokers may receive access to dedicated reporting or dashboard functionality. Depending on the setup, this may include visibility into: * referred merchants * transaction volume * activity status * revenue outcomes * other broker-related operational data The exact reporting scope may vary by product readiness and broker structure. *** ### 📌 Important Notes * Broker benefits and economics are determined case by case * The Broker Program is not the same as the standard Affiliate commission model * Final commercial terms may be set out in a separate partnership agreement or direct commercial discussion with AllScale * AllScale may update broker program features, support scope, and commercial structures over time # Broker Eligibility & Approval This page explains who the AllScale Broker Program is designed for and how approval works. ### 👤 Who Is the Broker Program For? The Broker Program is intended for higher-touch partners with stronger merchant access, commercial involvement, or channel influence. This may include: * agencies * consultants * merchant aggregators * KOLs with strong merchant reach * operators with direct merchant networks * senior business connectors * organizations with recurring merchant deal flow The Broker Program is generally more suitable for partners who want a more customized structure than the standard Affiliate path. *** ### 🧾 What AllScale May Review When evaluating a broker application, AllScale may consider factors such as: * the quality of your merchant network * expected transaction volume potential * industry or vertical relevance * regional fit and compliance considerations * ability to support merchant onboarding and commercial coordination * long-term partnership potential Submission of an application does not guarantee approval. *** ### 📨 How to Apply To express interest in the Broker Program, you should contact AllScale directly through an official contact channel, relationship manager, or approved onboarding path. AllScale may request additional information to evaluate your application. Depending on the situation, this may include: * your company or professional profile * merchant network background * target merchant types or industries * expected onboarding pipeline * anticipated transaction volume * geographic focus *** ### ⏳ Approval Process Broker participation is subject to review and approval by AllScale. The approval process may include: 1. Initial outreach or application 2. Internal review by the AllScale team 3. Follow-up discussion if needed 4. Commercial alignment on the proposed broker structure 5. Final approval and onboarding into the Broker Program *** ### 🚫 Reasons Approval May Be Limited or Declined AllScale may decline or delay broker participation for reasons including but not limited to: * insufficient merchant fit * unclear or limited volume potential * unsupported region or merchant category * compliance or operational concerns * mismatch with current program scope * incomplete application information *** ### 📌 Important Notes * Broker participation is not self-serve * Approval is required before broker-specific benefits or terms apply * Continued participation may depend on ongoing compliance, merchant quality, and operational alignment * AllScale may revise broker eligibility standards over time # Broker FAQ Below are some common questions about the AllScale Broker Program. ### Program Basics #### What is the difference between the Broker Program and the Affiliate Program? The Affiliate Program is the standard referral path with a published commission schedule. The Broker Program is a more tailored partnership path that requires direct outreach, application, and approval by AllScale. #### Is the Broker Program open to everyone? No. The Broker Program is application-based and subject to approval by AllScale. #### Do brokers follow the same commission schedule as affiliates? Not necessarily. Broker economics may be customized and do not always follow the standard Affiliate commission schedule. *** ### Commercial Model #### Can brokers set their own pricing? Yes. In the standard Broker Program structure, brokers operate under a **markup-based model**. AllScale assigns the broker a **base settlement rate**, and the broker sets the final merchant-facing fee within the agreed commercial structure. The broker then keeps the **markup / spread** between the base rate and the final fee. This is one of the main differences between the Broker Program and the standard Affiliate Program. #### Do brokers receive a dedicated dashboard? Approved brokers may receive access to dedicated dashboard or reporting functionality, depending on the broker setup and product readiness. #### How are broker rewards calculated? Broker rewards are generally **markup-based**, not based on the standard Affiliate commission schedule. In a typical broker arrangement: * AllScale provides a **base settlement rate** * the broker applies a **merchant-facing fee** * the broker earns the **difference between the two** as broker revenue This allows brokers to monetize merchant relationships through fee margin rather than only through a fixed referral share. *** ### Application & Approval #### How do I join the Broker Program? You must contact AllScale directly and go through the broker application and approval process. #### What does AllScale review during approval? AllScale may review your merchant network, industry fit, expected volume, region, commercial profile, and operational suitability. #### Does applying guarantee acceptance? No. Submission of an application does not guarantee approval. *** ### Operations #### Can I start as an affiliate and later become a broker? Potentially, yes. In some cases, a partner may begin through the Affiliate Program and later discuss a broker structure with AllScale if the relationship expands. #### Are broker merchants treated the same way as affiliate-referred merchants? Not always. Merchant treatment, pricing structure, reporting, and economics may differ depending on the broker arrangement. #### Where can I ask for more details? If you are interested in the Broker Program, please reach out to the AllScale team directly through your existing relationship manager or official contact channel. # Help and Support When at doubt, don't hesitate to contact our 24/7 support ### FAQ
1. Do I need to fund my account before payroll runs? **Yes.** You must have sufficient balance **before the scheduled pay date** for payroll to be processed successfully.
2. What payment methods does AllScale support? **Currently:** Fiat via wire transfer\ **Coming soon:** Stablecoin deposits (e.g., USDT, USDC)
3. What happens if I forget to approve payroll? Payroll will remain in **draft** and will not be processed. AllScale will remind you 48 hours before the due date.
4. How do I fix a failed payroll due to insufficient funds? Top up your account and click **“Retry”** in the Payroll tab. AllScale will attempt to reprocess it automatically.
5. Can I edit a team member’s info or wallet address? Not yet. This feature is coming soon. In the meantime, contact the AllScale team to request updates.
6. How will I know if something goes wrong with payroll or deposits? You’ll receive an **instant notification** via email and your AllScale dashboard with guidance on how to resolve it.
7. Where can I download payroll invoices and receipts? Go to the **Payroll** tab. * Upcoming payrolls = **Download Invoice** * Completed payrolls = **Download Receipt**
8. Can employees be paid on different schedules? **No.** All employees are included in a **single company-wide payroll cycle**.\ This means everyone is paid on the **same schedule**, rather than individually or on-demand.\ This helps ensure consistency, simplifies processing, and prevents payment delays.
Don't see your question? email: and let us help you. # Change log **Jul 21, 2026** Added API Doc pages covering Claim Link Routes and Webhooks **May 14, 2026** Updated Checkout API doc - Get Status **May 7, 2026** Updated Checkout doc for AI reading and Quick Start with Postman doc **May 5, 2026** Updated Checkout API doc for supporting USDC **May 5, 2026** Updated Checkout - Getting Started guide for One-Click Setup with AI **April 22, 2026** * Updated API docs for USDT checkout intent and related webhooks **April 21, 2026** * Added a new AllScale Partner Program section as a standalone documentation track, parallel to Checkout, Pay, and Payroll. **March 25, 2026** * Updated product overview descriptions for Payroll, Invoicing, Checkout, and Wallet. **March 13, 2026** * Restructured AllScale Checkout documentation: reorganized all pages under the Checkout section with dedicated entries for Getting Started, Integration Flow, and a full suite of API Docs * Added API Doc pages covering key Checkout flows: Test Route, Auth, Webhook Signing & Payload Guide, Checkout Intent Routes (Get Status / Create Checkout Intent / Get Checkout Intent), and Optional Response Signing **September 29, 2025** * Published comprehensive FAQ covering Account Registration, Wallet Features, and Invoice Features * Added PASSKEY registration troubleshooting guide with platform-specific solutions and known limitations **June 4, 2025** * Added initial introduction to the AllScale team * Published initial overview of the Payroll product * Included detailed walkthrough of the Payroll platform and its key functionalities **July 6, 2025** * Applied minor optimizations and UI enhancements * Released documentation explanations and usage guidelines