API Reference

Complete REST API documentation for the GullyPay platform. All endpoints use JSON request and response bodies.

Base URL

All API requests are made to:

https://gullypay.xyz/api

For sandbox/testing:

https://gullypay.xyz/api

Authentication

Include your API key or JWT token in the Authorization header of every request:

Authorization: Bearer rk_live_your_api_key

Two authentication methods are available:

Rate Limiting

All API endpoints are rate-limited to protect service stability.

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1718928000

When a rate limit is exceeded, the API returns HTTP 429 Too Many Requests.

Request Format

• All request bodies must be valid JSON with Content-Type: application/json
• Amounts are in the smallest currency unit (cents for USD, pence for GBP)
• Resource ids in paths are UUIDs (e.g. 3f2b8c1e-5d4a-4e7b-9c1a-2b6d8e0f4a11). A path id that is not a valid UUID returns 404 Not Found, not 500
• Timestamps are ISO 8601 format: 2025-06-09T12:00:00Z

Error Codes

All errors follow a consistent format:

{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request",
"details": [
  { "field": "amount", "message": "amount must be at least 1" }
]
}

Authentication

POST /auth/register

{
"email": "[email protected]",
"password": "secure-password-123",
"firstName": "Jane",
"lastName": "Doe"
}

POST /auth/login

{
"email": "[email protected]",
"password": "secure-password-123"
}

{
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "rt_a1b2c3d4..."
}

DELETE /auth/me

Closes the signed-in account. Used by Settings > Security, gullypay.xyz/account/delete and the mobile apps.

{
"password": "secure-password-123",
"code": "123456"
}

Errors: 401 INVALID_PASSWORD, 401 REAUTH_REQUIRED (no password and the session is older than 5 minutes), 401 MFA_REQUIRED, and 409 ACCOUNT_DELETION_BLOCKED with a blockers array while money is still moving or held. Deletion never strands funds; it waits while:

• the user is the only owner of a business with a payout in progress (payouts_in_flight), an unpaid stablecoin / x402 balance (merchant_balance_owed), a checkout that can still be paid (open_checkouts) or an open dispute (open_disputes);
• the user's embedded wallet holds stablecoins or more than 0.001 of the native gas token (wallet_balance), its balance cannot be read (wallet_unverified, fail-closed), or the internal glUSD balance is not zero (internal_balance).

Each blocker has a detail and the action that clears it. On success (200):

{
"deleted": true,
"closedAt": "2026-10-26T10:00:00.000Z",
"merchantsClosed": ["4b1d…"],
"retention": [{ "data": "Email, name, password hash, 2FA secret", "onDeletion": "anonymised", "period": "Immediately", "why": "…" }]
}

In one transaction the user's email, name, password hash and 2FA secret are anonymised; sessions, passkeys, push devices and team memberships are deleted; the user's API keys are revoked; wallets are frozen (status: frozen, encrypted key kept for recovery); businesses the user solely owned are closed with their API keys revoked and webhooks disabled; an account.deleted audit entry is written; and a confirmation email goes to the old address. Payment, ledger, payout and audit records are kept for 7 years and support tickets for 2 years, linked only to the anonymous user id (see the privacy policy).

Push devices (mobile apps)

/notifications/devices is accepted as an alias of /me/devices.

{
"token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
"platform": "ios",
"app": "consumer",
"deviceName": "Ada's iPhone"
}

A token is unique: registering it again refreshes it, and registering it from another account moves it to that account. Pushes go through the Expo push service and are sent only when the API runs with PUSH_NOTIFICATIONS_ENABLED=true (EXPO_ACCESS_TOKEN is optional, for Expo enhanced push security):

Every team member of the business gets merchant pushes. Each push is claimed once per user and event (payment:<transactionId>, payout:<id>, …), so the same payment reported by the checkout page and the Stripe webhook notifies once. Tokens Expo reports as DeviceNotRegistered are deleted.

Merchants

POST /merchants

{
"name": "Acme Electronics",
"slug": "acme-electronics",
"businessType": "company",
"country": "US"
}

POST /merchants/:id/team/members

{
"userId": "usr_abc123",
"role": "admin"
}

Available roles: owner, admin, manager, member, viewer.

Payments

POST /payments/intents

{
"amount": 2499,
"currency": "USD",
"storeId": "store_abc123",
"merchantId": "merch_xyz789",
"customerEmail": "[email protected]",
"idempotencyKey": "order_12345"
}

POST /payments/:id/refund

{
"amount": 1000,
"reason": "Customer requested refund"
}

Payouts

POST /merchants/:merchantId/payouts

{
"amount": 50000,
"currency": "USD",
"destination": "ba_ext_bank_account_id"
}

Checkout

POST /checkout/hosted/:storeId

Requires x-api-key: rk_… (scope checkout:write if the key is scoped), a dashboard JWT, or X-Checkout-Token: ct_…. See Checkout.

