gobtc payDocs

Payments

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

Get payment

POSThttps://api.gobtcpay.com/public/api/v1.2/instant/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: walletAuth

Body required

application/json
paymentIdstringrequired

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

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

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /instant/transaction/get-payment
cURL
curl -X POST "$BASE_URL/instant/transaction/get-payment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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",
      "posTerminalLabel": "Front desk",
      "posTerminalLocation": "Lisbon, PT",
      "merchantDisplayName": "Satoshi Coffee",
      "posTerminalId": "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"
    }
  }
}

List payments

POSThttps://api.gobtcpay.com/public/api/v1.2/instant/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: walletAuth

Body required

application/json
paginationobject
filtersobject

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /instant/transaction/list
cURL
curl -X POST "$BASE_URL/instant/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": [
      "success"
    ]
  }
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "items": [
        {
          "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "paymentTxId": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
          "status": "success",
          "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantName": "Satoshi Coffee",
          "posTerminalLabel": "Front desk",
          "posTerminalLocation": "Lisbon, PT",
          "merchantDisplayName": "Satoshi Coffee",
          "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "amountSats": "string",
          "description": "Order #1024",
          "metadata": {},
          "createdAt": 1718012345,
          "btcPriceInUsd": 65000,
          "btcPriceInCurrency": 65000,
          "currency": "USD",
          "amount": 10,
          "currencySymbol": "$",
          "onChain": {
            "tx": null,
            "amountSats": null,
            "feeSats": null,
            "createdAt": null,
            "blockNumber": null
          }
        }
      ],
      "totalCount": 0
    }
  }
}

Build payment transaction

POSThttps://api.gobtcpay.com/public/api/v1.2/instant/psbt/build-transaction-to-sign-payment

Builds the unsigned PSBT that settles a payment. Pass the paymentId; the response returns a jobId, the psbtBase64 to sign with the wallet key, and a summary of inputs, fee, and change. Sign it client-side, then submit via Settle payment.

Authorization: walletAuth

Body required

application/json
paymentIdstringrequired

The payment to settle, as returned by Create payment (/instant/transaction/create-payment).

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

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /instant/psbt/build-transaction-to-sign-payment
cURL
curl -X POST "$BASE_URL/instant/psbt/build-transaction-to-sign-payment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "psbtBase64": "cHNidP8BAHECAAAAAfYI0kF1pQ0i3xL0AAAAAAD9////AsBdAQAAAAAAFgAUdR5",
      "summary": {
        "fromAddress": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        "toAddress": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        "amountSats": "string",
        "feeRateSatVb": 50000,
        "estVsize": 140,
        "feeSats": "string",
        "changeSats": "string",
        "inputCount": 0
      }
    }
  }
}

Settle payment

POSThttps://api.gobtcpay.com/public/api/v1.2/instant/transaction/pay-and-sign-pre-authorized-transaction

Submits the signed payment PSBT to settle a pre-authorized payment. Send the paymentId and jobId from Build payment transaction together with the signedPsbtBase64. Returns the resulting paymentTxId and a success flag.

Authorization: walletAuth

Body required

application/json
paymentIdstring

The payment being settled (from Create payment).

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

The jobId from Build payment transaction (/instant/psbt/build-transaction-to-sign-payment).

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

The PSBT from Build payment transaction, signed with the wallet key, base64-encoded.

Example:cHNidP8BAHECAAAAAfYI0kF1pQ0i3xL0AAAAAAD9////AsBdAQAAAAAAFgAUdR5

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /instant/transaction/pay-and-sign-pre-authorized-transaction
cURL
curl -X POST "$BASE_URL/instant/transaction/pay-and-sign-pre-authorized-transaction" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "signedPsbtBase64": "cHNidP8BAHECAAAAAfYI0kF1pQ0i3xL0AAAAAAD9////AsBdAQAAAAAAFgAUdR5"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "paymentTxId": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
      "success": true
    }
  }
}

List on-chain transactions

POSThttps://api.gobtcpay.com/public/api/v1.2/instant/transaction/on-chain-list

Returns the wallet's on-chain transactions with optional dateRange and type filters. Each entry includes the tx id, amounts, fee, block number (null while unconfirmed), and the payments settled by that transaction.

Authorization: walletAuth

Body required

application/json
filtersobject

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /instant/transaction/on-chain-list
cURL
curl -X POST "$BASE_URL/instant/transaction/on-chain-list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "filters": {
    "dateRange": {
      "start": 0,
      "end": 0
    },
    "type": [
      "in"
    ]
  }
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "items": [
        {
          "tx": "02000000000101a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6071829ffffffff",
          "amountSats": "string",
          "feeSats": "string",
          "createdAt": 1718012345,
          "blockNumber": 845000,
          "type": "in",
          "paymentTxs": [
            {
              "paymentId": null,
              "paymentTxId": null,
              "status": null,
              "merchantId": null,
              "merchantName": null,
              "posTerminalLabel": null,
              "posTerminalLocation": null,
              "merchantDisplayName": null,
              "posTerminalId": null,
              "amountSats": null,
              "description": null,
              "metadata": null,
              "createdAt": null,
              "btcPriceInUsd": null,
              "currency": null,
              "amount": null,
              "currencySymbol": null,
              "btcPriceInCurrency": null
            }
          ]
        }
      ]
    }
  }
}

Cancel payment

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

Cancels a payment that has not been paid yet, use it when the order is dropped on your side. Only initiated and expired payments can be canceled; once funds are seen on-chain (detected) or confirmed (paid) the call fails with payment_not_cancelable. Cancelling an already-canceled payment succeeds and changes nothing, so retries are safe. Unlike expired, canceled is terminal: the watcher stops following the address, so late funds will not flip it to paid.

Authorization: merchantAuth

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/cancel
cURL
curl -X POST "$BASE_URL/merchant/payment/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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
    }
  }
}