Lium Payments API

The Payments API from Lium — 2 operation(s) for payments.

GitHub OpenAPI

Operations 2

POST /payments/topup Top up the balance from a saved card, without a browser #
POST /x402/topup Top up the balance with USDC on Base through x402 (HTTP 402) #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/lium-io:lium-io-payments-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

lium-io-payments-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Lium Backend Payments API
  description: '## 🚀 Lium Backend API


    A comprehensive compute platform that enables users to rent GPU resources from a network of providers/nodes.


    *Built with FastAPI, PostgreSQL and Redis.*'
  contact:
    name: Lium
    url: https://lium.io/
    email: support@lium.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
servers:
- url: /api
  description: Production API
tags:
- name: Payments
paths:
  /payments/topup:
    post:
      tags:
      - Payments
      summary: Top up the balance from a saved card, without a browser
      description: 'Charges `amount_usd` to the saved default card (or `payment_method_id`) off-session and records the pending top-up; the balance is credited by the Stripe webhook, as after a Checkout. Risk checks decide whether the charge goes off-session or steps up to a 3-D Secure challenge; a step-up, or a bank that asks for authentication, answers 402 `CARD_AUTHENTICATION_REQUIRED` with `next_action_url`: the cardholder confirms there and the webhook credits the balance, with no further call (a repeat with the same key answers the same URL). Through a key with a spending budget, a previously verified card normally charges without another confirmation. Lium asks again if it cannot confirm the earlier check, and the bank can always require confirmation. Other callers also step up past the 24-hour velocity. A step-up is authorized only and captured only when its 3-D Secure result shifted the fraud liability to the bank; otherwise the authorization is canceled and the call refused with 402 `CARD_AUTHENTICATION_UNAVAILABLE`, charged nothing. A wallet (Link, Apple Pay, Google Pay) is refused with 402 `WALLET_NOT_SUPPORTED` before anything is written or sent to the bank. A 402 without `next_action_url`, or `CARD_DECLINED`, is final: retry with a new `idempotency_key` (the same key always replays it and cannot charge twice). 202 `processing`: the row is not credited yet (first call or a repeat), or Stripe''s answer to the charge call was lost. 200 `succeeded` only once the row is COMPLETED (credited by the webhook, or by this call when it captured a confirmed step-up). First and repeat read that same row, so a succeeded PaymentIntent stays `processing` until the credit. Do not repeat the call without the returned `idempotency_key`; with it the repeat is the same transaction. The same key with a different amount is a new charge. Session, or an API key with the `billing` scope.'
      operationId: top_up_by_card_payments_topup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCardTopUpRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCardTopUpResponse'
        '202':
          description: 'processing: outcome pending, settled by the webhook'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCardTopUpResponse'
        '402':
          description: 'CARD_AUTHENTICATION_REQUIRED (with next_action_url: hand it to the cardholder; a repeat with the same idempotency_key returns the same URL until the cardholder confirms) · CARD_AUTHENTICATION_NOT_COMPLETED · CARD_AUTHENTICATION_UNAVAILABLE · CARD_AUTHENTICATION_EXPIRED (not confirmed within 7 days of the top-up''s start: canceled, nothing charged) · CARD_DECLINED · NO_SAVED_CARD · NO_DEFAULT_CARD · WALLET_NOT_SUPPORTED (Link or another wallet; charge a saved card) · API_KEY_BUDGET_EXCEEDED (a key at its budget; the body names the window)'
        '403':
          description: Feature off, key without the `billing` scope, or a workspace member's key
        '404':
          description: PAYMENT_METHOD_NOT_FOUND
        '409':
          description: The idempotency_key is recorded for another account
        '422':
          description: AMOUNT_BELOW_MINIMUM or an invalid body
        '502':
          description: STRIPE_UNAVAILABLE (retrieve/list, nothing charged) · STRIPE_REFUSED (refused before processing) · PAYMENT_NOT_COMPLETED (unexpected PaymentIntent status)
        '503':
          description: 'TOP_UP_BUSY: too many top-ups in flight on this server; nothing charged, retry'
      security:
      - JwtAccessBearer: []
      - APIKeyHeader: []
  /x402/topup:
    post:
      tags:
      - Payments
      summary: Top up the balance with USDC on Base through x402 (HTTP 402)
      description: 'Without a `PAYMENT-SIGNATURE` header: 402 with the x402 v2 payment requirements in the `PAYMENT-REQUIRED` header (and the body): scheme `exact`, USDC on Base, `amount_usd` in atomic units, Lium''s address as `payTo`. Repeat the same request with `PAYMENT-SIGNATURE` (an EIP-3009 authorization signed for those requirements, as any x402 client does): Lium has it settled, checks the transfer on chain and credits `amount_usd`. 200 with `PAYMENT-RESPONSE` (the transaction hash) once credited; 202 `processing` while the transfer is not readable on chain yet: repeat the same request. The same signature never credits twice. Session, or an API key (the login key''s rent scope is enough).'
      operationId: x402_top_up_x402_topup_post
      security:
      - JwtAccessBearer: []
      - APIKeyHeader: []
      parameters:
      - name: amount_usd
        in: query
        required: true
        schema:
          type: string
          maxLength: 20
          description: USD to add, whole cents; 1 USDC = $1
          title: Amount Usd
        description: USD to add, whole cents; 1 USDC = $1
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment-Signature
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '202':
          description: 'processing: settled, not yet read on chain; repeat the same request'
        '400':
          description: PAYMENT-SIGNATURE is not a well-formed x402 v2 payment
        '402':
          description: Payment required, refused or failed; PAYMENT-REQUIRED carries the requirements
        '403':
          description: x402 is not enabled
        '409':
          description: 'The authorization was sent for another account, or another request with it is in progress: repeat the same request'
        '422':
          description: amount_usd below the top-up minimum, above X402_MAX_TOPUP_USD, or not a number
        '502':
          description: The facilitator did not answer; nothing credited, repeat the same request
