Create a payment

Request a Lightning payment for an operation using MPP or L402. The payment goes to your Phoenixd node.

POST/gateway/payments

Required permission: Gateway → Write.

Body parameters

nodeIdstringRequired

ID of a running node in your account. Use List nodes to find its ID. The payment goes to this node.

amountSatintegerRequired

Payment amount in satoshis. Must be a whole number from 1 to 9007199254740, inclusive.

descriptionstringRequired

Description of the paid operation. Must be non-blank and contain no more than 500 characters. Control characters are not accepted.

protocolstringOptional

Choose mpp or l402 for the payment challenge and credential format.

Defaults to mpp.

Errors

Status	Code	What to do
`400`	`bad_request`	Check the request fields and protocol.
`401`	`unauthorized`	Check your API key and gateway permissions.
`404`	`node_not_found`	Use a node ID from the key's account.
`502`	`payment_service_unavailable`	Make sure the node is running and try again when it is ready.

See Error handling and Rate limiting for other errors and retry guidance.

Request

curl "https://api.nodana.io/v1/gateway/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "node-123",
    "amountSat": 100,
    "description": "Generate image"
  }'

For L402, include "protocol": "l402" in the request body.

Response

{
  "id": "payment-123",
  "protocol": "mpp",
  "status": "payment_required",
  "challenge": "<MPP challenge returned by Nodana>"
}

For L402, protocol is l402 and challenge contains the L402 macaroon and invoice header value.

Keep id with the operation. Return HTTP 402 to the calling client and set its WWW-Authenticate header to challenge. Your API chooses the response body. See Accept payments for MPP and L402 examples.

Challenges expire after five minutes, or sooner if the invoice expires first. Each creation request creates a new payment; retain the returned ID for retries.