UPTICK Micropayment (x402 Facilitator) API Documentation

Authentication

All Micropayment APIs require a project API Key. Example format: upt_xxxxxxxxxxxxxxxx.

Option 1: Request Header (Recommended)

Option 2: Query Parameter

Rule	Description
Key type	Must be a Micropayment (facilitator) project key
Query name	Fixed as `apiKey`; used for gateway auth only

Apifox Setup

Open Environment Management and add variable apiKey.

In Auth or global Headers, set x-api-key = {{apiKey}}.

Alternatively, add apiKey = {{apiKey}} as a query parameter on each request.

General Conventions

Request Format

Encoding: UTF-8

POST / PUT bodies are typically application/json (Webhook and other cases follow Facilitator requirements)

Optional: send X-Request-ID for tracing (forwarded upstream)

Response Format

Type	Description
Business success	HTTP status and JSON body from Facilitator
Gateway error	HTTP 4xx/5xx with UPTICK gateway JSON (see Error Codes)

Forwarded Headers

Header	Purpose
`Accept`	Content negotiation
`Content-Type`	Request body type
`X-Request-ID`	Request trace ID
`X-Webhook-Signature`	Webhook signature verification

Billing

Fees are deducted from the developer account Gas balance (UPTICK).

Pricing

Endpoint	Condition	Price (UPTICK/call)
`POST /verify`	Standard verify	0.00002
`POST /verify`	`paymentPayload.payload.type` = `voucher`	0.0008
`POST /settle`	—	0.002
Other endpoints	health, supported, webhook, payer-quota, orders	No per-call fee

Voucher Detection

For verify requests, type is resolved in this order:

paymentPayload.payload.type (x402 v2 standard, recommended)

Top-level type (legacy compatibility)

When the value is voucher (case-insensitive), the 0.0008 rate applies.

Balance Requirements

Endpoint type	Minimum balance
`verify` / `settle`	≥ fee for that call
Other endpoints	≥ 0.1 UPTICK (platform minimum)

Billing occurs only after the upstream returns HTTP 2xx.

Error Codes

Gateway Errors (Returned by UPTICK)

HTTP	error	Description	Action
401	`UNAUTHORIZED`	Missing/invalid API Key, or non-micropayment project key	Check key and project type
402	`INSUFFICIENT_GAS_BALANCE`	Insufficient Gas balance	Top up and retry
404	`NOT_FOUND`	Unknown gateway path	Check URL
429	`RATE_LIMITED`	Exceeded per-minute limit	Reduce rate or request higher quota
503	`FACILITATOR_UNAVAILABLE`	Micropayment service unavailable	Retry later
502	—	Upstream timeout or connection failure	Retry later

402 Response Example

{
  "error": "INSUFFICIENT_GAS_BALANCE",
  "message": "Insufficient gas balance for x402 call",
  "requiredFee": 0.0008,
  "currentBalance": 0.05
}

401 Response Example

{
  "error": "UNAUTHORIZED",
  "message": "Invalid API key or wrong project type (requires type=facilitator)"
}

Business Errors (Returned by Facilitator)

When verify/settle or other business calls fail, status codes and bodies are defined by Facilitator (often 400 / 422). The gateway does not charge for non-2xx upstream responses.

API Index

Group	Gateway Path	Method	Billable
Basics	`/health`	GET	No
Basics	`/supported`	GET	No
x402 Core	`/verify`	POST	Yes
x402 Core	`/settle`	POST	Yes
Webhook	`/webhook/config`	POST	No
Webhook	`/webhook/config`	GET	No
Webhook	`/webhook/config/{merchantId}`	GET	No
Webhook	`/webhook/events`	GET	No
Webhook	`/webhook/test`	POST	No
Webhook	`/webhook/receive`	POST	No
Payer Quota	`/payer-quota/signing-domain`	GET	No
Payer Quota	`/payer-quota`	POST	No
Payer Quota	`/payer-quota`	GET	No
Payer Quota	`/payer-quota/history`	GET	No
Payer Quota	`/payer-quota`	DELETE	No
Orders	`/orders`	GET	No
Orders	`/orders/{orderId}`	GET	No

Endpoint Details

1. Health Check

Check whether the Facilitator service is available.

Response: Facilitator /health response (typically 200).

2. Supported

Query supported x402 capabilities (scheme, network, etc.).

Response: Facilitator /supported response.

3. Verify

Verify an x402 payment payload; a core step in the micropayment flow.

Billing

Condition	Price
`paymentPayload.payload.type` = `voucher`	0.0008 UPTICK
Other	0.00002 UPTICK

Request Body (voucher example)

