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 scope: gateway:write.

Request fields

Field	Description
`nodeId`	Required. ID of a running node in your account.
`amountSat`	Required. Whole number of satoshis, from `1` to `9007199254740`.
`description`	Required. Non-blank description, up to 500 characters. Control characters are not accepted.
`protocol`	Optional: `mpp` or `l402`. Defaults to `mpp`.

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

201 Created

{
  "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.

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.

Create a payment

Request fields

Request

Response

Errors

On this page