How a payment works
What happens on the wire between the client, your server, Penni and the blockchain, in about two seconds.
- Request. The client asks for a priced path, for example
GET /premium/report. - Price. Your server (or our middleware) answers
402 Payment Requiredwith the price in thePAYMENT-REQUIREDheader: amount, token, network and your wallet. - Signature. The client signs a transfer of exactly that amount to your wallet and sends the request again with
PAYMENT-SIGNATURE. Nothing has moved yet. - Verify. Your server sends the payment to Penni. Penni checks the signature, amount, recipient, token, validity window and the payer's balance.
- Settle. Penni submits the transfer on-chain. The tokens go from the payer straight to your wallet.
- Serve. Your server returns the content with the receipt in
PAYMENT-RESPONSE.
Headers
| Header | Direction | Holds |
|---|---|---|
PAYMENT-REQUIRED | server → client, on the 402 | Base64 JSON: x402Version, resource, accepts |
PAYMENT-SIGNATURE | client → server | Base64 JSON: the chosen option in accepted and the signed payload |
PAYMENT-RESPONSE | server → client, on the paid response | Base64 JSON: success, transaction, network, payer |
Who pays the network fee
On Base and Solana, Penni pays the network fee, so payers only need the token. On Cardano the payer pays it in ADA as part of the transaction.
Penni never holds your money
Settlement moves tokens directly from the payer to the payTo wallet of your site. Penni can only submit a transfer the payer signed, to the wallet in your site's settings. You pay Penni separately, from prepaid credits.