{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "accepted": {
      "scheme": "batch-settlement",
      "network": "eip155:1170"
    },
    "payload": {
      "type": "voucher",
      "channelConfig": {
        "payer": "0x20fa255492c0c5fe5b6e9513ad4dc565d72ed885",
        "payerAuthorizer": "0x20fa255492c0c5fe5b6e9513ad4dc565d72ed885",
        "receiver": "0x5a08f46b5c6c5c25a58cd12f51ebe3ffadb67f56",
        "receiverAuthorizer": "0xd7df9727cac53059832607a6ad4b25feb6fd04ff",
        "token": "0x5b7cdc0de74e158eac21d1d054bc25d0ad56b773",
        "withdrawDelay": 900,
        "salt": "0x0000000000000000000000000000000000000000000000000000000000000000"
      },
      "voucher": {
        "channelId": "0x28e7764ab6408119c3e086e98a7a6582564d151d4334962c9b51c5b15695dd0b",
        "maxClaimableAmount": "1100",
        "signature": "0x4ce01ae20e04dcb525e333b28211a22e38f92e345223fa22a9d5887f786f6dee13d0e819d9b8887281304e5254de5494ebdbbea26da6fdc89c01b9c79583db491b"
      }
    }
  },
  "paymentRequirements": {
    "scheme": "batch-settlement",
    "network": "eip155:1170",
    "asset": "0x5b7cdc0de74e158eac21d1d054bc25d0ad56b773",
    "amount": "10",
    "payTo": "0x5a08f46b5c6c5c25a58cd12f51ebe3ffadb67f56",
    "maxTimeoutSeconds": 3600,
    "extra": {
      "withdrawDelay": 900,
      "receiverAuthorizer": "0xd7df9727cac53059832607a6ad4b25feb6fd04ff"
    }
  }
}

Response: Facilitator verification result (2xx → charged; 4xx/5xx → not charged).

curl

4. Settle

Execute x402 settlement.

Billing: 0.002 UPTICK per call (charged after upstream 2xx).

Request body: JSON per Facilitator settle protocol (see Facilitator documentation).

Response: Facilitator settlement response.

curl

5. Webhook

Gateway	Method	Upstream	Description
`/webhook/config`	POST	`/api/v1/webhook/config`	Configure Webhook
`/webhook/config`	GET	`/api/v1/webhook/config`	List all configs
`/webhook/config/{merchantId}`	GET	`/api/v1/webhook/config/{merchantId}`	Get config by merchant
`/webhook/events`	GET	`/api/v1/webhook/events`	List supported event types
`/webhook/test`	POST	`/api/v1/webhook/test`	Send test notification
`/webhook/receive`	POST	`/api/v1/webhook/receive`	Debug receive endpoint

Example: Configure Webhook

Example: Receive Callback

6. Payer Quota

Gateway	Method	Upstream	Description
`/payer-quota/signing-domain`	GET	`/api/v1/payer-quota/signing-domain`	Query: `network`
`/payer-quota`	POST	`/api/v1/payer-quota`	Register/update quota
`/payer-quota`	GET	`/api/v1/payer-quota`	Query: `payer`, `network`
`/payer-quota/history`	GET	`/api/v1/payer-quota/history`	Query: `payer`, `network?`
`/payer-quota`	DELETE	`/api/v1/payer-quota`	Query: `payer`, `network`

Example: Get Signing Domain

Example: Register Quota

7. Micropayment Orders

Gateway	Method	Upstream	Description
`/orders`	GET	`/api/v1/micropayment/orders`	Paginated list; Query: `payer`/`payTo` (at least one), `recordType`, `network`, `status`, `page`, `pageSize`
`/orders/{orderId}`	GET	`/api/v1/micropayment/orders/{orderId}`	Order detail

Example: List Orders

Example: Get Order Detail

The Facilitator orders module provides read-only APIs; there is no create-order POST.

FAQ

Q: Where do I get an API Key?
A: Log in to the UPTICK Developer Console → create a Micropayment project → copy the API Key. Keep it secret; do not commit it to public repositories.

Q: Why was verify charged 0.00002 instead of 0.0008?
A: Confirm that paymentPayload.payload.type in your JSON is "voucher".

Q: Am I charged when the response is 400?
A: No. Only upstream HTTP 2xx triggers billing.

Q: How do I top up Gas balance?
A: Use the recharge feature in the Developer Console to transfer UPTICK to the platform address, or contact an administrator for manual credit.

Q: Can I use the same API Key in test and production?
A: Usually not. Create separate projects per environment and use the matching key.

Apifox Import

File	Purpose
`micropayment-api-external.en.md`	Copy into Apifox Docs, or use as team reference
`micropayment-openapi.en.yaml`	Apifox → Import → OpenAPI to generate APIs and mocks

After importing OpenAPI, set environment variables:

baseUrl: e.g. https://developapi.testweb.uptick.network/v1/x402

apiKey: your Micropayment project key

Bind auth: x-api-key: {{apiKey}}.

Revision History

Version	Date	Notes
v1.0	2026-05	Initial release: auth, billing, errors, x402 / Webhook / Payer Quota / Orders

UPTICK Micropayment (x402 Facilitator) API Documentation

Authentication#

Option 1: Request Header (Recommended)#

Option 2: Query Parameter#

Apifox Setup#

General Conventions#

Request Format#

Response Format#

Forwarded Headers#

Billing#

Pricing#

Voucher Detection#

Balance Requirements#

Error Codes#

Gateway Errors (Returned by UPTICK)#

Business Errors (Returned by Facilitator)#

API Index#

Endpoint Details#

1. Health Check#

2. Supported#

3. Verify#

4. Settle#

5. Webhook#

6. Payer Quota#

7. Micropayment Orders#

FAQ#

Apifox Import#

Revision History#