API docs

Reloadable Virtual Card API

Create anonymous reloadable card accounts, top them up with crypto, issue cards from account balance, load/unload cards, and reveal card details through Onramp Pay backend proxy endpoints.

Base URL

https://onramp-pay.com/api/reloadable-cards

Reloadable cards use a private anonymous account controlled by a recovery token and session.

All money values are integer US cents. Send 5000 for $50.00, not 50.00.

Provider-only card lifecycle calls are proxied by Onramp Pay backend, so PayGate URLs are not exposed to the frontend.

Important notes

The customer must save both token and session. If they lose both, the account cannot be recovered.
Deposit/top-up creation routes through Onramp Pay for commission tracking.
Users may create more than one active deposit. Always list active deposits with their own asset, address, status, and expiry countdown.
Never send deposits on the wrong token or network. Wrong-chain deposits can be permanently lost.

GET

Sign Up

GET

https://onramp-pay.com/api/reloadable-cards/signup

Creates a new anonymous reloadable card account. The response returns a recovery token and a working session. The customer must save both because there is no email, password, or identity recovery.

Example response

OK 200

{
  "token": "NBcvfznMlfzL4ey%2BJmhdcdKVJpQBBqIxuOfZ2GFpbD0Orblz7zfywxXN4Te0Jheo%2F5vGoUuXwfrfxOd9zVOcTw%3D%3D",
  "session": "JSgPHmS2RHUFoR5bsBDw2Gklw_NghKvZs0D9nn9AaiU"
}

GET

Sign In / Recover Session

GET

https://onramp-pay.com/api/reloadable-cards/signin?token={token}&session={session}

Recovers access when a saved session is expired or invalidated. Send the token exactly as originally returned; do not decode and re-encode it.

Parameters

token: recovery token returned by signup

session: last known session value

Example response

OK 200

{
  "token": "NBcvfznMlfzL4ey%2BJmhdcdKVJpQBBqIxuOfZ2GFpbD0Orblz7zfywxXN4Te0Jheo%2F5vGoUuXwfrfxOd9zVOcTw%3D%3D",
  "session": "JSgPHmS2RHUFoR5bsBDw2Gklw_NghKvZs0D9nn9AaiU"
}

GET

Session and Balance

GET

https://onramp-pay.com/api/reloadable-cards/session?session={session}

Checks whether the session is active and returns the reloadable account balance. Money is returned in integer US cents.

Parameters

session: active reloadable account session

Example response

OK 200

{
  "balanceCents": 601
}

GET

Create Deposit

GET

https://onramp-pay.com/api/reloadable-cards/createDeposit?ticker=xmr&session={session}&amount=5000

Creates a crypto top-up intent for the reloadable account. This deposit endpoint is routed through Onramp Pay so funding stays under your commission flow. Amount is integer US cents; minimum is 3000 ($30.00).

Parameters

ticker: btc, xmr, ltc, eth, erc20/usdc, or erc20/usdt

session: active session

amount: top-up amount in US cents, minimum 3000

Example response

OK 200

{
  "ok": true,
  "id": "cmtnbkye5009jp207myrkr06t",
  "asset": "BTC",
  "status": "awaiting",
  "confirmations": 0,
  "expiresAt": "2026-09-04T20:01:13.669Z",
  "payCurrency": "btc",
  "createdAt": "2026-09-04T19:01:13.373Z",
  "minimum_amount": 0.00029,
  "network": "Bitcoin",
  "address_in": "3AtsETkcLm3rbM3fL8bWYvF8SCP4tCUybu",
  "qr_code": "base64_png_image",
  "ipn_token": "deposit_tracking_token"
}

GET

List Active Deposits

GET

https://onramp-pay.com/api/reloadable-cards/listActiveDeposits?session={session}

Returns active top-up deposits for the account. Show these as an expandable list with individual countdowns so customers can track each deposit address separately.

Parameters

session: active session

Example response

OK 200

{
  "deposits": [
    {
      "id": "cmtnbkye5009jp207myrkr06t",
      "status": "awaiting",
      "asset": "BTC",
      "amountCents": 5000,
      "expiresAt": "2026-09-04T20:01:13.669Z"
    }
  ]
}

GET

Cancel Deposit

GET

https://onramp-pay.com/api/reloadable-cards/cancelDeposit?session={session}&id={depositId}

Cancels an awaiting deposit so the customer can generate a new deposit address.

Parameters

session: active session

id: deposit intent id

Example response

OK 200

{
  "ok": true,
  "id": "cmtnbkye5009jp207myrkr06t",
  "status": "cancelled"
}

GET

Account Activity

GET

https://onramp-pay.com/api/reloadable-cards/accountActivity?session={session}

Returns account-level ledger activity such as deposits, issued-card fees, card loads, and unloads.

Parameters

session: active session

Example response

OK 200

{
  "activity": [
    {
      "type": "deposit",
      "amountCents": 5000,
      "status": "completed",
      "createdAt": "2026-09-04T19:01:13.373Z"
    }
  ]
}

GET

List Cards and Pricing

GET

https://onramp-pay.com/api/reloadable-cards/listCards?session={session}

