> For the complete documentation index, see [llms.txt](https://docs.gobtcpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gobtcpay.com/api-reference/wallet-api/payments.md).

# Payments

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

## 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.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Wallet API","version":"1.45.2"},"tags":[{"name":"Payments","description":"Create and inspect payments, list payment history, and build / submit the signed transaction that settles a payment."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"walletAuth":[]}],"components":{"securitySchemes":{"walletAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Wallet access token obtained from `/instant/auth/get-jwt` via the signature challenge flow. Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/instant/auth/refresh-jwt` when it expires."}}},"paths":{"/instant/transaction/get-payment":{"post":{"summary":"Get payment","description":"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.","tags":["Payments"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentId":{"type":"string","description":"Transaction (payment) identifier — the `paymentId` returned by **Create payment**."}},"required":["paymentId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"paymentId":{"type":"string","description":"Transaction (payment) identifier — the `paymentId` returned by **Create payment**."},"status":{"type":"string","enum":["initiated","paid","failed","expired","canceled","cleared"],"description":"Payment status. One of `initiated`, `paid`, `failed`, `expired`, `canceled`, `cleared`."},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"currency":{"type":"string","description":"Fiat currency code (ISO 4217), e.g. `USD`."},"merchantName":{"type":"string","description":"Merchant's internal name."},"posTerminalLabel":{"type":["string","null"],"description":"Label of the POS terminal (may be null)."},"posTerminalLocation":{"type":["string","null"],"description":"Location of the POS terminal (may be null)."},"merchantDisplayName":{"type":["string","null"],"description":"Merchant's public display name (may be null)."},"posTerminalId":{"type":"string","description":"Identifier of the POS terminal (UUID)."},"description":{"type":"string","description":"Description shown to the payer (optional)."},"amountSats":{"type":"number","description":"Amount to pay, in satoshis."},"btcPriceInUsd":{"type":"number","description":"BTC/USD price captured when the payment was created."},"btcPriceInCurrency":{"type":"number","description":"BTC price in the payment's `currency`, captured when the payment was created."},"currencySymbol":{"anyOf":[{"type":"string"},{"not":{}}],"description":"Display symbol of the currency, e.g. `$`."},"amount":{"type":"number","description":"Amount in the payment's fiat `currency`."},"metadata":{"description":"Internal system metadata attached to the payment (reserved; not set by clients)."},"expiresAt":{"anyOf":[{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"},{"type":"null"}],"description":"Expiry time as a Unix timestamp (seconds)."},"qrString":{"type":"string","description":"Payment encoded as a BIP-21 URI, ready to render as a QR code."}},"required":["paymentId","status","merchantId","currency","merchantName","posTerminalLabel","posTerminalLocation","merchantDisplayName","posTerminalId","amountSats","btcPriceInUsd","btcPriceInCurrency","amount","expiresAt","qrString"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Description shown to the payer (optional)."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## List payments

> 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.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Wallet API","version":"1.45.2"},"tags":[{"name":"Payments","description":"Create and inspect payments, list payment history, and build / submit the signed transaction that settles a payment."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"walletAuth":[]}],"components":{"securitySchemes":{"walletAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Wallet access token obtained from `/instant/auth/get-jwt` via the signature challenge flow. Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/instant/auth/refresh-jwt` when it expires."}}},"paths":{"/instant/transaction/list":{"post":{"summary":"List payments","description":"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.","tags":["Payments"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pagination":{"type":"object","properties":{"limit":{"type":"number","minimum":1,"maximum":100,"default":20,"description":"Maximum number of items to return (1–100, default 20)."},"skip":{"type":"number","minimum":0,"default":0,"description":"Number of items to skip — offset for pagination (default 0)."}},"additionalProperties":false},"filters":{"type":"object","properties":{"dateRange":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"description":"Filter from this creation time, Unix timestamp (seconds)."},"end":{"type":"integer","minimum":0,"description":"Filter up to this creation time, Unix timestamp (seconds)."}},"required":["start","end"],"additionalProperties":false},"status":{"type":"array","items":{"type":"string","enum":["success","failed","pending","cleared"]},"description":"Filter by payment transaction status. Values: `success`, `failed`, `pending`, `cleared`."}},"additionalProperties":false}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"paymentId":{"type":"string","description":"Identifier of the payment (UUID)."},"paymentTxId":{"type":"string","description":"Id of the payment transaction."},"status":{"type":"string","enum":["success","failed","pending","cleared"],"description":"Filter by payment transaction status. Values: `success`, `failed`, `pending`, `cleared`."},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"merchantName":{"type":"string","description":"Merchant's internal name."},"posTerminalLabel":{"type":["string","null"],"description":"Label of the POS terminal (may be null)."},"posTerminalLocation":{"type":["string","null"],"description":"Location of the POS terminal (may be null)."},"merchantDisplayName":{"type":["string","null"],"description":"Merchant's public display name (may be null)."},"posTerminalId":{"type":"string","description":"Identifier of the POS terminal (UUID)."},"amountSats":{"type":"number","description":"Amount in satoshis."},"description":{"type":["string","null"],"description":"Description shown to the payer (may be null)."},"metadata":{"description":"Internal system metadata attached to the payment (reserved; not set by clients)."},"createdAt":{"type":"integer","minimum":0,"description":"Creation time as a Unix timestamp (seconds)."},"btcPriceInUsd":{"type":"number","description":"BTC/USD price captured when the payment was created."},"btcPriceInCurrency":{"type":"number","description":"BTC price in the payment's `currency`, captured when the payment was created."},"currency":{"type":"string","description":"Fiat currency code (ISO 4217), e.g. `USD`."},"amount":{"type":"number","description":"Amount in the payment's fiat `currency`."},"currencySymbol":{"anyOf":[{"type":"string"},{"not":{}}],"description":"Display symbol of the currency, e.g. `$`."},"onChain":{"anyOf":[{"type":"object","properties":{"tx":{"type":"string","description":"On-chain Bitcoin transaction id (hex)."},"amountSats":{"type":"number","description":"Amount in satoshis."},"feeSats":{"type":"number","description":"Network fee for the transaction, in satoshis."},"createdAt":{"type":"integer","minimum":0,"description":"Creation time as a Unix timestamp (seconds)."},"blockNumber":{"type":["number","null"],"description":"Height of the block that confirmed the transaction; null while unconfirmed."}},"required":["tx","amountSats","feeSats","createdAt","blockNumber"],"additionalProperties":false},{"type":"null"}],"description":"On-chain settlement details, or null if not yet settled."}},"required":["paymentId","paymentTxId","status","merchantId","merchantName","posTerminalLabel","posTerminalLocation","merchantDisplayName","posTerminalId","amountSats","description","createdAt","btcPriceInUsd","btcPriceInCurrency","currency","amount","onChain"],"additionalProperties":false}},"totalCount":{"type":"number","description":"Total number of records matching the filters."}},"required":["items","totalCount"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Description shown to the payer (may be null)."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Build payment transaction

> 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\*\*.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Wallet API","version":"1.45.2"},"tags":[{"name":"Payments","description":"Create and inspect payments, list payment history, and build / submit the signed transaction that settles a payment."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"walletAuth":[]}],"components":{"securitySchemes":{"walletAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Wallet access token obtained from `/instant/auth/get-jwt` via the signature challenge flow. Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/instant/auth/refresh-jwt` when it expires."}}},"paths":{"/instant/psbt/build-transaction-to-sign-payment":{"post":{"summary":"Build payment transaction","description":"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**.","tags":["Payments"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentId":{"type":"string","description":"The payment to settle, as returned by **Create payment** (`/instant/transaction/create-payment`)."}},"required":["paymentId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"jobId":{"type":"string","description":"Id of this PSBT build. Pass it with the signed PSBT to **Settle payment**."},"psbtBase64":{"type":"string","description":"Unsigned transaction as a base64-encoded PSBT (BIP-174). Sign it with the wallet key."},"summary":{"type":"object","properties":{"fromAddress":{"type":"string","description":"Source address — the user's multisig wallet."},"toAddress":{"type":"string","description":"Destination address — the treasury (settlement) wallet."},"amountSats":{"type":"number","description":"Amount in satoshis."},"feeRateSatVb":{"type":"number","description":"Fee rate in satoshis per virtual byte (sat/vB)."},"estVsize":{"type":"number","description":"Estimated virtual size of the transaction, in vbytes."},"feeSats":{"type":"number","description":"Network fee for the transaction, in satoshis."},"changeSats":{"type":"number","description":"Change returned to the wallet, in satoshis."},"inputCount":{"type":"number","description":"Number of inputs selected for the transaction."}},"required":["fromAddress","toAddress","amountSats","feeRateSatVb","estVsize","feeSats","changeSats","inputCount"],"additionalProperties":false}},"required":["jobId","psbtBase64","summary"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Settle payment

> 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.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Wallet API","version":"1.45.2"},"tags":[{"name":"Payments","description":"Create and inspect payments, list payment history, and build / submit the signed transaction that settles a payment."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"walletAuth":[]}],"components":{"securitySchemes":{"walletAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Wallet access token obtained from `/instant/auth/get-jwt` via the signature challenge flow. Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/instant/auth/refresh-jwt` when it expires."}}},"paths":{"/instant/transaction/pay-and-sign-pre-authorized-transaction":{"post":{"summary":"Settle payment","description":"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.","tags":["Payments"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentId":{"type":"string","description":"The payment being settled (from **Create payment**)."},"jobId":{"type":"string","description":"The `jobId` from **Build payment transaction** (`/instant/psbt/build-transaction-to-sign-payment`)."},"signedPsbtBase64":{"type":"string","description":"The PSBT from **Build payment transaction**, signed with the wallet key, base64-encoded."}},"required":["paymentId","jobId","signedPsbtBase64"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"paymentId":{"type":"string","description":"The payment being settled (from **Create payment**)."},"paymentTxId":{"type":"string","description":"Id of the resulting payment transaction."},"success":{"type":"boolean","description":"Whether the payment was accepted and broadcast."}},"required":["paymentId","paymentTxId","success"],"additionalProperties":false,"description":"Whether the payment was accepted and broadcast."}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## List on-chain transactions

> 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.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Wallet API","version":"1.45.2"},"tags":[{"name":"Payments","description":"Create and inspect payments, list payment history, and build / submit the signed transaction that settles a payment."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"walletAuth":[]}],"components":{"securitySchemes":{"walletAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Wallet access token obtained from `/instant/auth/get-jwt` via the signature challenge flow. Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/instant/auth/refresh-jwt` when it expires."}}},"paths":{"/instant/transaction/on-chain-list":{"post":{"summary":"List on-chain transactions","description":"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.","tags":["Payments"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filters":{"type":"object","properties":{"dateRange":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"description":"Filter from this creation time, Unix timestamp (seconds)."},"end":{"type":"integer","minimum":0,"description":"Filter up to this creation time, Unix timestamp (seconds)."}},"required":["start","end"],"additionalProperties":false},"type":{"type":"array","items":{"type":"string","enum":["in","out","self"]},"description":"Filter by transaction direction. Values: `in`, `out`, `self`."}},"additionalProperties":false}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"tx":{"type":"string","description":"On-chain Bitcoin transaction id (hex)."},"amountSats":{"type":"number","description":"Amount in satoshis."},"feeSats":{"type":"number","description":"Network fee for the transaction, in satoshis."},"createdAt":{"type":"integer","minimum":0,"description":"Creation time as a Unix timestamp (seconds)."},"blockNumber":{"type":["number","null"],"description":"Height of the block that confirmed the transaction; null while unconfirmed."},"type":{"type":"string","enum":["in","out","self"],"description":"Filter by transaction direction. Values: `in`, `out`, `self`."},"isPromo":{"type":"boolean","description":"Whether this transaction is a promotional credit rather than a regular transfer."},"paymentTxs":{"type":"array","items":{"type":"object","properties":{"paymentId":{"type":"string","description":"Identifier of the payment (UUID)."},"paymentTxId":{"type":"string","description":"Identifier of the payment transaction (UUID)."},"status":{"type":"string","enum":["success","failed","pending","cleared"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"merchantName":{"type":"string","description":"Merchant's internal name."},"posTerminalLabel":{"type":["string","null"],"description":"Label of the POS terminal (may be null)."},"posTerminalLocation":{"type":["string","null"],"description":"Location of the POS terminal (may be null)."},"merchantDisplayName":{"type":["string","null"],"description":"Merchant's public display name (may be null)."},"posTerminalId":{"type":"string","description":"Identifier of the POS terminal (UUID)."},"amountSats":{"type":"number","description":"Amount in satoshis."},"description":{"type":["string","null"],"description":"Human-readable description."},"metadata":{"description":"Internal system metadata attached to the payment (reserved; not set by clients)."},"createdAt":{"type":"integer","minimum":0,"description":"Creation time as a Unix timestamp (seconds)."},"btcPriceInUsd":{"type":"number","description":"BTC/USD price captured when the payment was created."},"currency":{"type":"string","description":"Fiat currency code (ISO 4217), e.g. `USD`."},"amount":{"type":"number","description":"Amount in the payment's fiat `currency`."},"currencySymbol":{"anyOf":[{"type":"string"},{"not":{}}],"description":"Display symbol of the currency, e.g. `$`."},"btcPriceInCurrency":{"type":"number","description":"BTC price in the payment's `currency`, captured when the payment was created."}},"required":["paymentId","paymentTxId","status","merchantId","merchantName","posTerminalLabel","posTerminalLocation","merchantDisplayName","posTerminalId","amountSats","description","createdAt","btcPriceInUsd","currency","amount","btcPriceInCurrency"],"additionalProperties":false}}},"required":["tx","amountSats","feeSats","createdAt","blockNumber","type","paymentTxs"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.gobtcpay.com/api-reference/wallet-api/payments.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.