{"id":21815745,"url":"https://github.com/bitcoin-com/pay.bitcoin.com","last_synced_at":"2025-03-21T09:46:49.106Z","repository":{"id":96053908,"uuid":"186545974","full_name":"Bitcoin-com/Pay.bitcoin.com","owner":"Bitcoin-com","description":"Documentation for BIP70 merchant server","archived":false,"fork":false,"pushed_at":"2019-10-02T04:27:49.000Z","size":8,"stargazers_count":1,"open_issues_count":1,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-01-26T06:25:24.730Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bitcoin-com.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-14T04:42:18.000Z","updated_at":"2021-12-26T19:12:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"f3b95069-5352-4ba7-98f2-34433d6d65ec","html_url":"https://github.com/Bitcoin-com/Pay.bitcoin.com","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bitcoin-com%2FPay.bitcoin.com","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bitcoin-com%2FPay.bitcoin.com/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bitcoin-com%2FPay.bitcoin.com/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bitcoin-com%2FPay.bitcoin.com/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bitcoin-com","download_url":"https://codeload.github.com/Bitcoin-com/Pay.bitcoin.com/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244776273,"owners_count":20508503,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-27T15:22:31.868Z","updated_at":"2025-03-21T09:46:49.082Z","avatar_url":"https://github.com/Bitcoin-com.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bitcoin.com BIP70 Merchant Server\n\nA server for the creation and fulfillment of Bitcoin Cash invoices utilizing the [BIP70 Payment Protocol](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki)\n\n## Invoice Creation\n\n### Request\n\nA POST request is made to `https://pay.bitcoin.com/create_invoice`\n\n#### POST Data\nJSON string of an output object with the following properties:\n* `script` - (optional) Hex string of desired locking script\n* `address` - (optional) Legacy or CashAddr format BCH address. P2PKH or P2SH\n* `amount` - Amount in satoshis\n* `fiatAmount` - (optional instead of `amount`) Amount denominated in `fiat`\n* `fiat` - (optional) Main asset to settle price in. Defaults to BCH if null.\n* `fiatRate` - (optional) Rate in [currency]/BCH, if currency is USD, amount is 10.0, then rate would be the USD/BCH price. If null, server will use default rate. Only available for select merchants.\n* `webhook` - (optional) URL for webhook\n* `memo` - (optional) Memo to be sent back\n* `apiKey` - Merchant's/Store's API key. This will get the merchant's settings from server. This will populate the merchant data field in the BIP70 response.\n\nEither script or address can be used. Only one is required.\n\nIf more than one output is desired send a JSON string of an object with the following properties:\n* `outputs` - An array of output objects formatted as:\n    * `script` - (optional) Hex string of desired locking script\n    * `address` - (optional) Legacy or CashAddr format BCH address. P2PKH or P2SH\n    * `amount` - Amount in satoshis\n    * `fiatAmount` - (optional instead of `amount`) Amount denominated in `fiat`\n* `currency` - (optional) Main asset to settle price in. Defaults to BCH if null.\n* `fiat` - (optional) Main asset to settle price in. Defaults to BCH if null.\n* `fiatRate` - (optional) Rate in [currency]/BCH, if currency is USD, amount is 10.0, then rate would be the USD/BCH price. If null, server will use default rate. Only available for select merchants.\n* `webhook` - (optional) URL for webhook\n* `memo` - (optional) Memo to be sent back\n* `apiKey` - Merchant's/Store's API key. This will get the merchant's settings from server. This will populate the merchant data field in the BIP70 response.\n\n#### Headers\n\n* `Content-Type` should be set to `application/json`.\n\n### Response\nThe response will be a JSON format payload quite similar to the BIP70 format.\n\n#### Body\n* `network` - Which network is this request for (main / test / regtest)\n* `currency` - Three digit currency code representing which coin the request is based on\n* `outputs` - What output(s) your transaction must include in order to be accepted\n* `time` - ISO Date format of when the invoice was generated\n* `expires` - ISO Date format of when the invoice will expire\n* `status` - The status of the invoice `open / paid / expired`\n* `merchantId` - UUID of associated merchant. If no merchant, uuid consists of all zeroes\n* `memo` - A plain text description of the payment request, can be displayed to the user / kept for records\n* `paymentUrl` - The url where the payment should be sent\n* `paymentId` - The invoice ID, can be kept for records\n* `paymentAsset` - BCH\n* `fiatSymbol` - Counter currency (like USD)\n* `fiatRate` - Rate in [currency]/BCH\n* `fiatTotal` - Sum of [outputs] amounts, denominated in [fiatSymbol]\n* `webhookUrl` - URL for webhook (if specified on invoice creation)\n\n#### Response Body Example\n```\n{\n   \"network\":\"main\",\n   \"currency\":\"BCH\",\n   \"outputs\":[\n      {\n         \"script\":\"76a914018a532856c45d74f7d67112547596a03819077188ac\",\n         \"amount\":25500,\n         \"address\":\"199PArEUmwmcch2LsjxVpegDXsomKdgYi\",\n         \"type\":\"P2PKH\"\n      }\n   ],\n   \"time\":\"2019-06-19T17:57:41.573Z\",\n   \"expires\":\"2019-06-19T18:12:41.573Z\",\n   \"status\":\"open\",\n   \"merchantId\":\"00000000-0000-0000-0000-000000000000\",\n   \"memo\":\"Your message here\",\n   \"fiatSymbol\":\"USD\",\n   \"fiatRate\":409.7,\n   \"fiatTotal\":0.1044735\n   \"paymentUrl\":\"https://pay.bitcoin.com/i/DHL7iqo2CK3hDXZK34Sry8\",\n   \"paymentId\":\"DHL7iqo2CK3hDXZK34Sry8\",\n   \"webhookUrl\":\"http://somedomain.com/webhook\"\n}\n```\n\n### Curl Example\n```\ncurl -v -L -H 'Content-Type: application/json' -d '{\"script\":\"76a914018a532856c45d74f7d67112547596a03819077188ac\",\"amount\":25500, \"webhook\":\"http://somedomain.com/webhook\", \"fiat\":\"USD\", \"memo\":\"Your message here\"}' https://pay.bitcoin.com/create_invoice\n*   Trying 13.53.78.23...\n* TCP_NODELAY set\n* Connected to pay.bitcoin.com (13.53.78.23) port 443 (#0)\n\u003e POST /create_invoice HTTP/1.1\n\u003e Host: pay.bitcoin.com\n\u003e User-Agent: curl/7.58.0\n\u003e Accept: */*\n\u003e Content-Type: application/json\n\u003e Content-Length: 78\n\u003e\n* upload completely sent off: 78 out of 78 bytes\n\u003c HTTP/1.1 200 OK\n\u003c Access-Control-Allow-Origin: *\n\u003c Content-Type: application/json\n\u003c Date: Wed, 12 Jun 2019 22:51:36 GMT\n\u003c Connection: keep-alive\n\u003c Content-Length: 451\n\u003c\n* Connection #0 to host pay.bitcoin.com left intact\n{\"network\":\"main\",\"currency\":\"BCH\",\"outputs\":[{\"script\":\"76a914018a532856c45d74f7d67112547596a03819077188ac\",\"amount\":25500,\"address\":\"199PArEUmwmcch2LsjxVpegDXsomKdgYi\",\"type\":\"P2PKH\"}],\"time\":\"2019-06-19T17:57:41.573Z\",\"expires\":\"2019-06-19T18:12:41.573Z\",\"status\":\"open\",\"merchantId\":\"00000000-0000-0000-0000-000000000000\",\"memo\":\"Your message here\",\"fiatSymbol\":\"USD\",\"fiatRate\":409.7,\"paymentUrl\":\"https://pay.bitcoin.com/i/DHL7iqo2CK3hDXZK34Sry8\",\"paymentId\":\"DHL7iqo2CK3hDXZK34Sry8\",\"webhookUrl\":\"http://somedomain.com/webhook\"}% \n```\n\n## Payment\n\nThe payment process follows the [BIP70](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki) / [BIP71](https://github.com/bitcoin/bips/blob/master/bip-0071.mediawiki) / [BIP72](https://github.com/bitcoin/bips/blob/master/bip-0072.mediawiki) specification, with a slight modification to the headers in BIP71 as follows:\n\nThe Media Type (Content-Type in HTML/email headers) for Bitcoin Cash\nprotocol messages shall be:\n\n\n| Message | Type/Subtype |\n| --- | --- |\n| PaymentRequest | application/bitcoincash-paymentrequest |\n| Payment | application/bitcoincash-payment |\n| PaymentACK | application/bitcoincash-paymentack |\n\n\n## API Endpoints\n\n### Check Status\n\n#### Request Status (Server-Sent Events)\n\nA GET request is made to `https://pay.bitcoin.com/s/{paymentId}`\n\n#### Request Status (Websockets)\n\nA Websocket Secure (WSS) request is made to `wss://pay.bitcoin.com/s/{paymentId}`\n\n#### Response\n\nServer will respond with a JSON response of the same type as the response during invoice creation.If status is \"open,\" connection will remain open until closed by client or until status changes to either \"expired\" or \"paid,\" at which time a new object will be returned and the connection will close.\n\n### Invoice Web Page\n\nVisiting `https://pay.bitcoin.com/i/{paymentId}` in a browser returns a web page. Currently this page has a centered QR code and creates a Server-Sent Events connection, logging status to console.\n\n### Invoice Merchant Data\n\nRequest made to `https://pay.bitcoin.com/m/{paymentId}` receive a JSON response containing data about the invoice and the merchant that created the payment request\n\n#### Response Body Example\n```\n{\n   \"merchantProcessor\":\"Bitcoin.com\",\n   \"merchantName\":\"Unregistered merchant\",\n   \"verification\":\"UNVERIFIED\",\n   \"invoiceCurrency\":\"USD\",\n   \"invoiceAmount\":0.0498276,\n   \"paymentCurrency\":\"BCH\",\n   \"paymentAmount\":18000,\n   \"conversionRate\":276.82,\n   \"conversionAssets\":\"USD/BCH\",\n   \"itemDesc\":\"Payment request for invoice FFbFxhisukytSvAwGqZDsD\",\n   \"email\":\"support@bitcoin.com\",\n   \"merchantWebsite\":\"https://www.bitcoin.com\",\n   \"phone\":null,\n   \"createTime\":1567108639293,\n   \"expiryTime\":1567109539293,\n   \"status\":\"open\",\n   \"outputs\":\n      [\n         {\n            \"script\":\"76a914018a532856c45d74f7d67112547596a03819077188ac\",\n            \"amount\":7500,\n            \"address\":\"199PArEUmwmcch2LsjxVpegDXsomKdgYi\",\n            \"type\":\"P2PKH\"\n         },\n         {\n            \"script\":\"76a9145d02663da9af3acde02fcd138abd998ab9edd56d88ac\",\n            \"amount\":10500,\n            \"address\":\"19UniZ1obAjU1tgUydYLzhyvaMignd1oNE\",\n            \"type\":\"P2PKH\"\n         }\n      ]\n}\n```\n\n### QR Code\n\n#### Request QR code\n\nA GET request is made to `https://pay.bitcoin.com/qr/{paymentID}`\n\n#### Response\n\nA QR code representation of a URI formatted to BIP72 specification (non-backwards compatible) is returned as a PNG image\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcoin-com%2Fpay.bitcoin.com","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitcoin-com%2Fpay.bitcoin.com","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcoin-com%2Fpay.bitcoin.com/lists"}