REST API Reference

The complete U.CASH Pay merchant API: one HTTPS POST endpoint, form-encoded, dispatched by a function parameter. Everything the console does is available here.

How the API works#

Every call is an HTTPS POST, form-encoded, carrying a function parameter that selects the operation. There are four surfaces:

Surface	URL	Use
Main API	`https://pay.u.cash/api.php`	Console operations: transactions, checkouts, rates, settings
Payment API	`https://pay.u.cash/payment/api.php`	Payment-surface operations
Cloud API	`https://pay.u.cash/cloud/api.php`	Cloud/store operations
AJAX API	`https://pay.u.cash/payment/ajax.php`	Buyer checkout creation with a Cloud Token (public, no API key)

Authentication#

Authenticate with your API key in the X-Api-Key header - preferred over a POST field because it stays out of access logs. An api-key POST field is also accepted; the header wins when both are sent.

X-Api-Key: YOUR_API_KEY

Get your key from Settings in the console.

Two credentials, two jobs

The API key is a server-side secret: it can read transactions, change settings, and issue refunds. The store Cloud Token is the publishable credential for buyer-facing embeds and payment links. Never confuse the two - the Cloud Token can only create checkouts, and that is by design.

Function reference#

All functions dispatch on the main API (https://pay.u.cash/api.php) unless noted:

Function	Key parameters	Purpose
`create-transaction`	`amount`, `cryptocurrency_code`	Create a checkout or invoice
`invoice` / `payment-link`	`transaction_id`	Get a shareable payment URL
`get-transaction` / `get-transactions` / `download-transactions`	`transaction_id`	Status, history, exports
`check-transaction` / `check-transactions`	`transaction` / `transaction_id`	Force a re-scan of pending payments
`update-transaction` / `delete-transaction`	`transaction_id` (+ `values`)	Edit or remove records
`save-checkout` / `get-checkouts` / `delete-checkout`	`checkout` / `checkout_id`	Manage saved payment links
`get-fiat-value`	`amount`, `cryptocurrency_code`, `currency_code`	Price a coin amount in fiat
`get-exchange-rates` / `get-usd-rates`	`currency_code`, `cryptocurrency_code`	Rate lookups
`vat` / `vat-validation`	`amount` / `vat_number`	Tax computation, VAT number checks (see VAT & Sales Tax)
`get-cryptocurrency-codes` / `get-custom-tokens`	-	Supported coins and custom tokens
`get-settings` / `save-settings`	`settings` (JSON)	Read and write settings
`get-balances`, `encryption`, `settings-get-address`	-	Utilities
`get-cloud-token`	-	Retrieve the publishable store Cloud Token
`refund`	`transaction_id`	Refund a payment (requires the refunds capability)

Two special calls: GET /api.php?cron with the X-Api-Key header runs scheduled maintenance (used by the platform's own cron), and function=test-connection authenticates with the Cloud Token instead of an API key - see Testing.

Creating payments#

create-transaction makes a checkout or invoice; invoice / payment-link returns the shareable URL for an existing transaction:

curl https://pay.u.cash/api.php \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d function=create-transaction \
  -d amount=25.00 \
  -d cryptocurrency_code=

For saved, branded payment links you manage over time, use save-checkout (see Embed, API & SDKs for the embed side and Invoicing for the invoice flow).

Buyer-side creation (public)#

POST https://pay.u.cash/payment/ajax.php with function=create-transaction, amount, currency_code, and your Cloud Token in cloud creates a hosted checkout with no API key - this is exactly what the payment button and Add Funds embeds use. The Cloud Token is the credential for this surface; it can only create checkouts.

Response format#

Every response is JSON with a consistent envelope:

success: { "success": true,  "response": { ... } }
error:   { "success": false, "error_code": "invalid-api-key", "message": "..." }

Branch on error_code, never on message

The message is prose for humans and can change; error_code is the stable contract. Authentication failures return HTTP 401 with api-key-not-found or invalid-api-key.

Transaction statuses#

Status	Meaning
`P`	Pending
`C`	Completed - the webhook fires
`X`	Rejected (for example an underpayment below the acceptance threshold; no webhook)

Testing#

Testnets: enable testnet mode in the console and run end-to-end tests on Bitcoin and EVM testnets without real funds (see Testnets)
Webhook handler: call function=test-connection with the Cloud Token - it sends a genuine signed test delivery to your webhook URL and reports the HTTP status, response body, and whether the signature verified (see Webhooks)

Machine payments: the agents API#

Building for AI agents or x402 machine payments? That is a separate API at agents.u.cash with JSON bodies, per-key rate limits, and idempotent creates. Its full reference - every endpoint, parameter, and response - is browsable at agents.u.cash/reference, with machine-readable twins at openapi.json and llms.txt. See Agents & x402 for the platform overview.

Getting help#

Stuck? Open a support ticket from the console (Help → Support), or start with Troubleshooting.