POS API

This surface integrates a point-of-sale terminal that accepts Bitcoin payments: create a payment, show the customer a QR code, and track it until it settles on-chain.

Authentication: each terminal is issued an apiKey and signs every request with an HMAC-SHA256 signature (signature + ts in the request), so the secret is never transmitted.
Operation groups: Payments (create, get, list), plus the payment.status.updated webhook as an alternative to polling.

Browse all endpointsCreate payment, get payment, list payments, and the webhook contract.POS API SDKThe official client. Signs each request for you, works server-side and in the browser.

The flow

Get a terminal key

In the merchant dashboard, create a store and a terminal, then copy the terminal's key. See Stores and POS Terminals.

Create a payment

Post the amount and currency. The response includes the satoshi amount, the BTC price snapshot, an expiresAt deadline, and a qrString to present to the payer.

Pass your own externalId (order or invoice id) to make the call idempotent and to correlate the payment with your records.

Show the QR and wait

Render qrString as a QR code. The customer scans it in the GoBTC Pay app and approves.

Track it to completion

Either poll Get payment, or subscribe to the payment.status.updated webhook. The webhook's data has the same shape as the Get payment response, so one parser covers both.

Webhook signatures

Each delivery is signed. Verify the X-GoBTCPay-Signature: t=<unix>,v1=<hmac> header, where:

v1 = HMAC-SHA256(signingSecret, "{t}.{rawBody}")

Delivery is at-least-once, so de-duplicate on eventId. Respond with any 2xx to acknowledge receipt; non-2xx responses are retried.

Important

The apiKey is a per-terminal secret used to sign every request. Keep it server-side or on a controlled POS device. Never ship it in a public website.