nodana
Solutions / MPP

MPP

Accept Lightning payments for API calls with the Machine Payments Protocol and your Phoenixd node. phoenixd-mpp-sdk supplies the Lightning receiving method for mppx. Your backend sets the price, records payments and serves the result.

Set up your paid endpoint

  1. Create a Phoenixd node and save its connection URL and limited-access password. For a Nodana-hosted node, copy the URL from its details in the dashboard.
  2. Install the SDK, phoenixd-ts and mppx in your Node.js backend. Follow the SDK setup and handler example.
  3. Generate an application signing secret and use the same value across your backend instances and deployments.
  4. Choose a price in whole satoshis, such as amount: "100" for 100 sats, and implement the payment-recording functions described below.

Your backend connects directly to your node to create invoices. Return the handler's HTTP 402 challenge to the payer. A Lightning-capable MPP client pays the invoice and retries the same request with its credential. After verification and successful redemption, serve the result and attach the receipt with payment.withReceipt.

Save challenges and redeem payments

The SDK example uses two functions you implement with your application's database:

  • db.saveChallenge: save the exact challenge and its expiry before returning it to the payer.
  • db.redeemChallengeOnce: compare the submitted challenge with the saved original, check that it is unexpired and unused, then atomically mark it used and record its payment hash. Enforce uniqueness so simultaneous retries cannot redeem the same payment twice.

Return false for unknown, expired, mismatched or previously redeemed challenges. Throw on database errors and stop delivery. Run the protected operation only after verification and redemption succeed.

Record delivery against the purchase so you can recover if the operation fails after payment is redeemed. Keep your normal application authentication and permission checks.

Set invoice and challenge expiry

phoenixd.charge accepts invoiceExpirySeconds (default 3600) and an optional expected network (mainnet, regtest or signet). The payment challenge defaults to five minutes and expires no later than its invoice. You can set a shorter deadline on the handler:

const payment = await payments.charge({
  amount: "100",
  expires: new Date(Date.now() + 60_000),
})(request);

Keep issued and redeemed challenge records for at least the challenge lifetime, and retain purchase records for delivery recovery.

Test and troubleshoot

Call your endpoint with curl -i https://api.example.com/premium. Expect HTTP 402 with a WWW-Authenticate: Payment header. Use a Lightning-capable MPP client to pay and retry. Check that the result includes a Payment-Receipt header and that concurrent retries produce only one redemption.

  • The node rejects your connection: check its complete URL, availability and limited-access Phoenixd password. See API authentication.
  • Invoice creation fails: check node status and the configured network. Handle ChargeError with code invalid_invoice as a service error.
  • A paid retry is rejected: check expiry, price, signing secret and that the retry uses the same URL, method and body.
  • Redemption fails: check that the exact issued challenge was saved before returning the 402. If already redeemed, inspect the original purchase's delivery status before requesting another payment.

Use HTTPS for remote connections and keep node passwords, signing secrets and payment credentials in your backend and out of logs.

On this page