> 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/merchant-api/payments.md). # Payments Create and inspect payments, list payment history, and build / submit the signed transaction that settles a payment. ## 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. ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account 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":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/pos/transaction/create-payment":{"post":{"summary":"Create payment","description":"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.","tags":["Payments"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"posTerminalId":{"type":"string","description":"POS terminal that accepts the payment (from **Create POS terminal**)."},"amount":{"type":"number","description":"Amount to charge, in the selected fiat `currency`."},"description":{"type":"string","description":"Optional description shown to the payer."},"currency":{"type":"string","description":"Fiat currency code (ISO 4217), e.g. `USD`."},"metadata":{"description":"Internal system metadata attached to the payment (reserved; not set by clients)."},"ttlSeconds":{"type":"number","description":"Optional lifetime of the payment in seconds; after this it expires."},"externalId":{"type":"string","description":"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."},"signature":{"type":"string","description":"Optional HMAC-SHA256 signature of the request (hex), authenticating the POS terminal with its `apiKey`."},"ts":{"type":"number","description":"Request timestamp in milliseconds, used together with `signature` for replay protection."}},"required":["posTerminalId","currency"],"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":"Unique id of the created 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)."},"merchantName":{"type":"string","description":"Merchant's internal name."},"storeId":{"type":"string","description":"Identifier of the store the payment belongs to (UUID)."},"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":"POS terminal that accepts the payment (from **Create POS terminal**)."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"amountSats":{"type":"number","description":"Amount to pay in satoshis (converted from `amount` at `btcPriceInCurrency`)."},"currency":{"type":"string","description":"Fiat currency code (ISO 4217), e.g. `USD`."},"currencySymbol":{"anyOf":[{"type":"string"},{"not":{}}],"description":"Display symbol of the currency, e.g. `$`."},"amount":{"type":"number","description":"Amount to charge, in the selected fiat `currency`."},"expiresAt":{"anyOf":[{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"},{"type":"null"}],"description":"Expiry 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."},"btcAddress":{"type":"string","description":"Bitcoin address bound to this payment; the payer sends funds here. Can be used to look the payment up later."},"qrString":{"type":"string","description":"Payment encoded as a BIP-21 URI, ready to render as a QR code."}},"required":["paymentId","status","merchantId","merchantName","storeId","posTerminalLabel","posTerminalLocation","merchantDisplayName","posTerminalId","externalId","amountSats","currency","amount","expiresAt","btcPriceInUsd","btcPriceInCurrency","btcAddress","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":"Optional description shown to the payer."},"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#"}}}}}}}}} ``` ## 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 Merchant Account 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":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/pos/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**."},"signature":{"type":"string","description":"Signature in hex format sha 256"},"ts":{"type":"number","description":"Timestamp in milliseconds"}},"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."},"storeId":{"type":"string","description":"Identifier of the store the payment belongs to (UUID)."},"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)."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Merchant's own correlation id (e.g. order / invoice id), echoed back from create-payment. Null when none was supplied."},"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","storeId","posTerminalLabel","posTerminalLocation","merchantDisplayName","posTerminalId","externalId","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 Merchant Account 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":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/pos/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},"userPubKeyHex":{"type":"string"},"posTerminalId":{"type":"string","description":"Identifier of the POS terminal (UUID)."},"signature":{"type":"string","description":"Signature in hex format sha 256"},"ts":{"type":"number","description":"Timestamp in milliseconds"}},"required":["userPubKeyHex"],"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#"}}}}}}}}} ``` --- # 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/merchant-api/payments.md?ask=&goal= ``` `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.