components:
  schemas:
    ToppedUpCard:
      properties:
        brand:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand
        last4:
          anyOf:
          - type: string
          - type: 'null'
          title: Last4
      type: object
      title: ToppedUpCard
    ApiCardTopUpResponse:
      properties:
        status:
          type: string
          enum:
          - succeeded
          - processing
          title: Status
        payment_intent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Intent Id
          description: None when Stripe's answer to the charge call was lost.
        transaction_id:
          type: string
          title: Transaction Id
        idempotency_key:
          type: string
          title: Idempotency Key
          description: The caller's key; a retry with this key cannot charge twice.
        amount_usd:
          type: number
          title: Amount Usd
        card:
          $ref: '#/components/schemas/ToppedUpCard'
      type: object
      required:
      - status
      - payment_intent_id
      - transaction_id
      - idempotency_key
      - amount_usd
      - card
      title: ApiCardTopUpResponse
      description: '200 `succeeded` only when the row is COMPLETED (the webhook credited the balance). 202 `processing`

        until then: first call, a repeat, Stripe still processing, or Stripe''s answer to the charge call was

        lost. First and repeated calls read that same row, so a succeeded PaymentIntent stays `processing`

        until the credit. The `charge.updated` webhook credits the balance, the same path a Checkout top-up

        takes. `transaction_id` is the row it settles (`GET /transactions`). The caller always sends

        `idempotency_key`: a lost HTTP answer plus a retry with that key cannot charge twice. The same key

        with a different amount is a new charge.'
    ApiCardTopUpRequest:
      properties:
        amount_usd:
          type: number
          maximum: 999999.99
          title: Amount Usd
          description: 'Amount to add to the balance, in USD. Charged in whole cents: a third decimal is rounded half-up (10.005 → 10.01) and the response echoes the amount charged.'
        payment_method_id:
          anyOf:
          - type: string
            maxLength: 64
            pattern: ^pm_[A-Za-z0-9]+$
          - type: 'null'
          title: Payment Method Id
          description: 'A saved card (`GET /stripe/payments/payment-methods`). Omitted: the default card.'
        idempotency_key:
          type: string
          pattern: ^[A-Za-z0-9._:-]{1,64}$
          title: Idempotency Key
          description: 'Repeat a call with the same key and amount and you get the first call''s transaction back: answered from our records once it is settled, from the payment''s current state in Stripe while it is still pending (neither charges again), replayed by Stripe (within 24 h) when the first answer was lost. Required: if the HTTP response is lost the caller still has the key, so a retry cannot open a second charge.'
      type: object
      required:
      - amount_usd
      - idempotency_key
      title: ApiCardTopUpRequest
  securitySchemes:
    JwtAccessBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key