Getting started

Quickstart

Accept your first crypto payment in about 10 minutes. This guide creates a session in test mode, walks a fake customer through checkout, and receives the webhook.

1. Create an account

Sign up at blockcade.app/gateway/register. Pick Individual (for personal projects) or Business (for a company). A test API key is issued automatically — grab it from Settings → API keys.

2. Install an SDK (optional)

You can use raw HTTP if you prefer. Official SDKs:

# Node.js
npm install @blockcade/node

# Python (coming soon)
pip install blockcade

3. Create a session

curl -X POST https://blockcade.app/gateway/api/sessions/ \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "currency": "USD",
    "accepted_currencies": ["USDC", "USDT"],
    "customer_email": "test@example.com",
    "success_url": "https://mysite.com/thanks",
    "cancel_url":  "https://mysite.com/cart",
    "metadata":    {"order_id": "TEST-001"}
  }'

const Blockcade = require('@blockcade/node');
const bc = new Blockcade({ apiKey: process.env.BLOCKCADE_KEY });

const session = await bc.sessions.create({
  amount: 25,
  currency: 'USD',
  accepted_currencies: ['USDC', 'USDT'],
  customer_email: 'test@example.com',
  success_url: 'https://mysite.com/thanks',
  cancel_url:  'https://mysite.com/cart',
  metadata: { order_id: 'TEST-001' }
});

console.log(session.url);  // redirect the customer here

import requests

r = requests.post(
    "https://blockcade.app/gateway/api/sessions/",
    headers={
        "Authorization": f"Bearer {BLOCKCADE_KEY}",
        "Content-Type":  "application/json",
    },
    json={
        "amount":   25.00,
        "currency": "USD",
        "accepted_currencies": ["USDC", "USDT"],
        "customer_email": "test@example.com",
        "success_url": "https://mysite.com/thanks",
        "cancel_url":  "https://mysite.com/cart",
        "metadata":    {"order_id": "TEST-001"},
    },
    timeout=15,
)
session = r.json()
print(session["url"])  # redirect the customer here

<?php
$ch = curl_init('https://blockcade.app/gateway/api/sessions/');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('BLOCKCADE_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'amount'   => 25.00,
    'currency' => 'USD',
    'accepted_currencies' => ['USDC', 'USDT'],
    'customer_email' => 'test@example.com',
    'success_url'    => 'https://mysite.com/thanks',
    'cancel_url'     => 'https://mysite.com/cart',
    'metadata'       => ['order_id' => 'TEST-001'],
  ]),
]);

$session = json_decode(curl_exec($ch), true);
header('Location: ' . $session['url']);  // redirect the customer

4. Redirect the customer

The response includes a url. Send your customer there. They'll see a Blockcade-hosted checkout page branded with your name and color, with QR codes for crypto and a card fallback. In test mode, a "Simulate payment" button appears at the bottom — click it to move to step 5.

5. Handle the webhook

Set up a public endpoint on your server. In Blockcade Dashboard → Webhooks, add its URL. You'll get a signing secret — keep it in an environment variable.

// Express receiver
const express = require('express');
const Blockcade = require('@blockcade/node');

const app = express();
app.post('/webhooks/blockcade',
  express.raw({ type: '*/*' }),
  (req, res) => {
    const ok = Blockcade.webhooks.verify({
      payload:   req.body,
      signature: req.header('X-Blockcade-Signature'),
      secret:    process.env.BLOCKCADE_WEBHOOK_SECRET,
    });
    if (!ok) return res.status(400).send('invalid signature');

    const event = JSON.parse(req.body.toString());
    if (event.type === 'payment.succeeded') {
      // Fulfill the order using event.data.object.metadata.order_id
    }
    res.sendStatus(200);
  }
);