HTTPS Transport Mechanism for DPP
An abstract payment protocol still has to travel over something real. This specifies how it runs over ordinary secure web requests, including the practical size limits that implies.
Summary
- Why
- Wallets and merchants need a fixed, interoperable HTTP contract for exchanging payment terms and acknowledgements, rather than each implementing DPP over HTTPS differently.
- What
- BRC-55 defines the HTTPS routes, message types, and size limits for carrying BRC-27's Direct Payment Protocol over the web.
- How
- A merchant server exposes GET and POST on /api/v1/payment/{paymentID}, returning PaymentTerms JSON on GET and accepting a Payment JSON body on POST that gets acknowledged with a PaymentACK, all over plain HTTPS with defined size limits and status codes.
What this lets you do
- Serve payment terms at a GET endpoint keyed by paymentID
- Accept a completed payment via POST and return a PaymentACK
- Cap PaymentTerms and Payment messages at 10 MB to block oversized requests
- Cap PaymentACK at 11 MB since it embeds the original Payment
- Return 400/404/500 codes for invalid, unknown, or failed paymentID lookups
Written by claude-sonnet-5 from the specification text. Where the two differ, the original is correct.
Reference for an AI
Everything an assistant needs to answer questions about BRC-55 accurately, including what it depends on.
The specification
Abstract
BRC-27 defines an abstract messaging protocol that facilitates payments on the Bitcoin SV network. This specification extends the protocol with the specifics required for a concrete HTTPS implementation that includes message size limits and HTTPS-specific implementation details.
Motivation
HTTPS is one of the most widely used transport mechanisms for internet traffic. Enabling users of HTTPS to benefit from the use of the BRC-27 DPP will facilitate increased industry adoption and growth. Defining implementation-specific stipulations for HTTPS-based DPP will address problems and ambiguities specific to this communications substrate.
Specification
Status Note
BRC-55 is the HTTPS transport for BRC-27 DPP. It is not implemented by the current bsv-blockchain/ts-sdk or bsv-blockchain/wallet-toolbox wallet substrates. Do not confuse the DPP /api/v1/payment/{paymentID} routes below with current BRC-100 wallet HTTP routes such as /createAction and /internalizeAction, or with BRC-105/BRC-121 402 payment headers.
Treat this document as external or legacy unless a deployment explicitly opts into DPP.
Below is the table with messages requested from client (wallet) to merchant (server).
The paymentID parameter is assumed to be known as a result of request between client-server before DPP protocol operation.
| MESSAGE | ENDPOINTS | TYPE/SUBTYPE | RESPONSE CODES |
|---|---|---|---|
| PaymentTerms | GET /api/v1/payment/{paymentID} | application/json | 200 – contains PaymentTerms JSON object with all data used by the payee to construct a transaction <br /> 404 – returned if the paymentID has not been found <br /> 500 – returned if there is an unexpected internal error |
| Payment | POST /api/v1/payment/{paymentID} | application/json | 201 – contains PaymentACK JSON object <br /> 400 – returned if the user input is invalid, usually an issue with the paymentID <br /> 404 – returned if the paymentID has not been found <br /> 500 – returned if there is an unexpected internal error |
PaymentTerms messages larger than 10 MB should be rejected by the wallet application, to mitigate denial-of-service attacks.
Payment messages larger than 10 MB should be rejected by the payment host’s server, to mitigate denial-of-service attacks.
PaymentACK messages larger than 11 MB bytes should be rejected by the wallet application, to mitigate denial-of-service attacks. This is larger than the limits on Payment and PaymentTerms messages as PaymentACK contains a full Payment message within it.
Implementations
The BRC-55 API is implemented in this example from Jad Wahab.