Build with the BlockAck API

Keep authentication on your server

Base URL: https://www.blockack.com. Send your scoped merchant API key as Authorization: Bearer YOUR_API_KEY. Never include API keys in public links, website buttons, browser JavaScript, or source control.

Create an account, connect your Bitcoin extended public key, configure your store, and create a scoped API key in the merchant console. You do not connect a separate payment server. Account-management endpoints use a merchant session token instead of this API key.

Create your first API invoice

This server-side JavaScript example requests 25,000 sats. Use your local BlockAck store UUID and an API key with invoices:write. Check the effective USD-equivalent payment limit before submitting.

// Server-side only. Never expose your API key in browser code.
const response = await fetch("https://www.blockack.com/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLOCKACK_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-1042-invoice",
  },
  body: JSON.stringify({
    amount_sats: 25000,
    store_id: process.env.BLOCKACK_STORE_ID,
    email: "customer@example.com",
    metadata: { order_id: "1042" },
  }),
});
const invoice = await response.json();
if (!response.ok) throw new Error(invoice.error ?? "Invoice creation failed");
// Save invoice.id and checkout_url against your order on your server.
// Confirm settlement before fulfilling; a successful POST is not payment.

Send either amount_sats as a positive integer, or {"amount":"0.00025000","currency":"BTC"}. Do not combine these forms. Fractional satoshis are rejected rather than rounded. Fiat numeric amounts are also supported; currency defaults to USD when omitted. email is required. BlockAck sends the receipt to that address after the payment settles. Optional description says what the customer is paying for. The same field works on every invoice currency and on both payment and donation links.

Keep one Idempotency-Key (8–128 characters) per intended invoice. Reuse it with the same payload on retry. A completed replay returns Idempotency-Replayed: true. If creation is in progress or unresolved, investigate the original request; do not switch to a new key and risk a duplicate invoice.

Create a store with the API

1. Create an account and an API key in the console. The key needs stores:write, wallets:write, and stores:read. Keep the key on your server.
2. POST /v2/stores with name, an https callback_url, and environment set to production or sandbox. Save the id. An account can have 5 stores.
3. POST /v2/wallets with crypto set to BTC, a name, and the extended public key. A private key or a seed phrase is refused. Save the wallet id.
4. POST /v2/stores/{id}/wallets with wallet_id.
5. GET /v2/stores/{id} until the store is ready.
6. The three-address check uses your signed-in session, not the API key. POST /api/account/stores/{id}/wallet-verification with {"action":"challenge"}. Compare all three addresses in your own wallet. Within 24 hours send {"action":"confirm","addresses":[...]}. Payments and a published shop wait for that check.

Examples

Store and wallet

Create the store, register the extended public key, and attach it. Read the store again until it is ready. A private key or a seed phrase is refused.

const key = process.env.BLOCKACK_API_KEY;
const headers = { Authorization: `Bearer ${key}`, "Content-Type": "application/json" };

const store = await fetch("https://www.blockack.com/v2/stores", {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Harbor Goods",
    callback_url: "https://example.com/hooks/harbor",
    environment: "production",
  }),
});
const { id: storeId } = await store.json();

const wallet = await fetch("https://www.blockack.com/v2/wallets", {
  method: "POST",
  headers,
  body: JSON.stringify({ crypto: "BTC", name: "Shop wallet", xpub: "xpub..." }),
});
const { id: walletId } = await wallet.json();

await fetch(`https://www.blockack.com/v2/stores/${storeId}/wallets`, {
  method: "POST",
  headers,
  body: JSON.stringify({ wallet_id: walletId }),
});

// Read the store again until it is ready. A private key or seed phrase is refused.

Shop and products

Create the shop, then add products from a spreadsheet. A shop can hold 40 products. The spreadsheet also needs invoices:write.

const shop = await fetch("https://www.blockack.com/v2/shops", {
  method: "POST",
  headers,
  body: JSON.stringify({
    store_id: storeId,
    name: "Harbor Goods",
    slug: "harbor-goods",
    summary: "Wool and paper.",
    category: "clothing",
    terms_accepted: true,
    seller_accepted: true,
  }),
});
const { shop: created } = await shop.json();

await fetch(`https://www.blockack.com/v2/shops/${created.id}/products`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    csv: "Title,amount_sats,Option1 Name,Option1 Value,Variant Inventory Qty,Type,description\nNotebook,15000,Size,A5,12,payment,<p>Plain paper.</p>\nCard,6000,Finish,Matte,20,payment,A folded note.",
  }),
});

Edit a product

Change the description, option, note for the buyer, or the digital delivery text. Send one or more of those fields. The product stays off the public shop until the review finishes.

