POST/v1/cards/:id/topup

Top up a card

Adds funds to an existing card, debited from your wallet at this store.

Required scope: cards.writeRate limit: 10 rps

If the issuer's answer is indeterminate the request returns 202 with pending:true and holds the charge for reconciliation — it does NOT close the attempt as failed, because a paid-for card must not be reported as a refusal. Retry with the same Idempotency-Key to read the settled answer.

Parameters

idstringrequired

The card ID.

amount_usdstringrequired

Amount to add, as a STRING in US dollars, up to 4 decimals, greater than 0 and at most 100000.

Idempotency-Keystringrequired

Required, at least 8 characters. A replayed key returns the stored answer and moves no money again.

Code samples

curl -X POST "https://samaprime.com/api/v1/cards/smsord_01J8X9AABBCCDD/topup" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0e7f5c1e-2b3a-4f6d-9c8b-1a2b3c4d5e6f" \
  -d '{"amount_usd":"example"}'

Response

→ 200
{
  "data": {
    "id": "cm_card_01J8Z1A2BBCCDD",
    "status": "active",
    "replayed": false
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

Errors

Status	Code
400	`validation_failed` The body is malformed or carries an unexpected field.
400	`invalid_amount` amount_usd is not a plain amount like "20.00" with at most 2 decimal places of value. Nothing is rounded, and the wallet has not been touched.
400	`idempotency_key_required` There is no Idempotency-Key header, or it is shorter than 8 characters. Top-up debits your wallet BEFORE the issuer is asked, so this endpoint refuses to run without a key.
403	`test_key_not_allowed` A test key (sk_test_) cannot move money: card writes need a live key. Nothing was reserved and the wallet was not touched.
409	`cards_unavailable` Card top-ups are temporarily unavailable: the card provider cannot serve right now (issuing paused, provider under maintenance, or its balance known to be exhausted). Refused before anything was charged — the wallet was not touched and nothing is held. This Idempotency-Key was not used up: retry later with the same key. (A key that already has an answer, such as an earlier held top-up, gets that answer back instead.)
409	`card_frozen_at_provider` The issuer reports this card frozen, so it will not accept funding. Refused before your wallet was debited.
409	`card_deleted_at_provider` The issuer no longer holds this card. Refused before the debit — nothing was charged, and the card was not closed on our side either.
409	`card_suspended_by_provider` The issuer suspended this card, and only the issuer can release it. Refused before the debit, and there is no unfreeze you can call for it.
409	`already_in_flight` Another top-up for this card is still being settled.
409	`topup_refused` The funding engine refused for a reason this endpoint passes through in the engine's own word. Nothing moved — read the message for the word it used.
422	`insufficient_balance` Your wallet at this store cannot cover the amount.
404	`not_found` No card with this ID belongs to you at this store.