User API

The User API is called by the checkout frontend running in the user's browser. All requests require a signed checkout URL generated by your application backend.

Base path: /api/v1/user
Authentication: Ocrch-Signed-Url + Ocrch-Signature headers — see Authentication

Every User API request must include these two headers:

Header	Value
`Ocrch-Signed-Url`	The full checkout URL that was signed by your backend
`Ocrch-Signature`	`{timestamp}.{base64_hmac}` computed over the URL

Endpoints

`GET /chains`

List all available chain/coin pairs (based on your wallet configuration).

No request body.

Response — 200 OK:

[
  {
    "blockchain": "eth",
    "stablecoin": "USDT",
    "wallet_address": "0xYourEthereumWalletAddress"
  },
  {
    "blockchain": "eth",
    "stablecoin": "USDC",
    "wallet_address": "0xYourEthereumWalletAddress"
  },
  {
    "blockchain": "tron",
    "stablecoin": "USDT",
    "wallet_address": "TYourTronWalletAddress"
  }
]

Each element represents one selectable payment option. Display these to the user so they can choose how to pay.

Field	Type	Description
`blockchain`	string	Chain identifier (see blockchain identifiers)
`stablecoin`	string	Stablecoin identifier (`"USDT"`, `"USDC"`, `"DAI"`)
`wallet_address`	string	Receiving wallet address for this chain

`POST /orders/{order_id}/payment`

Select a payment method (chain + stablecoin) for an order. Creates a pending deposit and returns the wallet address and expected amount.

Path parameter: order_id — the Ocrch order UUID.

Request headers:

Header	Value
`Content-Type`	`application/json`
`Ocrch-Signed-Url`	Signed checkout URL
`Ocrch-Signature`	`{timestamp}.{base64_hmac}`

Request body:

{
  "blockchain": "eth",
  "stablecoin": "USDT"
}

Field	Type	Required	Description
`blockchain`	string	Yes	Chain to pay on.
`stablecoin`	string	Yes	Coin to pay with.

Response — 201 Created:

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "wallet_address": "0xYourEthereumWalletAddress",
  "amount": "19.99",
  "blockchain": "eth",
  "stablecoin": "USDT"
}

Field	Type	Description
`order_id`	UUID string	Internal order ID
`wallet_address`	string	Address the user must send funds to
`amount`	decimal string	Exact amount the user must send
`blockchain`	string	Selected chain
`stablecoin`	string	Selected stablecoin

Error responses:

Status	Body	Cause
`404 Not Found`	`order not found`	Order UUID does not exist
`409 Conflict`	`order is not pending`	Order already paid, expired, or cancelled
`400 Bad Request`	`no wallet available for the selected chain and coin`	No configured wallet supports this combination
`400 Bad Request`	`invalid blockchain selection`	Chain value unrecognized

`POST /orders/{order_id}/cancel`

Cancel an order. Only pending orders can be cancelled.

Path parameter: order_id — the Ocrch order UUID.

Request headers:

Header	Value
`Ocrch-Signed-Url`	Signed checkout URL
`Ocrch-Signature`	`{timestamp}.{base64_hmac}`

No request body.

Response — 200 OK (empty body on success).

Error responses:

Status	Body	Cause
`404 Not Found`	`order not found`	Order UUID does not exist
`409 Conflict`	`order is not pending`	Order already in terminal state

`GET /orders/{order_id}/status`

Poll the current status of an order.

Path parameter: order_id — the Ocrch order UUID.

Response — 200 OK:

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_order_id": "your-order-reference-123",
  "amount": "19.99",
  "status": "pending",
  "created_at": 1711900800
}

Use this as a fallback when WebSocket connections are not available.

`GET /orders/{order_id}/ws`

Upgrade to a WebSocket connection and receive real-time order status updates.

Path parameter: order_id — the Ocrch order UUID.

Authentication: The Ocrch-Signed-Url and Ocrch-Signature headers must be sent during the HTTP upgrade request.

WebSocket Protocol

Immediately after upgrade, the server sends a status_update frame with the current order state.
Subsequent status_update frames are sent whenever the order status changes.
After a terminal status (paid, expired, cancelled) the server sends a close frame with code 1000.

Server Message Format

Messages are JSON text frames:

Status update:

{
  "type": "status_update",
  "order": {
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "merchant_order_id": "your-order-reference-123",
    "amount": "19.99",
    "status": "pending",
    "created_at": 1711900800
  }
}

Error (non-closing):

{
  "type": "error",
  "code": 4004,
  "reason": "order not found"
}

WebSocket Close Codes

Code	Meaning
`1000`	Normal closure — terminal status delivered
`1011`	Internal server error
`4004`	Order not found

Client Example (Node.js)

import WebSocket from "ws";

const ws = new WebSocket(
  `wss://checkout-api.example.com/api/v1/user/orders/${orderId}/ws`,
  {
    headers: {
      "Ocrch-Signed-Url": signedUrl,
      "Ocrch-Signature": signature,
    },
  }
);

ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.type === "status_update") {
    console.log("Order status:", msg.order.status);
  }
});

ws.on("close", (code) => {
  console.log("WebSocket closed with code:", code);
});

Order Status Values

Value	Meaning
`"pending"`	Awaiting payment
`"paid"`	Payment confirmed on-chain
`"expired"`	Timed out before payment
`"cancelled"`	Cancelled by user or merchant