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: merchantAuth

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" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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: merchantAuth

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" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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: merchantAuth

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" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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
    }
  }
}

Create payment

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/payment/create

Creates a payment from the merchant cabinet. Authorization is the merchant bearer token, no posTerminalId or signature is sent: the payment is booked on the merchant's system POS (created lazily on first use). 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. Pass an optional externalId (your order / invoice id) to make the call idempotent.

Authorization: merchantAuth

Body required

application/json
amountnumberrequired

Amount in the payment's fiat currency.

Example:10
currencystringrequired

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

Example:USD
descriptionstring

Human-readable description.

Example:Order #1024
externalIdstring
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
ttlSecondsnumber
Example:900

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/payment/create
cURL
curl -X POST "$BASE_URL/merchant/payment/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "amount": 10,
  "currency": "USD",
  "description": "Order #1024",
  "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ttlSeconds": 900
}'
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/merchant/payment/get

Returns the current state of a payment by paymentId, including its status, amounts, merchant / POS details, and qrString. This endpoint requires no authorization, so the payer can poll it directly to track a payment until it is paid or expired.

Body required

application/json
paymentIdstringrequired

Identifier of the payment (UUID).

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

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/payment/get
cURL
curl -X POST "$BASE_URL/merchant/payment/get" \
  -H "Content-Type: application/json" \
  -d '{
  "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
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/merchant/payment/list

Returns a paginated list of the merchant's payments (the payment entity, not the on-chain transaction), scoped to the authenticated merchant. Supports optional dateRange, status, storeIds, posIds, currency, externalId and system filters. For the report of already-paid transactions use /merchant/reports/transactions.

Authorization: merchantAuth

Body required

application/json
paginationobject
filtersobject

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/payment/list
cURL
curl -X POST "$BASE_URL/merchant/payment/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "pagination": {
    "limit": 20,
    "skip": 0
  },
  "filters": {
    "dateRange": {
      "start": 1718012345,
      "end": 1718012345
    },
    "storeIds": [
      "string"
    ],
    "posIds": [
      "string"
    ],
    "status": [
      "initiated"
    ],
    "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "currency": "USD",
    "system": true,
    "paymentIds": [
      "string"
    ]
  }
}'
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",
          "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "posTerminalLabel": "Front desk",
          "posTerminalLocation": "Lisbon, PT",
          "settlement": {
            "settledAt": null,
            "status": null,
            "platformFeeSats": null,
            "netSats": null,
            "payout": null
          }
        }
      ],
      "totalCount": 0
    }
  }
}