API Documentation

Complete reference for the CoinPay REST API

📦 Node.js SDK & CLI

Use our official SDK for seamless integration with your Node.js applications

View SDK Docs

Authentication

All API requests require authentication using a JWT token in the Authorization header.

POST/api/auth/register

Create a new merchant account.

Request Body

{
  "email": "merchant@example.com",
  "password": "SecurePassword123!",
  "name": "My Business"  // optional
}

cURL Example

curl -X POST https://coinpayportal.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "merchant@example.com",
    "password": "SecurePassword123!",
    "name": "My Business"
  }'

Node.js Example

const response = await fetch('https://coinpayportal.com/api/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'merchant@example.com',
    password: 'SecurePassword123!',
    name: 'My Business'
  })
});
const data = await response.json();
console.log(data.token); // Save this token

POST/api/auth/login

Request Body

{
  "email": "merchant@example.com",
  "password": "SecurePassword123!"
}

Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "merchant": {
    "id": "merchant-123",
    "email": "merchant@example.com",
    "name": "My Business"
  }
}

GET/api/auth/me

Get current authenticated merchant information.

cURL Example

curl https://coinpayportal.com/api/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "merchant": {
    "id": "merchant-123",
    "email": "merchant@example.com",
    "name": "My Business",
    "created_at": "2024-01-01T12:00:00Z"
  }
}

Subscriptions & Entitlements

CoinPay Portal offers two subscription tiers with different features and transaction limits. All subscription payments are processed using cryptocurrency.

Tip: View our pricing page for a visual comparison of plans and to upgrade your subscription.

Subscription Plans

Starter (Free)

• Up to 100 transactions/month
• All supported chains
• Basic API access
• Email support

Professional ($49/month)

• Unlimited transactions
• Priority support
• Advanced analytics
• Custom webhooks
• White-label option

GET/api/subscription-plans

Get available subscription plans (public endpoint).

Response

{
  "success": true,
  "plans": [
    {
      "id": "starter",
      "name": "Starter",
      "description": "Perfect for testing and small projects",
      "pricing": { "monthly": 0, "yearly": 0 },
      "limits": { "monthly_transactions": 100, "is_unlimited": false },
      "features": {
        "all_chains_supported": true,
        "basic_api_access": true,
        "advanced_analytics": false,
        "custom_webhooks": false,
        "white_label": false,
        "priority_support": false
      }
    },
    {
      "id": "professional",
      "name": "Professional",
      "pricing": { "monthly": 49, "yearly": 490 },
      "limits": { "monthly_transactions": null, "is_unlimited": true },
      "features": { ... }
    }
  ]
}

GET/api/entitlements

Get current merchant's entitlements, features, and usage.

cURL Example

curl https://coinpayportal.com/api/entitlements \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "entitlements": {
    "plan": {
      "id": "starter",
      "name": "Starter",
      "description": "Perfect for testing and small projects",
      "price_monthly": 0
    },
    "features": {
      "all_chains_supported": true,
      "basic_api_access": true,
      "advanced_analytics": false,
      "custom_webhooks": false,
      "white_label": false,
      "priority_support": false
    },
    "usage": {
      "transactions_this_month": 45,
      "transaction_limit": 100,
      "transactions_remaining": 55,
      "is_unlimited": false
    },
    "status": "active"
  }
}

POST/api/subscriptions/checkout

Create a crypto payment for subscription upgrade.

Request Body

{
  "plan_id": "professional",
  "billing_period": "monthly",  // or "yearly"
  "blockchain": "ETH"  // BTC, BCH, ETH, MATIC, SOL
}

cURL Example

curl -X POST https://coinpayportal.com/api/subscriptions/checkout \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "professional",
    "billing_period": "monthly",
    "blockchain": "ETH"
  }'

Response

{
  "success": true,
  "payment": {
    "id": "pay_abc123",
    "payment_address": "0x1234...5678",
    "amount": 49,
    "currency": "USD",
    "blockchain": "ETH",
    "expires_at": "2024-01-15T12:00:00Z"
  },
  "plan": {
    "id": "professional",
    "name": "Professional",
    "billing_period": "monthly",
    "price": 49
  },
  "instructions": "Send exactly $49 worth of ETH to the payment address..."
}

GET/api/subscriptions/status

Get current subscription status.

Response

{
  "success": true,
  "subscription": {
    "planId": "professional",
    "status": "active",
    "startedAt": "2024-01-01T00:00:00Z",
    "endsAt": "2024-02-01T00:00:00Z",
    "isActive": true,
    "daysRemaining": 15
  }
}

DELETE/api/subscriptions/status

Cancel subscription (access continues until end of billing period).

Response

{
  "success": true,
  "message": "Subscription cancelled. You will retain access until the end of your billing period.",
  "subscription": {
    "planId": "professional",
    "status": "cancelled",
    "endsAt": "2024-02-01T00:00:00Z",
    "isActive": true,
    "daysRemaining": 15
  }
}

Entitlement Error Codes

429

Transaction Limit Exceeded

Monthly transaction limit reached. Upgrade to Professional for unlimited.

403

Feature Not Available

Feature not available on current plan. Upgrade required.

402

Subscription Inactive

Subscription is past_due or cancelled. Payment required.

Businesses

GET/api/businesses

List all businesses for the authenticated merchant.

cURL Example

curl https://coinpayportal.com/api/businesses \
  -H "Authorization: Bearer YOUR_TOKEN"

POST/api/businesses

Create a new business.

Request Body

{
  "name": "My Store",
  "description": "Online retail store",  // optional
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "webhook_url": "https://mystore.com/webhook"  // optional
}

