Top Up Card

Fund a card from your USD card wallet. The wallet is debited first; the card’s balance reflects the top-up on success. Send a numeric amount, not a quoted string. Use your Numero API credentials and card reference; no separate third-party credentials or wallet IDs are required. The current default funding fee is USD 0.50, additional to the requested amount. A USD 1 top-up requires USD 1.50 in the USD CARD wallet and adds USD 1 to the card. Fees are configurable; do not hard-code these defaults. USD FX funds are separate.

Pending operations, settlement and alerts

HTTP 200 is not proof of completed funding. An accepted but unresolved request returns status: Pending, operationReference and operationStatus: Pending (or Review). Principal is reserved; do not resubmit while reconciliation is outstanding. Read the card and wallet statement and process your subscribed webhooks. A confirmed failure releases the reserve; a timeout is not a confirmed failure. The funding fee is posted once on successful settlement, not on a confirmed rejected deposit. Wallet principal and fee postings generate separate USD debit alerts using the normal transaction-alert layout. Alert delivery is separate from settlement and must not be used to trigger another top-up. Webhook redelivery must not create a second credit or fee.

Card endpoints use the same base URL and API key as the rest of the API, and are signature-gated: send X-Numero-Signature and X-Numero-Signature-Version: v2 as well. See Request signing.

Endpoint

POST /api/v1/business/card/{reference}/topup

Signature required: Yes

Headers

Header	Required	Description
`X-Numero-Api-Key`	Yes	Your API key
`X-Numero-Signature`	Yes	Base64 HMAC-SHA256 over the exact raw request body (POST) or the canonicalised query string (GET), keyed with your Public Key. See Request signing.
`X-Numero-Signature-Version`	Yes	Always `v2`.

Path parameters

Parameter	Type	Required	Description
`reference`	string	Yes	The card reference

Request body

Field	Type	Required	Description
`amount`	number	Yes	USD amount

Request example

curl -X POST "https://api.usenumero.com/numeroaccount/api/v1/business/card/NCRD24AD18BEBD474A/topup" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10 }'

Response

{
  "data": {
    "cardReference": "NCRD24AD18BEBD474A",
    "customerId": "NCUS9953596C2B7F45",
    "label": "Ads spend",
    "brand": "Visa",
    "firstSix": "428852",
    "lastFour": "6353",
    "expiryMonth": "06",
    "expiryYear": "2029",
    "currency": "USD",
    "balance": 25.0,
    "status": "Active",
    "isPhysical": false,
    "dailyLimit": 5000,
    "perTransactionLimit": 1000,
    "issuedAt": "2026-06-16T12:00:00Z",
    "capabilities": [
      "USD",
      "APPLE_PAY",
      "GOOGLE_PAY"
    ]
  },
  "error": null,
  "meta": {
    "request_id": "req_365123ebc73323f1482508560ce6400e",
    "pagination": null
  }
}

Getting Started

Transfers & Payouts

Collections (Virtual Accounts)

Wallet-as-a-Service

Customers

Invoices

Cards

Cardholders

Balance & Transactions

Value Added Services

Credit

Verification / KYC

Webhooks

Pending operations, settlement and alerts

Endpoint

Headers

Path parameters

Request body

Request example

Response

​Pending operations, settlement and alerts

​Endpoint

​Headers

​Path parameters

​Request body

​Request example

​Response

Pending operations, settlement and alerts

Endpoint

Headers

Path parameters

Request body

Request example

Response