PacketPay HTTP Payment Mechanism

Abstract

This standard describes PacketPay, a mechanism for facilitating micropayments using Bitcoin SV within HTTP requests. It relies on the BRC-29 payment protocol for processing payments, and BRC-31 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, with BRC-118 for multipart payment body transport where needed. Simple unauthenticated 402 payment profiles are covered separately by BRC-121. 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 [object Object] 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 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 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 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, 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 for processing payments and BRC-31 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 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, 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 deprecated PacketPay packages have been superseded by AuthFetch for authenticated client requests and the maintained payment-express-middleware package for Express servers. New integrations should use the current BRC-105, BRC-118, or BRC-121 profile described in the status note above.