Create Checkout API

Initialize a payment session for cross-chain cryptocurrency payments. This is the first step in the CyberPay payment flow.

Endpoint

POST /v1/checkout/create

Authentication

This endpoint requires API key authentication:

Authorization: Bearer YOUR_API_KEY

Request Parameters

Parameter	Type	Required	Description
`merchantId`	string	✅	Your merchant identifier
`amount`	string	✅	Payment amount in the specified currency
`currency`	string	✅	Target settlement currency (e.g., "USDC", "USDT")
`productInfo`	object	✅	Product or service details
`returnUrl`	string	✅	URL to redirect after payment completion
`cancelUrl`	string	❌	URL to redirect if payment is cancelled
`webhookUrl`	string	❌	URL for payment status notifications
`metadata`	object	❌	Custom data to associate with this payment
`expiresAt`	number	❌	Session expiration timestamp (Unix)

ProductInfo Object

interface ProductInfo {
  name: string;           // Product/service name
  description?: string;   // Detailed description
  imageUrl?: string;      // Product image URL
  category?: string;      // Product category
  sku?: string;          // Stock keeping unit
}

Example Request

{
  "merchantId": "merchant_abc123",
  "amount": "99.99",
  "currency": "USDC",
  "productInfo": {
    "name": "Premium Subscription",
    "description": "1-year premium access to our platform",
    "imageUrl": "https://example.com/product.jpg",
    "category": "subscription"
  },
  "returnUrl": "https://yourstore.com/payment/success",
  "cancelUrl": "https://yourstore.com/payment/cancel",
  "webhookUrl": "https://yourstore.com/webhooks/cyberpay",
  "metadata": {
    "orderId": "order_xyz789",
    "customerId": "customer_456",
    "source": "web"
  },
  "expiresAt": 1759234785
}

Response Format

Success Response