await fetch(`https://www.blockack.com/v2/shops/${shopId}/products/${linkId}`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    description_html: "<p>Ruled paper, 48 pages.</p>",
    option_label: "Size: A5",
    buyer_prompt: "Name to print",
    fulfillment: "payment",
  }),
});

Product photo

Send the file itself. Content-Type is image/jpeg, image/png, or image/webp. The file is at most 1 MB, and no side is longer than 1600 pixels. A product with no photo has no public image. The banner and the logo use the same rules.

const file = await readFile("notebook.png");
await fetch(`https://www.blockack.com/v2/shops/${shopId}/products/${linkId}/image`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BLOCKACK_API_KEY}`, "Content-Type": "image/png" },
  body: file,
});

// Banner: POST /v2/shops/{id}/cover
// Logo: POST /v2/shops/{id}/logo
// Same file rules. The body is the file itself.

Cart checkout

The cart request does not use your API key. The code in the response opens the pay page.

const quote = await fetch("https://www.blockack.com/api/stores/harbor-goods/checkout", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    request_id: crypto.randomUUID(),
    lines: [{ link_id: linkId, quantity: 1 }],
    shipping_id: shippingId,
  }),
});
const { code } = await quote.json();
// Open /pay?code= with that code. This request does not use your API key.

Bitcoin integration endpoints

These routes require merchant API authentication and the permission shown. List responses include pagination; cryptocurrency atomic amounts in ledger responses are strings.

Hosted shops

A shop is a catalog on a store you already created. Creating and publishing use the permission shown. The public directory does not use an API key.

The shop name becomes the public address: Harbor Goods is /stores/harbor-goods. Publish waits until that store's extended public key is verified and the current seller terms are accepted. An account can have three shops, and a shop can have 40 products. A spreadsheet import also needs invoices:write because it creates payment links. A product image is JPEG, PNG, or WebP, up to 1 MB, with no side longer than 1600 pixels. Pay for the cart with POST /api/stores/{slug}/checkout. That request does not use your API key. The response code opens /pay?code=. The banner and the logo use the same image rules at /v2/shops/{id}/cover and /v2/shops/{id}/logo. DELETE /v2/shops/{id}/products/{linkId} takes a product off the shop. The payment link stays.

Share a receipt with a QR

Receipt POST accepts an empty JSON object or {"expires_in_seconds":1209600} (maximum 30 days). It returns reference, expires_at, and a bearer url whose page offers copy/share/download QR controls. Repeating POST invalidates the previous link; DELETE returns 204. An ineligible or inaccessible invoice returns 404.

Anyone with the link can view the original invoice amount, currency and recorded settlement time. No customer details or transaction identifiers are disclosed. This is stored settlement evidence, not fresh chain verification or a tax invoice.

Verify callbacks before fulfillment

Configure a public HTTPS callback URL on your store. Local/private addresses, embedded credentials, and custom ports are rejected. Delivery is asynchronous and may be retried; do not assume events arrive once or in order.

Verify the BlockAck-Sig header: sha256= followed by the hexadecimal HMAC-SHA256 of the unmodified request body, using the callback signing secret. Compare signatures in constant time. This is not your API key. Securely arrange the signing secret with the platform operator; there is no self-service callback-secret retrieval endpoint documented here.

The envelope has id, type, and data. Handle invoice.settled, deduplicate by delivery id, and check the invoice against your server-side order record. Return a 2xx response after durable acceptance. A redirect, invoice-created response, or browser success screen is not proof of settlement.

Allowances, limits & failure handling

Each merchant shares 1,000 free authorized API requests per UTC month across keys and stores. Starter is 10,000 sats/month or 96,000 sats/year. Paid access does not bypass short-window rate limits or payment-creation safety limits. The default API rate limit is 120 requests per key per 60 seconds.

Current launch defaults: $50 USD-equivalent per creation and 1,000 creations per merchant per UTC month, including paid accounts. Check your effective limits in Billing. Polling, authorized failures, and idempotent retries count toward free API usage.

• 400: fix invalid input; do not retry unchanged.
• 401 / 403: check credentials, scopes and subscription access.
• 409: resolve idempotency conflicts or uncertain creation before another attempt.
• 422: a payment can exceed the configured amount limit.
• 429: distinguish short-window rate limiting from a monthly creation limit.
• 503: configuration, store readiness or conversion dependencies may be unavailable. This does not authorize accepting payments.

Inspect the response’s error code. Use bounded backoff for transient failures, and preserve the original idempotency key. Never automatically mark an order paid when an API request fails.