gobtc payDocs

Payments

Create and inspect payments, list payment history, and build / submit the signed transaction that settles a payment.

Create payment

POSThttps://api.gobtcpay.com/public/api/v1.2/pos/transaction/create-payment

Creates a payment request for a POS terminal. Specify 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. signature and ts may be supplied for request signing.

Authorization: apiAuth

Body required

application/json
posTerminalIdstringrequired

POS terminal that accepts the payment (from Create POS terminal).

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
amountnumber

Amount to charge, in the selected fiat currency.

Example:10
descriptionstring

Optional description shown to the payer.

Example:Order #1024
currencystringrequired

Fiat currency code (ISO 4217), e.g. USD.

Example:USD
metadataany

Internal system metadata attached to the payment (reserved; not set by clients).

ttlSecondsnumber

Optional lifetime of the payment in seconds; after this it expires.

Example:900
externalIdstring

Merchant's own correlation id (e.g. order / invoice id). Unique per merchant, so reusing it makes create-payment idempotent. Echoed back in payment responses and webhook deliveries.

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
signaturestringrequired

Optional HMAC-SHA256 signature of the request (hex), authenticating the POS terminal with its apiKey.

Example:4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7a…
tsnumberrequired

Request timestamp in milliseconds, used together with signature for replay protection.

Example:1718012345000

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /pos/transaction/create-payment
cURL
curl -X POST "$BASE_URL/pos/transaction/create-payment" \
  -H "Content-Type: application/json" \
  -d '{
  "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": 10,
  "description": "Order #1024",
  "currency": "USD",
  "metadata": {},
  "ttlSeconds": 900,
  "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "signature": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
  "ts": 1718012345000
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "initiated",
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "merchantName": "Satoshi Coffee",
      "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "posTerminalLabel": "Front desk",
      "posTerminalLocation": "Lisbon, PT",
      "merchantDisplayName": "Satoshi Coffee",
      "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "amountSats": "string",
      "currency": "USD",
      "currencySymbol": "$",
      "amount": 10,
      "expiresAt": 1718012345,
      "btcPriceInUsd": 65000,
      "btcPriceInCurrency": 65000,
      "checkoutUrl": "string",
      "version": 0,
      "btcAddress": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
      "qrString": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005"
    }
  }
}

Get payment

POSThttps://api.gobtcpay.com/public/api/v1.2/pos/transaction/get-payment

Returns the current state of a payment by paymentId, including its status, amounts, merchant / POS details, and qrString. Poll this to track a payment until it is paid or expired.

Authorization: apiAuth

Body required

application/json
paymentIdstringrequired

Transaction (payment) identifier, the paymentId returned by Create payment.

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
signaturestringrequired

Signature in hex format sha 256

Example:4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7a…
tsnumberrequired

Timestamp in milliseconds

Example:1718012345000

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /pos/transaction/get-payment
cURL
curl -X POST "$BASE_URL/pos/transaction/get-payment" \
  -H "Content-Type: application/json" \
  -d '{
  "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "signature": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
  "ts": 1718012345000
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "initiated",
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "currency": "USD",
      "merchantName": "Satoshi Coffee",
      "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "posTerminalLabel": "Front desk",
      "posTerminalLocation": "Lisbon, PT",
      "merchantDisplayName": "Satoshi Coffee",
      "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "description": "Order #1024",
      "amountSats": "string",
      "btcPriceInUsd": 65000,
      "btcPriceInCurrency": 65000,
      "currencySymbol": "$",
      "amount": 10,
      "metadata": {},
      "expiresAt": 1718012345,
      "qrString": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005",
      "version": 0,
      "transactions": [],
      "paidAt": null
    }
  }
}

List payments

POSThttps://api.gobtcpay.com/public/api/v1.2/pos/transaction/list

Returns a paginated list of payment transactions with optional dateRange and status filters. Each item carries merchant / POS context, fiat and BTC amounts, and on-chain settlement data when available. totalCount reflects the filtered total.

Authorization: apiAuth

Body required

application/json
paginationobject
filtersobject
posTerminalIdstringrequired

Identifier of the POS terminal (UUID).

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
signaturestringrequired

Signature in hex format sha 256

Example:4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7a…
tsnumberrequired

Timestamp in milliseconds

Example:1718012345000

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /pos/transaction/list
cURL
curl -X POST "$BASE_URL/pos/transaction/list" \
  -H "Content-Type: application/json" \
  -d '{
  "pagination": {
    "limit": 20,
    "skip": 0
  },
  "filters": {
    "dateRange": {
      "start": 0,
      "end": 0
    },
    "status": [
      "initiated"
    ]
  },
  "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "signature": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
  "ts": 1718012345000
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "items": [
        {
          "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "status": "initiated",
          "amount": 10,
          "amountSats": "string",
          "currency": "USD",
          "currencySymbol": "$",
          "description": "Order #1024",
          "metadata": {},
          "network": "mainnet",
          "btcPriceInUsd": 65000,
          "btcPriceInCurrency": 65000,
          "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "createdAt": 1718012345,
          "expiresAt": 1718012345,
          "btcAddress": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
          "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantName": "Satoshi Coffee",
          "merchantDisplayName": "Satoshi Coffee",
          "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "posTerminalLabel": "Front desk",
          "posTerminalLocation": "Lisbon, PT"
        }
      ],
      "totalCount": 0
    }
  }
}

Payment status updateWebhook

POSThttps://api.gobtcpay.com/public/api/v1.2payment.status.updated

Sent to your configured webhook URL whenever a payment's status changes (paid, cleared, expired, …). The event is wrapped in a thin envelope (eventId, type, createdAt, data) where `data` has the same structure as the Get payment response, so you can reuse the same parser. Use this as an alternative to polling Get payment.

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, de-duplicate on eventId. Respond with any 2xx to acknowledge receipt; non-2xx responses are retried.

Body required

application/json
eventIdstringrequired

Unique id of this webhook event. Use it to de-duplicate deliveries (delivery is at-least-once).

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
typeenumrequired

Event type. Always payment.status.updated.

payment.status.updated
Example:payment.status.updated
createdAtintegerrequired

When this event was emitted, as a Unix timestamp (seconds).

Example:1718012345
dataobjectrequired

The payment, identical in structure to the Get payment response.

Responses

No body.

POST payment.status.updated
cURL
curl -X POST "$BASE_URLpayment.status.updated" \
  -H "Content-Type: application/json" \
  -d '{
  "eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "payment.status.updated",
  "createdAt": 1718012345,
  "data": {
    "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "initiated",
    "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "currency": "USD",
    "merchantName": "Satoshi Coffee",
    "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "posTerminalLabel": "Front desk",
    "posTerminalLocation": "Lisbon, PT",
    "merchantDisplayName": "Satoshi Coffee",
    "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "description": "Order #1024",
    "amountSats": "string",
    "btcPriceInUsd": 65000,
    "btcPriceInCurrency": 65000,
    "currencySymbol": "$",
    "amount": 10,
    "metadata": {},
    "expiresAt": 1718012345,
    "qrString": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005",
    "version": 0,
    "transactions": [],
    "paidAt": null
  }
}'