Payment Orders API

Payment orders are the core of CryptoPay. They represent payment requests that customers can fulfill by sending cryptocurrency to your wallet addresses.

Create Payment Order

Create a new payment order for a customer to pay.

POST /api/payment-orders/

Request Body

{
  "amount": "100.00",
  "currency": "USDC",
  "blockchain": "base",
  "order_info": "{\"product\": \"Premium Plan\", \"quantity\": 1}",
  "nonce": 1640995200123456,
  "webhook_url": "https://your-site.com/webhooks/cryptopay",
  "redirect_url": "https://your-site.com/payment/success",
  "expires_at": "2024-01-01T12:00:00Z"
}

Parameters

Parameter	Type	Required	Description
amount	string	Yes	Payment amount (e.g., "100.00")
currency	string	Yes	Token symbol (USDC, ETH, etc.)
blockchain	string	Yes	Blockchain slug (base, ethereum, polygon)
order_info	string	Yes	JSON string with order details
nonce	integer	Yes	Unique nonce for blockchain tracking
webhook_url	string	No	Custom webhook URL for this order
redirect_url	string	No	URL to redirect after payment
expires_at	string	No	ISO 8601 expiration timestamp

Response

{
  "success": true,
  "data": {
    "id": 123,
    "order_id": "ORD-abc123def456",
    "amount": "100.00",
    "currency": "USDC",
    "blockchain": "base",
    "status": "pending",
    "receiving_address": "0x1234567890123456789012345678901234567890",
    "payment_url": "https://pay.cryptopay.com/order/ORD-abc123def456",
    "qr_code_url": "/qr/ORD-abc123def456",
    "order_info": "{\"product\": \"Premium Plan\", \"quantity\": 1}",
    "nonce": 1640995200123456,
    "created_at": "2024-01-01T10:00:00Z",
    "expires_at": "2024-01-01T12:00:00Z",
    "transaction": null
  }
}

Example

const createOrder = async () => {
  const response = await fetch('/api/payment-orders/', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: '100.00',
      currency: 'USDC',
      blockchain: 'base',
      order_info: JSON.stringify({
        product: 'Premium Plan',
        customer_id: 'user_123',
        quantity: 1
      }),
      nonce: Date.now() + Math.floor(Math.random() * 1000000)
    })
  });
  
  return await response.json();
};

Get Payment Order

Retrieve details of a specific payment order.

GET /api/payment-orders/{order_id}/

Response

{
  "success": true,
  "data": {
    "id": 123,
    "order_id": "ORD-abc123def456",
    "amount": "100.00",
    "currency": "USDC",
    "blockchain": "base",
    "status": "confirmed",
    "receiving_address": "0x1234567890123456789012345678901234567890",
    "payment_url": "https://pay.cryptopay.com/order/ORD-abc123def456",
    "order_info": "{\"product\": \"Premium Plan\", \"quantity\": 1}",
    "nonce": 1640995200123456,
    "created_at": "2024-01-01T10:00:00Z",
    "confirmed_at": "2024-01-01T10:15:00Z",
    "transaction": {
      "transaction_hash": "0xabcdef1234567890...",
      "block_number": 12345678,
      "confirmations": 15,
      "status": "confirmed"
    }
  }
}

List Payment Orders

Get a paginated list of your payment orders.

GET /api/payment-orders/

Query Parameters

Parameter	Type	Description
status	string	Filter by status (pending, confirmed, expired, failed)
blockchain	string	Filter by blockchain
currency	string	Filter by currency
page	integer	Page number (default: 1)
page_size	integer	Items per page (default: 20, max: 100)
ordering	string	Sort field (-created_at, amount, status)

Example

GET /api/payment-orders/?status=confirmed&blockchain=base&page=1&page_size=50

Response

{
  "count": 150,
  "next": "/api/payment-orders/?page=2",
  "previous": null,
  "results": [
    {
      "id": 123,
      "order_id": "ORD-abc123def456",
      "amount": "100.00",
      "currency": "USDC",
      "status": "confirmed",
      "created_at": "2024-01-01T10:00:00Z"
    }
  ]
}

Payment Order Status

Payment orders can have the following statuses:

Status	Description
pending	Waiting for payment
processing	Payment detected, waiting for confirmations
confirmed	Payment confirmed on blockchain
expired	Payment window expired
failed	Payment failed or rejected

Payment Flow

1. Create Order: Generate payment order with unique nonce
2. Customer Payment: Customer sends crypto to receiving address
3. Detection: Our system detects the blockchain transaction
4. Confirmation: Wait for required block confirmations
5. Webhook: Send notification to your webhook endpoint
6. Completion: Order status updated to confirmed

Error Codes

Code	Description
INVALID_AMOUNT	Amount must be positive number
UNSUPPORTED_CURRENCY	Currency not supported on blockchain
INVALID_BLOCKCHAIN	Blockchain not supported
WALLET_NOT_CONFIGURED	No wallet address for blockchain
DUPLICATE_NONCE	Nonce already used
INVALID_ORDER_INFO	Order info must be valid JSON

Best Practices

Nonce Generation

Always generate unique nonces to prevent duplicate orders:

const generateNonce = () => {
  return Date.now() + Math.floor(Math.random() * 1000000);
};

Order Info Structure

Use consistent JSON structure for order info:

{
  "product": "Premium Plan",
  "quantity": 1,
  "customer_id": "user_123",
  "metadata": {
    "campaign": "summer_sale",
    "referrer": "google"
  }
}

Expiration Handling

Set reasonable expiration times (typically 15-30 minutes):

const expiresAt = new Date(Date.now() + 30 * 60 * 1000); // 30 minutes

Next Steps

• Webhooks - Handle payment notifications
• Transactions - View payment details
• Integration Examples - Complete integration example