{
  "success": true,
  "data": {
    "checkoutId": "checkout_1759231185333_abc123",
    "status": "created",
    "amount": "99.99",
    "currency": "USDC",
    "productInfo": {
      "name": "Premium Subscription",
      "description": "1-year premium access to our platform",
      "imageUrl": "https://example.com/product.jpg",
      "category": "subscription"
    },
    "availablePaymentMethods": [
      {
        "chainId": 1,
        "chainName": "Ethereum",
        "tokens": [
          {
            "symbol": "ETH",
            "address": "0x0000000000000000000000000000000000000000",
            "decimals": 18,
            "name": "Ethereum"
          },
          {
            "symbol": "USDC",
            "address": "0xA0b86a33E6441b8e776f89d2b5B977c737C5e0b6",
            "decimals": 6,
            "name": "USD Coin"
          }
        ]
      },
      {
        "chainId": 137,
        "chainName": "Polygon",
        "tokens": [
          {
            "symbol": "MATIC",
            "address": "0x0000000000000000000000000000000000000000",
            "decimals": 18,
            "name": "Polygon"
          },
          {
            "symbol": "USDC",
            "address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
            "decimals": 6,
            "name": "USD Coin"
          }
        ]
      }
    ],
    "paymentUrl": "https://pay.cyberpay.org/checkout/checkout_1759231185333_abc123",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "returnUrl": "https://yourstore.com/payment/success",
    "cancelUrl": "https://yourstore.com/payment/cancel",
    "metadata": {
      "orderId": "order_xyz789",
      "customerId": "customer_456",
      "source": "web"
    },
    "createdAt": 1759231185,
    "expiresAt": 1759234785
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Response Fields

Field	Type	Description
`checkoutId`	string	Unique checkout session identifier
`status`	string	Current checkout status (`created`, `expired`, `completed`)
`amount`	string	Payment amount
`currency`	string	Settlement currency
`availablePaymentMethods`	array	Supported payment tokens by network
`paymentUrl`	string	Hosted payment page URL
`qrCode`	string	QR code for mobile payments (base64 encoded)
`createdAt`	number	Creation timestamp
`expiresAt`	number	Expiration timestamp

Error Responses

Invalid Parameters

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid request parameters",
    "details": {
      "field": "amount",
      "reason": "Amount must be a positive number"
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Unsupported Currency

{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_CURRENCY",
    "message": "Currency not supported",
    "details": {
      "currency": "XYZ",
      "supportedCurrencies": ["USDC", "USDT", "DAI", "ETH"]
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Merchant Not Found

{
  "success": false,
  "error": {
    "code": "MERCHANT_NOT_FOUND",
    "message": "Merchant ID not found or inactive",
    "details": {
      "merchantId": "merchant_abc123"
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Code Examples

JavaScript/TypeScript

import { CyberPaySDK } from '@cyberpay/sdk';
 
const sdk = new CyberPaySDK({
  apiKey: 'YOUR_API_KEY',
  environment: 'production' // or 'testnet'
});
 
async function createCheckout() {
  try {
    const checkout = await sdk.checkout.create({
      merchantId: 'merchant_abc123',
      amount: '99.99',
      currency: 'USDC',
      productInfo: {
        name: 'Premium Subscription',
        description: '1-year premium access to our platform'
      },
      returnUrl: 'https://yourstore.com/payment/success',
      metadata: {
        orderId: 'order_xyz789',
        customerId: 'customer_456'
      }
    });
    
    console.log('Checkout created:', checkout);
    
    // Redirect user to payment page
    window.location.href = checkout.paymentUrl;
    
    return checkout;
  } catch (error) {
    console.error('Error creating checkout:', error);
  }
}

cURL

curl -X POST https://api.cyberpay.org/v1/checkout/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "merchant_abc123",
    "amount": "99.99",
    "currency": "USDC",
    "productInfo": {
      "name": "Premium Subscription",
      "description": "1-year premium access to our platform"
    },
    "returnUrl": "https://yourstore.com/payment/success",
    "metadata": {
      "orderId": "order_xyz789",
      "customerId": "customer_456"
    }
  }'

Python

import requests
 
def create_checkout():
    url = "https://api.cyberpay.org/v1/checkout/create"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    data = {
        "merchantId": "merchant_abc123",
        "amount": "99.99",
        "currency": "USDC",
        "productInfo": {
            "name": "Premium Subscription",
            "description": "1-year premium access to our platform"
        },
        "returnUrl": "https://yourstore.com/payment/success",
        "metadata": {
            "orderId": "order_xyz789",
            "customerId": "customer_456"
        }
    }
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

Integration Patterns

Hosted Payment Page

The simplest integration redirects users to CyberPay's hosted payment page:

// Create checkout and redirect
const checkout = await sdk.checkout.create({...});
window.location.href = checkout.paymentUrl;

Embedded Payment Widget

For a more integrated experience, embed the payment widget:

<div id="cyberpay-widget"></div>
 
<script>
CyberPay.embed({
  checkoutId: 'checkout_1759231185333_abc123',
  container: '#cyberpay-widget',
  onSuccess: (payment) => {
    console.log('Payment successful:', payment);
    window.location.href = '/success';
  },
  onError: (error) => {
    console.error('Payment failed:', error);
  }
});
</script>

Mobile Deep Links

For mobile apps, use deep links to popular wallets:

const checkout = await sdk.checkout.create({...});
 
// Generate wallet-specific deep links
const deepLinks = {
  metamask: `https://metamask.app.link/dapp/${checkout.paymentUrl}`,
  trust: `https://link.trustwallet.com/open_url?coin_id=60&url=${checkout.paymentUrl}`,
  coinbase: `https://go.cb-w.com/dapp?cb_url=${checkout.paymentUrl}`
};

Webhook Integration

Set up webhooks to receive real-time payment updates:

// Webhook endpoint on your server
app.post('/webhooks/cyberpay', (req, res) => {
  const signature = req.headers['x-cyberpay-signature'];
  const payload = req.body;
  
  // Verify webhook signature
  if (!sdk.webhooks.verify(payload, signature)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Handle payment events
  switch (payload.event) {
    case 'checkout.completed':
      console.log('Payment completed:', payload.data);
      // Update your database, send confirmation email, etc.
      break;
    case 'checkout.failed':
      console.log('Payment failed:', payload.data);
      // Handle failed payment
      break;
  }
  
  res.status(200).send('OK');
});

Best Practices

Security

Always validate webhook signatures
Use HTTPS for all URLs (returnUrl, cancelUrl, webhookUrl)
Store sensitive data in metadata only if encrypted
Implement proper API key management

User Experience

Set reasonable expiration times (typically 15-30 minutes)
Provide clear product information and images
Handle payment failures gracefully
Show payment progress to users

Error Handling

Implement retry logic for network failures
Validate all parameters before API calls
Provide meaningful error messages to users
Log errors for debugging

Performance

Cache available payment methods when possible
Use appropriate timeout values
Implement proper loading states
Consider using webhooks instead of polling

Rate Limits

Standard: 100 requests per minute
Premium: 1000 requests per minute
Enterprise: Custom limits available

Next Steps

After creating a checkout:

Get Quote - Get real-time pricing for payment routes
Create Order - Lock in pricing and create payment order
Execute Payment - Process the cross-chain transaction
Query Status - Monitor payment progress

Support

📧 Email: support@cyberpay.org
💬 Telegram: @cyberpay_support
📖 Documentation: docs.cyberpay.org