Sign in
Payments

Top up the balance from a saved card, without a browser

Changed on

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. A bank that wants a confirmation answers 402 CARD_AUTHENTICATION_REQUIRED with a dashboard_url; a decline answers 402 CARD_DECLINED. After either 402, retry with a new idempotency_key (the same key replays the 402 for 24 hours 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 after the webhook marks the row COMPLETED. 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.

post/payments/topup

Request

  • Base URL: https://lium.io/api
  • URL: https://lium.io/api/payments/topup
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

amount_usdnumber required

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_idstring nullable

A saved card (GET /stripe/payments/payment-methods). Omitted: the default card.

idempotency_keystring required

Repeat a call with the same key and amount and you get the first call's transaction back — answered from our records once Stripe has answered it (no second Stripe call), 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.

Response

Successful Response

status'succeeded' | 'processing' required
payment_intent_idstring nullable required

None when Stripe's answer to the charge call was lost.

transaction_idstring required
idempotency_keystring required

The caller's key; a retry with this key cannot charge twice.

amount_usdnumber required

Changes