Returns issued cards, live tier pricing, balances, card status, limits, and wallet eligibility. Render issue fees from this response instead of hardcoding prices.

Parameters

session: active session

Example response

OK 200

{
  "balanceCents": 5000,
  "tiers": {
    "aurora": { "tierPriceCents": 1995 },
    "shadow": { "tierPriceCents": 995 },
    "eclipse": { "tierPriceCents": 2995 }
  },
  "cards": [
    {
      "id": "cmtkm8nk600j7lp07gv3lis6a",
      "tier": "aurora",
      "status": "active",
      "last4": "7284",
      "spendableCents": 2500,
      "walletEligible": true
    }
  ]
}

GET

Issue Card

GET

https://onramp-pay.com/api/reloadable-cards/issueCard?session={session}&type=aurora

Issues a new card from the account balance. The card starts empty; load money onto the card after it is issued.

Parameters

session: active session

type: aurora, shadow, or eclipse

Example response

OK 200

{
  "id": "cmtkm8nk600j7lp07gv3lis6a",
  "tier": "aurora",
  "status": "issuing",
  "priceCents": 1995,
  "spendableCents": 0
}

GET

Load Card

GET

https://onramp-pay.com/api/reloadable-cards/loadCard?session={session}&id={cardId}&amount=1500

Moves funds from the reloadable account balance onto a card. Amount is integer US cents.

Parameters

session: active session

id: card id

amount: load amount in US cents, minimum 1500

Example response

OK 200

{
  "ok": true,
  "id": "cmtkm8nk600j7lp07gv3lis6a",
  "balanceCents": 1500,
  "spendableCents": 1500
}

GET

Unload Card

GET

https://onramp-pay.com/api/reloadable-cards/unloadCard?session={session}&id={cardId}&amount=1500

Moves supported card balance back into the reloadable account. Offer this only when the card reports unload support and enough unloadable balance.

Parameters

session: active session

id: card id

amount: unload amount in US cents

Example response

OK 200

{
  "ok": true,
  "id": "cmtkm8nk600j7lp07gv3lis6a",
  "unloadedCents": 1500
}

GET

Card Activity

GET

https://onramp-pay.com/api/reloadable-cards/cardActivity?session={session}&id={cardId}

Returns card-level activity, including loads, unloads, authorizations, declines, and settled transactions.

Parameters

session: active session

id: card id

Example response

OK 200

{
  "activity": [
    {
      "type": "load",
      "amountCents": 1500,
      "createdAt": "2026-09-04T21:09:13.214Z"
    }
  ]
}

GET

TOTP Status

GET

https://onramp-pay.com/api/reloadable-cards/totpStatus?session={session}

Checks whether the account has TOTP configured. Reveal and wallet-code flows may require TOTP step-up.

Parameters

session: active session

Example response

OK 200

{
  "enabled": true,
  "method": "totp"
}

GET

TOTP Setup

GET

https://onramp-pay.com/api/reloadable-cards/totpSetup?session={session}

Starts authenticator setup and returns a secret/QR payload for the customer to add to their authenticator app.

Parameters

session: active session

Example response

OK 200

{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth": "otpauth://totp/OnrampPay:reloadable?secret=JBSWY3DPEHPK3PXP"
}

GET

TOTP Submit

GET

https://onramp-pay.com/api/reloadable-cards/totpSubmit?session={session}&code=123456&setup=1

Submits a TOTP code. Use setup=1 only when enabling TOTP for the first time; otherwise omit setup.

Parameters

session: active session

code: current 6-digit authenticator code

setup: optional 1 for first-time setup

Example response

OK 200

{
  "ok": true,
  "trusted": true
}

GET

Reveal Card Number

GET

https://onramp-pay.com/api/reloadable-cards/revealCardNumber?session={session}&id={cardId}

Reveals PAN, CVV, expiry, and optional PIN for a funded card. If the response returns step_up_required, collect TOTP and call this endpoint again.

Parameters

session: active session

id: card id

Example response

OK 200

{
  "ok": true,
  "pan": "4111111111117284",
  "cvv": "123",
  "expMonth": 12,
  "expYear": 2028,
  "pin": "1234"
}

GET

Arm Wallet Code

GET

https://onramp-pay.com/api/reloadable-cards/armWalletCode?session={session}&id={cardId}&type=apple

Arms a one-minute capture window for Apple Pay or Google Pay verification codes. Customer must choose email verification in the wallet app.

Parameters

session: active session

id: card id

type: apple or google

Example response

OK 200

{
  "ok": true,
  "status": "arming",
  "armedAt": "2026-09-04T21:09:13.214Z"
}

GET

Check Wallet Code

GET

https://onramp-pay.com/api/reloadable-cards/checkWalletCode?session={session}&id={cardId}&type=apple

Polls the armed wallet-code window. Poll about every 10 seconds until status is ready or timeout.

Parameters

session: active session

id: card id

type: apple or google

Example response

OK 200

{
  "ok": true,
  "status": "ready",
  "code": "641614",
  "expiresAt": "2026-09-04T15:13:40.631Z"
}