Lium Payments API
The Payments API from Lium — 2 operation(s) for payments.
The Payments API from Lium — 2 operation(s) for payments.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/lium-io:lium-io-payments-api"
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.
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: 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