POST/v1/cards/:id/close

Close a card

Closes the card for good and returns whatever balance is left to your wallet at this store.

Required scope: cards.writeRate limit: 10 rps

Idempotent and self-reporting: the response says how much was credited, how much the platform absorbed as fees, and whether this call only replayed an earlier closure (already_refunded). A closure whose refund amount the issuer cannot confirm is refused rather than guessed.

Parameters

idstringrequired

The card ID.

Idempotency-Keystringrequired

Required, at least 8 characters. A card is refunded at most once, ever — the key is what makes a retry return that same refund instead of asking for a second one.

Code samples

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

Response

→ 200
{
  "data": {
    "id": "cm_card_01J8Z1A2BBCCDD",
    "status": "closed",
    "credited_usd": "31.0100",
    "absorbed_fee_usd": "0.0000",
    "already_refunded": false
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

Errors

Status	Code
404	`not_found` No card with this ID belongs to you at this store.
409	`provider_error` The issuer refused the closure. The card stays open and nothing was refunded.
409	`refund_amount_unknown` The card was closed upstream, but the amount to credit back could not be measured — so NOTHING was credited to your wallet and no plausible zero was substituted. The card is closed and the money is outstanding; this needs support, not a retry.
409	`close_refused` The closure was refused for a reason this endpoint passes through in the engine's own word. The card stays open and nothing was credited.
400	`idempotency_key_required` There is no Idempotency-Key header, or it is shorter than 8 characters. Close credits money into your wallet, so it will not run without a key that makes a retry return the same single refund.
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.