# PacketPay HTTP Payment Mechanism Ty Everett () ## Abstract This standard describes PacketPay, a mechanism for facilitating micropayments using Bitcoin SV within HTTP requests. It relies on the [BRC-29](/payments/0029.md) payment protocol for processing payments, and [BRC-31](/peer-to-peer/0031.md) Authrite for authenticating communications between the API provider and consumer. PacketPay enables secure, per-request monetization of APIs, allowing API providers to charge consumers on a pay-per-use basis. This standard defines the required HTTP headers, the process of making and verifying payments, and the necessary steps to implement PacketPay in API interactions. ## Motivation The rapid growth of web services and APIs has created a need for efficient, secure, and scalable methods of monetizing these services. Traditional payment methods are often cumbersome and impose high fees, making them unsuitable for micropayments. PacketPay addresses this need by providing a secure, efficient, and low-cost solution for facilitating micropayments in HTTP requests. By leveraging Bitcoin SV's capabilities, PacketPay enables API providers to monetize their services on a per-request basis, and API consumers to pay only for the resources they use. ## Status Note BRC-41 is historical. Current authenticated HTTP monetization is specified by [BRC-105](/payments/0105.md), with [BRC-118](/payments/0118.md) for multipart payment body transport where needed. Simple unauthenticated 402 payment profiles are covered separately by [BRC-121](/payments/0121.md). The PacketPay JavaScript packages referenced below are deprecated for new integrations. ## Specification ### HTTP Headers PacketPay uses the following HTTP headers for facilitating payments between API consumers and providers: 1. `x-bsv-payment-satoshis-required`: Sent by the API provider in a 402 response, it indicates the number of satoshis required for the requested resource. 2. `x-bsv-payment`: Sent by the API consumer in a request to a payment-enabled API endpoint, it contains a JSON stringified object representing a [BRC-29](/payments/0029.md) payment. 3. `x-bsv-payment-satoshis-paid`: Sent by the API provider in the response to a successfully paid API request, it indicates the number of satoshis paid for the requested resource. ### PacketPay Process The PacketPay process is divided into the following stages: 1. **Authentication**: The API consumer and provider exchange [BRC-31](/peer-to-peer/0031.md) Authrite requests and responses to authenticate their identities and share necessary identity information. 2. **Initial Request**: The API consumer sends an HTTP request to the API provider without a payment. If the requested resource requires a payment, the API provider responds with a 402 status code and includes the `x-bsv-payment-satoshis-required` header, indicating the required payment amount. 3. **Payment Processing**: The API consumer reads the `x-bsv-payment-satoshis-required` header, constructs a [BRC-29](/payments/0029.md) payment message for the required amount, and includes it in the `x-bsv-payment` header of the subsequent API request. 4. **Payment Verification**: The API provider reads the `x-bsv-payment` header, verifies the payment using [BRC-29](/payments/0029.md), and processes the request if the payment is valid. 5. **Payment Acknowledgment**: The API provider sends a response containing the `x-bsv-payment-satoshis-paid` header, indicating the number of satoshis paid for the requested resource. The API consumer reads this header to confirm successful payment. ## Implementation To implement PacketPay, API providers and consumers must follow these steps: 1. Implement [BRC-29](/payments/0029.md) for processing payments and [BRC-31](/peer-to-peer/0031.md) for authenticating communications between parties. 2. For API providers, implement logic to determine the payment required for each request and include the `x-bsv-payment-satoshis-required` header in the 402 response. 3. For API consumers, implement logic to read the `x-bsv-payment-satoshis-required` header, construct a [BRC-29](/payments/0029.md) payment, and include the `x-bsv-payment` header in the subsequent request. 4. For API providers, implement logic to read and verify the `x-bsv-payment` header using [BRC-29](/payments/0029.md), process the request if the payment is valid, and include the `x-bsv-payment-satoshis-paid` header in the response. 5. For API consumers, implement logic to read the `x-bsv-payment-satoshis-paid` header and confirm successful payment. By following the above implementation steps, API providers and consumers can ensure secure and efficient micropayments using the PacketPay system. This will enable a new revenue model for APIs, allowing for greater flexibility and scalability in the ever-growing world of web services. The PacketPay [client](https://github.com/p2ppsr/packetpay-js) and [express middleware](https://github.com/p2ppsr/packetpay-express) have been implemented in JavaScript by the Babbage Team. --- # Agent Instructions: 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: ``` GET https://bsv.brc.dev/payments/0041.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.