Node.js Example

const response = await fetch('https://coinpayportal.com/api/businesses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My Store',
    wallet_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
  })
});
const data = await response.json();

PATCH/api/businesses/:id

Update an existing business.

DELETE/api/businesses/:id

Delete a business.

Payments

POST/api/payments/create

Create a new payment request.

Request Body

{
  "business_id": "business-123",
  "amount_usd": 100.00,
  "currency": "btc",  // btc, eth, matic, sol
  "description": "Order #12345"  // optional
}

cURL Example

curl -X POST https://coinpayportal.com/api/payments/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "business-123",
    "amount_usd": 100.00,
    "currency": "btc"
  }'

Response

{
  "success": true,
  "payment": {
    "id": "payment-456",
    "business_id": "business-123",
    "amount_usd": "100.00",
    "amount_crypto": "0.00234567",
    "currency": "btc",
    "payment_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "status": "pending",
    "created_at": "2024-01-01T12:00:00Z",
    "expires_at": "2024-01-01T13:00:00Z"
  }
}

GET/api/payments/:id

Retrieve payment details by ID.

Node.js Example

const response = await fetch('https://coinpayportal.com/api/payments/payment-456', {
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
const data = await response.json();
console.log(data.payment.status);

GET/api/payments/:id/qr

Get QR code image for payment address.

Usage

<img src="https://coinpayportal.com/api/payments/payment-456/qr" 
     alt="Payment QR Code" />

Business Collection

Business Collection payments allow the platform to collect payments from business users (subscription fees, service charges, etc.) with 100% forwarding to platform wallets.

Key Difference: Unlike regular payments (99.5% merchant / 0.5% platform), Business Collection forwards 100% of funds to the platform's collection wallet.

POST/api/business-collection

Create a new business collection payment.

Request Body

{
  "business_id": "business-123",
  "amount": 99.99,
  "currency": "USD",
  "blockchain": "ETH",  // BTC, BCH, ETH, MATIC, SOL
  "description": "Monthly subscription fee",
  "metadata": {
    "plan": "premium",
    "billing_period": "2024-01"
  }
}

Response

{
  "success": true,
  "payment": {
    "id": "collection-456",
    "payment_address": "0x1234...5678",
    "amount": 99.99,
    "currency": "USD",
    "blockchain": "ETH",
    "destination_wallet": "0xplatform...wallet",
    "status": "pending",
    "description": "Monthly subscription fee",
    "expires_at": "2024-01-02T12:00:00Z",
    "created_at": "2024-01-01T12:00:00Z"
  }
}

GET/api/business-collection

List business collection payments with optional filters.

Query Parameters

business_id - Filter by business (optional)

status - Filter by status: pending, confirmed, forwarded (optional)

limit - Results per page, default 50 (optional)

offset - Pagination offset (optional)

GET/api/business-collection/:id

Get details of a specific business collection payment.

Collection Payment Statuses

pending

Waiting for payment

detected

Payment detected on blockchain

confirmed

Payment confirmed

forwarding

Forwarding to platform wallet

forwarded

100% forwarded to platform

expired

Payment request expired

Dashboard

GET/api/dashboard/stats

Get payment statistics and recent activity.

Response

{
  "success": true,
  "stats": {
    "total_payments": 150,
    "successful_payments": 142,
    "pending_payments": 5,
    "failed_payments": 3,
    "total_volume": "0.12345678",
    "total_volume_usd": 5234.56
  },
  "recent_payments": [...]
}

Settings

GET/api/settings

Get merchant notification settings.

PUT/api/settings

Update notification preferences.

Request Body

{
  "notifications_enabled": true,
  "email_notifications": true,
  "web_notifications": false
}

Supported Cryptocurrencies

Bitcoin

BTC

Code: btc

Confirmations: 3

Ethereum

ETH

Code: eth

Confirmations: 12

Polygon

MATIC

Code: matic

Confirmations: 128

Solana

SOL

Code: sol

Confirmations: 32

Webhooks

Configure webhook URLs in your business settings to receive real-time payment notifications.

Webhook Events

payment.detected

Payment detected on blockchain (0 confirmations)

payment.confirmed

Payment confirmed (sufficient confirmations)

payment.forwarded

Payment forwarded to merchant wallet

payment.failed

Payment failed or expired

Webhook Payload Example

{
  "event": "payment.confirmed",
  "payment_id": "payment-456",
  "business_id": "business-123",
  "amount_crypto": "0.00234567",
  "amount_usd": "100.00",
  "currency": "btc",
  "status": "confirmed",
  "confirmations": 3,
  "tx_hash": "abc123...",
  "timestamp": "2024-01-01T12:05:00Z"
}

Note: Webhook payloads are signed with HMAC-SHA256. Verify the signature using your webhook secret.

Rate Limits & Fees

Rate Limits

• API Requests: 100 requests/minute

• Payment Creation: 10 payments/minute

• Webhook Retries: 3 attempts with exponential backoff

Platform Fees

• Platform Fee: 0.5% per transaction

• Network Fees: Paid by customer

• Minimum Payment: $1.00 USD

Error Codes

400

Bad Request

Invalid request parameters or missing required fields

401

Unauthorized

Invalid or missing authentication token

402

Payment Required

Subscription inactive or payment needed

403

Forbidden

Feature not available on current plan

404

Not Found

Resource not found

429

Too Many Requests

Rate limit or transaction limit exceeded

500

Server Error

Internal server error - please try again

Error Response Format

{
  "success": false,
  "error": "Detailed error message here"
}