API Reference

Interact with the Crypax REST API to create and manage payments, customers, and refunds. All requests must be made over HTTPS.

Base URL

https://api.crypax.io

Authentication

Crypax uses two API key types. Include the appropriate key as a request header.

Header	Key type	Usage
`X-Secret-Key`	Secret Key	Server-side only. Create/read payments, manage customers, refunds. Prefix: `sk_live_`
`X-Publishable-Key`	Publishable Key	Safe for browser. Read-only public data (chains, tokens). Prefix: `pk_live_`

Example request

POST /v1/payments HTTP/1.1
Host: api.crypax.io
X-Secret-Key: sk_live_your_secret_key
Content-Type: application/json

Webhook Signature Format

Webhook requests include three headers for verification. The signature covers both the timestamp and raw body to prevent replay attacks.

Header	Format
`X-Crypax-Signature`	`v1={HMAC-SHA256(timestamp.rawBody, secret)}`
`X-Crypax-Event`	Event type string, e.g. `payment.confirmed`
`X-Crypax-Timestamp`	Unix timestamp (seconds) — reject if older than 5 minutes

Endpoints

POST/v1/paymentsSecret Key

Create payment

Creates a new payment. Returns a clientSecret that the frontend SDK uses to confirm the payment. Set qrMode: true to skip wallet selection and show a QR code directly.

Request body

{
  "amount": "10.00",
  "chainId": 41956,
  "currency": "native",
  "recipientAddress": "0xYourWalletAddress",
  "description": "Pro Plan",
  "metadata": { "userId": "user_123" },
  "qrMode": false
}

Response

{
  "id": "pay_01HZ...",
  "clientSecret": "cs_live_...",
  "status": "created",
  "amount": "10.00",
  "currency": "native",
  "chainId": 41956,
  "recipientAddress": "0x...",
  "description": "Pro Plan",
  "expiresAt": "2024-01-01T00:30:00.000Z",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

GET/v1/payments/:idSecret Key

Get payment

Retrieves a payment by its ID.

Response

{
  "id": "pay_01HZ...",
  "status": "confirmed",
  "txHash": "0xabcdef1234...",
  "blockNumber": 12345,
  "amount": "10.00",
  "currency": "native",
  "chainId": 41956,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "confirmedAt": "2024-01-01T00:02:31.000Z"
}

GET/v1/paymentsSecret Key

List payments

Returns a paginated list of payments. Optional query params: status, page, limit.

Response

{
  "data": [
    {
      "id": "pay_01HZ...",
      "status": "confirmed",
      "amount": "10.00",
      "currency": "native",
      "chainId": 41956,
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

POST/v1/customersSecret Key

Create customer

Creates a new customer record linked to a wallet address.

Request body

{
  "walletAddress": "0x...",
  "email": "user@example.com",
  "displayName": "Alice",
  "metadata": { "plan": "pro" }
}

Response

{
  "id": "cust_01HZ...",
  "walletAddress": "0x...",
  "email": "user@example.com",
  "displayName": "Alice",
  "metadata": { "plan": "pro" },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

GET/v1/customers/:idSecret Key

Get customer

Retrieves a customer by ID.

Response

{
  "id": "cust_01HZ...",
  "walletAddress": "0x...",
  "displayName": "Alice",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

GET/v1/customersSecret Key

List customers

Returns a paginated list of customers. Optional query params: page, limit.

Response

{
  "data": [{ "id": "cust_01HZ...", "displayName": "Alice" }],
  "total": 10,
  "page": 1,
  "limit": 20
}

PUT/v1/customers/:idSecret Key

Update customer

Updates a customer's displayName or metadata.

Request body

{
  "displayName": "Bob",
  "metadata": { "plan": "enterprise" }
}

Response

{
  "id": "cust_01HZ...",
  "displayName": "Bob",
  "metadata": { "plan": "enterprise" }
}

DELETE/v1/customers/:idSecret Key

Delete customer

Deletes a customer record.

Response

{ "deleted": true, "id": "cust_01HZ..." }

POST/v1/refundsSecret Key

Create refund

Initiates a refund for a confirmed payment. Omit amount for a full refund.

Request body

{
  "paymentId": "pay_01HZ...",
  "amount": "5.00",
  "reason": "Customer request"
}

Response

{
  "id": "refund_01HZ...",
  "paymentId": "pay_01HZ...",
  "amount": "5.00",
  "status": "created",
  "reason": "Customer request",
  "createdAt": "2024-01-01T01:00:00.000Z"
}

GET/v1/refunds/:idSecret Key

Get refund

Retrieves a refund by ID.

Response

{
  "id": "refund_01HZ...",
  "paymentId": "pay_01HZ...",
  "amount": "5.00",
  "status": "completed",
  "txHash": "0x...",
  "createdAt": "2024-01-01T01:00:00.000Z"
}

GET/v1/refundsSecret Key

List refunds

Returns a paginated list of refunds. Optional query params: paymentId, page, limit.

Response

{
  "data": [{ "id": "refund_01HZ...", "status": "completed", "amount": "5.00" }],
  "total": 3,
  "page": 1,
  "limit": 20
}

GET/v1/projects/meSecret Key

Get project

Retrieves the current project settings.

Response

{
  "id": "proj_01HZ...",
  "name": "My Store",
  "callbackUrl": "https:0
  5: ["https://my-store.com"],
  "brandingConfig": { "primaryColor": "#8B5CF6" }
}

PUT/v1/projects/meSecret Key

Update project

Updates project name, branding, allowed origins, or callback URL.

Request body

{
  "name": "My Store",
  "callbackUrl": "https:0
  4: ["https://my-store.com"],
  "brandingConfig": { "primaryColor": "#8B5CF6" }
}

Response

{
  "id": "proj_01HZ...",
  "name": "My Store",
  "callbackUrl": "https://my-store.com/api/crypax/callback"
}

GET/v1/chainsPublishable Key

List supported chains

Returns all blockchain networks supported by Crypax.

Response

[
  {
    "chainId": 41956,
    "name": "Plumise Mainnet",
    "symbol": "PLM",
    "rpcUrl": "https:0
    6: "https://explorer.plumise.com",
    "isTestnet": false
  }
]

GET/v1/chains/:chainId/tokensPublishable Key

List chain tokens

Returns all ERC-20 tokens supported for payment on a specific chain.

Response

[
  {
    "symbol": "USDC",
    "name": "USD Coin",
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "decimals": 6,
    "chainId": 41956
  }
]

POST/v1/auth/authonSecret Key

Authon SSO callback

Exchanges an Authon SSO token for a Crypax session. Used for projects that authenticate users via Authon.

Request body

{
  "token": "authon_sso_token_..."
}

Response

{
  "sessionToken": "sess_...",
  "expiresAt": "2024-01-02T00:00:00.000Z"
}

Error Responses

All errors return a consistent JSON shape with an HTTP status code in the 4xx–5xx range.

Error example

{
  "statusCode": 401,
  "message": "Invalid or missing API key",
  "error": "Unauthorized"
}

Quick Start →Webhook Guide →Node.js SDK →