Payment IDs and status

Your first POST /v1/gateway/payments request returns a payment ID alongside the challenge. Keep this ID with the customer request. Send it back when validating the customer's payment credentials or checking payment status.

Use the same payment ID for retries of the same paid operation. Request a new payment for a different purchase.

Check a payment

Call GET /v1/gateway/payments/{id} using a key with gateway:read permission:

See Get payment status for the endpoint reference and error responses.

$ curl "https://api.nodana.io/v1/gateway/payments/PAYMENT_ID" \
    -H "Authorization: Bearer YOUR_API_KEY"

Replace PAYMENT_ID with the ID returned when requesting payment. Use this lookup to investigate whether a payment has arrived or a challenge has expired, without maintaining a separate payment ledger.

Response

200 OK

{
  "id": "payment-123",
  "nodeId": "node-123",
  "protocol": "mpp",
  "amountSat": 100,
  "description": "API query",
  "status": "paid"
}

The lookup returns the same fields for MPP and L402, with protocol identifying the selected protocol.

Authorise paid access

Before serving a paid operation, submit the customer's credentials to POST /v1/gateway/payments/{id}/validate, using the original payment ID in the path. A successful status lookup alone does not authorise another execution. Follow Accept payments to handle the client retry.

Payment status describes payment handling. Your application tracks whether the purchased operation completed and whether a saved result can be returned to the customer.