{
"amount": 4999,
"currency": "USD",
"successUrl": "https://yoursite.com/success",
"cancelUrl": "https://yoursite.com/cancel"
}

{
"sessionId": "3f2b8c1e-9a4d-4e7b-8c21-0d5e6f7a8b9c",
"checkoutUrl": "https://checkout.gullypay.xyz/3f2b8c1e-9a4d-4e7b-8c21-0d5e6f7a8b9c",
"expiresAt": "2026-10-25T13:00:00.000Z"
}

Payment Links

POST /merchants/:merchantId/payment-links

{
"amount": 1999,
"currency": "USD",
"storeId": "store_abc123",
"description": "Premium Plan - Monthly"
}

Products

POST /stores/:storeId/products

{
"title": "Wireless Headphones Pro",
"description": "Premium noise-canceling wireless headphones",
"type": "physical",
"price": 14999,
"sku": "WHP-001",
"status": "active"
}

Orders

POST /stores/:storeId/orders

{
"customerId": "cust_abc123",
"items": [
  { "variantId": "var_xyz789", "quantity": 2 },
  { "variantId": "var_def456", "quantity": 1 }
],
"currency": "USD"
}

Wallets

POST /wallets/:id/send

{
"toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD38",
"amount": 100.50,
"currency": "USDC"
}

POST /wallets/:id/swap

{
"fromToken": "USDC",
"toToken": "glUSD",
"amount": 500
}

x402

See the dedicated x402 Protocol page for full documentation.

Coupons & Collections

POST /stores/:storeId/coupons

{
"code": "SUMMER2025",
"type": "percentage",
"value": 20,
"usageLimit": 100,
"minOrderAmount": 5000
}

Public Stats and Health

These endpoints need no authentication and return no personal data.

GET /public/stats

Platform-wide totals and daily series for the last days days. days is 7, 30 or 90; any other value falls back to 30. Results are cached for 60 seconds (Cache-Control: public, max-age=30, stale-while-revalidate=60) and the endpoint allows 120 requests per minute per IP.

{
"generatedAt": "2026-10-26T12:00:00.000Z",
"windowDays": 30,
"totals": {
  "merchants": 42, "stores": 57, "payments": 1310, "volumeCents": 8423100,
  "checkoutSessions": 1688, "checkoutCompleted": 1204,
  "x402Endpoints": 18, "x402Payments": 9120, "x402Settlements": 9101, "paymentLinks": 73
},
"daily": [
  { "date": "2026-10-25", "volumeCents": 312000, "payments": 48, "x402Payments": 301,
    "newMerchants": 2, "checkoutSessions": 61, "glusdMintedCents": 0, "glusdRedeemedCents": 0 }
],
"chainMix": [{ "network": "gully-chain-testnet", "label": "Gully Chain", "payments": 12 }],
"railMix": [{ "rail": "crypto", "label": "Stablecoin", "payments": 230, "volumeCents": 1250000 }],
"glusd": { "supplyCents": 0, "mintedCents": 0, "redeemedCents": 0, "pendingMints": 0, "holders": 0 },
"uptime": { "uptimePct": 100, "p50Ms": 2, "p95Ms": 5, "intervalMs": 60000, "since": "…", "samples": [] },
"networks": [
  { "network": "gully-chain-testnet", "label": "Gully Chain", "chainId": 485590, "enabled": true },
  { "network": "base", "label": "Base", "chainId": 8453, "enabled": true },
  { "network": "ethereum", "label": "Ethereum", "chainId": 1, "enabled": true },
  { "network": "bsc", "label": "BSC", "chainId": 56, "enabled": true },
  { "network": "solana", "label": "Solana", "chainId": null, "enabled": true },
  { "network": "base-sepolia", "label": "Base Sepolia", "chainId": 84532, "enabled": true }
],
"fees": { "…": "the published fee schedule" }
}

chainMix lists every supported network, zeros included. In networks, Gully Chain Testnet has enabled: false while the API runs without GULLY_CHAIN_ENABLED=true.

GET /health/ready

For load balancers and deploy checks. Returns 200 with "status": "ready" when Postgres answers, and 503 with "status": "not_ready" when it does not.

{ "status": "ready", "ready": true, "database": true, "latencyMs": 2, "timestamp": "2026-10-26T12:00:00.000Z" }

GET /health/history

Real database probe results since this API process started: one probe every 60 seconds, the last 24 hours kept. uptimePct, p50Ms, p95Ms and since are null before the first probe.

{
"samples": [{ "t": 1793016000000, "ok": true, "latencyMs": 2 }],
"uptimePct": 100,
"p50Ms": 2,
"p95Ms": 4,
"intervalMs": 60000,
"since": "2026-10-26T08:00:00.000Z"
}

Webhooks

Subscriptions & delivery monitoring

See the dedicated Webhooks page for event types, payload formats, and verification.