BTCPay Server

# Greenfield API examples

These examples create a basic invoice. Replace placeholders and use the API reference at /docs on your target instance for the complete request and response models. The key needs btcpay.store.cancreateinvoice, scoped to the selected store when possible.

# cURL

BTCPAY_URL="https://your-btcpay.example"
API_KEY="your-api-key"
STORE_ID="your-store-id"

curl --fail-with-body \
  -X POST \
  -H "Authorization: token $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"amount":"10.00","currency":"USD","metadata":{"orderId":"ORDER-123"}}' \
  "$BTCPAY_URL/api/v1/stores/$STORE_ID/invoices"

# Node.js

const btcpayUrl = 'https://your-btcpay.example'
const apiKey = process.env.BTCPAY_API_KEY
const storeId = process.env.BTCPAY_STORE_ID

const response = await fetch(`${btcpayUrl}/api/v1/stores/${storeId}/invoices`, {
  method: 'POST',
  headers: {
    Authorization: `token ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '10.00',
    currency: 'USD',
    metadata: { orderId: 'ORDER-123' }
  })
})

if (!response.ok) throw new Error(`BTCPay returned ${response.status}: ${await response.text()}`)
const invoice = await response.json()
console.log(invoice.id, invoice.checkoutLink)

For webhook signatures, compute HMAC-SHA256 over the exact request bytes with the webhook secret. Compare sha256=<lowercase hex digest> to the BTCPay-Sig header with a constant-time comparison. Do this before acting on the parsed event.

# PHP

The maintained BTCPay Server Greenfield PHP client (opens new window) is available through Composer:

composer require btcpayserver/btcpayserver-greenfield-php

<?php
require __DIR__ . '/vendor/autoload.php';

$client = new BTCPayServer\Client\Invoice(
    'https://your-btcpay.example',
    getenv('BTCPAY_API_KEY')
);

$invoice = $client->createInvoice(
    getenv('BTCPAY_STORE_ID'),
    'USD',
    BTCPayServer\Util\PreciseNumber::parseString('10.00'),
    'ORDER-123'
);

echo $invoice->getCheckoutLink();

Check the client's examples (opens new window) for its current method signatures and webhook helper.

# OpenAPI clients

You can browse the Greenfield API for the latest BTCPay Server version in the public API reference (opens new window), without running your own server. Its OpenAPI (Swagger) document (opens new window) is also publicly available.

You can use either OpenAPI document to generate an API client. Use your instance's document at /swagger/v1/swagger.json to match its BTCPay Server version and include APIs provided by installed plugins.

← Invoice metadata →