API Documentation

Complete reference for integrating Proton Pay into your application. All client endpoints require JWT Bearer authentication.

Authentication

Obtain a JWT token via /auth/login, then include it in every request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

Access tokens expire after 15 minutes. Use /auth/refresh with your refresh token to obtain a new one. Refresh tokens expire after 7 days.

Base URL

https://protonpay.org/api

Auth Endpoints

Public endpoints — no Bearer token required.

POST/auth/register

Request Body

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "securePassword123"
}

Response

200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "cm...",
    "email": "john@example.com",
    "name": "John Doe",
    "role": "USER"
  }
}

POST/auth/login

Authenticate and receive JWT tokens.

Request Body

{
  "email": "john@example.com",
  "password": "securePassword123"
}

Response

200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "cm...",
    "email": "john@example.com",
    "name": "John Doe",
    "role": "USER",
    "balanceUsdc": "1250.00"
  }
}

POST/auth/refresh

Refresh an expired access token using a refresh token.

Request Body

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Response

200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Client Endpoints

Require Authorization: Bearer TOKEN header.

GET/client/balance

Get current USDC balance and linked wallet info.

Response

200

{
  "balanceUsdc": "1250.00",
  "walletAddress": "D9cCZQ...",
  "walletNetwork": "Solana"
}

GET/client/dashboard

Get dashboard summary: balance, recent activity, account setup status.

Response

200

{
  "balance": "1250.00",
  "totalDeposited": "5000.00",
  "totalWithdrawn": "3750.00",
  "recentActivity": [
    {
      "id": "cm...",
      "type": "DEPOSIT",
      "amount": "100.00",
      "status": "CONFIRMED",
      "createdAt": "2026-03-14T12:00:00Z"
    }
  ],
  "setupSteps": {
    "emailVerified": true,
    "kycCompleted": false,
    "walletLinked": true,
    "twoFaEnabled": false
  }
}

POST/client/deposit/card

Create a card deposit session via Tap Payments (USD, OMR, AED, SAR), YooKassa (RUB), or FreedomPay (KZT/UZS/KGS). Returns a payment URL.

Request Body

{
  "amount": 100,
  "currency": "usd",
  "provider": "tap"
}

Response

200

{
  "url": "https://checkout.tap.company/pay/chg_..."
}

POST/client/withdraw

Create a USDC withdrawal to an external wallet. Subject to plan limits and cooldown.

Request Body

{
  "amount": 50,
  "walletAddress": "D9cCZQxDN1fohCRSfQMRC...",
  "network": "Solana"
}

Response

200

{
  "payout": {
    "id": "cm...",
    "amount": "50.00",
    "fee": "0.50",
    "walletAddress": "D9cCZQ...",
    "network": "Solana",
    "status": "PENDING",
    "createdAt": "2026-03-14T15:00:00Z"
  }
}

POST/client/transfer

Internal USDC transfer to another user by email or public ID.

Request Body

{
  "toIdentifier": "user@example.com",
  "amount": 25,
  "note": "Payment for services"
}

Response

200

{
  "transfer": {
    "id": "cm...",
    "amount": "25.00",
    "fee": "0",
    "toUser": "user@example.com",
    "status": "COMPLETED"
  },
  "newBalance": "1225.00"
}

GET/client/activity

Get transaction history (deposits, withdrawals, transfers).

Response

200

{
  "activity": [
    {
      "id": "cm...",
      "type": "DEPOSIT",
      "amount": "100.00",
      "method": "CRYPTO",
      "network": "Solana",
      "status": "CONFIRMED",
      "createdAt": "2026-03-14T12:00:00Z"
    }
  ]
}

GET/client/fees

Get current fee schedule and withdrawal limits for your plan.

Response

200

{
  "fees": {
    "deposit": { "commission": "0%" },
    "withdrawal": {
      "Solana": "0.01 USDC",
      "Base": "0.05 USDC",
      "Polygon": "0.02 USDC"
    },
    "transfer": { "fee": "0 USDC" },
    "limits": {
      "maxSingleWithdrawal": 10000,
      "dailyWithdrawalLimit": 50000,
      "withdrawalCooldownSec": 60
    }
  }
}

Developer Endpoints

API keys, webhooks, and invoices for programmatic integration.

POST/client/api-keys

Create a new API key. The raw key is returned only once.

Request Body

{
  "name": "Production Key"
}

Response

200

{
  "key": {
    "id": "cm...",
    "name": "Production Key",
    "prefix": "sk_live_abc...",
    "rawKey": "sk_live_abc123def456...",
    "permissions": "full"
  }
}

POST/client/webhooks

Request Body

{
  "url": "https://yourapp.com/webhooks/nova",
  "events": ["deposit.confirmed", "payout.completed"]
}

Response

200

{
  "webhook": {
    "id": "cm...",
    "url": "https://yourapp.com/webhooks/nova",
    "events": ["deposit.confirmed", "payout.completed"],
    "secret": "whsec_..."
  }
}

POST/client/invoices

Create a payment invoice with a unique payment link.

Request Body

{
  "amount": 50,
  "currency": "USDC",
  "description": "Monthly subscription"
}

Response

200

{
  "invoice": {
    "id": "cm...",
    "amount": "50.00",
    "currency": "USDC",
    "status": "PENDING",
    "payUrl": "https://protonpay.org/pay/cm..."
  }
}

Supported Networks

Solana

USDC (SPL)

~400ms finality

Base

USDC (ERC-20)

~2s finality

Polygon

USDC (ERC-20)

~2s finality

Card Payment Providers

Tap Payments

USD, OMR, AED, SAR, KWD, BHD, EGP

provider: "tap", currency: "usd"

YooKassa

RUB

provider: "yookassa", currency: "rub"

FreedomPay

KZT, UZS, KGS

provider: "freedompay", currency: "kzt"

Webhook Events

Configure webhook endpoints via POST /client/webhooks to receive real-time event notifications.

deposit.confirmedA crypto deposit has been confirmed on-chain

deposit.card.successA card payment has been completed successfully

payout.completedA USDC payout has been sent to the wallet

payout.failedA payout has failed (insufficient balance, network error)

transfer.completedAn internal user-to-user transfer completed

invoice.paidA payment invoice has been paid

kyc.approvedUser KYC verification was approved

kyc.rejectedUser KYC verification was rejected

Webhook Payload Example

{
  "event": "deposit.confirmed",
  "data": {
    "id": "cm...",
    "userId": "cm...",
    "amount": "100.00",
    "currency": "USDC",
    "network": "Solana",
    "txHash": "5xKm2Q...8b3c",
    "status": "CONFIRMED"
  },
  "timestamp": "2026-03-14T12:00:00Z",
  "signature": "hmac_sha256(payload, webhook_secret)"
}

Rate Limits

Authentication endpoints5 req/min per IP

Client read endpoints (GET)60 req/min

Client write endpoints (POST/PUT/DELETE)30 req/min

Withdrawal cooldown60 seconds

Error Codes

Code	Description
400	Bad Request — Invalid or missing parameters
401	Unauthorized — Missing or expired JWT token
403	Forbidden — Insufficient permissions or plan limit reached
404	Not Found — Resource does not exist
409	Conflict — Duplicate operation (e.g. withdrawal cooldown)
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error — Something went wrong on our end
503	Service Unavailable — Payment provider not configured