@spec activate(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.Card.t()} | {:error, Railsr.Error.t()}

Activate a card (moves from pending to active).

@spec cancel(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.Card.t()} | {:error, Railsr.Error.t()}

Cancel a card permanently.

@spec create(
  map(),
  keyword()
) :: {:ok, Railsr.Types.Card.t()} | {:error, Railsr.Error.t()}

Create a virtual or physical card.

Required params

• :ledger_id — the ledger this card is funded from

• :card_type — "virtual" | "physical"

• :card_programme_id — BIN programme to issue against

Optional

• :card_holder_name — printed name (physical cards)
• :physical_delivery_address — delivery address map (physical only)
• :metadata

@spec create_payment_token(String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Railsr.Error.t()}

Provision a digital wallet token (Apple Pay / Google Pay) — Labs API.

Requires MeaWallet integration to be enabled on your card programme.

Params

• :wallet_provider — "apple_pay" | "google_pay"

• :nonce — provider-supplied provisioning nonce
• :nonce_signature — signed nonce from wallet provider SDK
• :certificates — certificate chain (Apple Pay)

@spec create_rule(String.t(), map(), keyword()) ::
  {:ok, Railsr.Types.CardRule.t()} | {:error, Railsr.Error.t()}

Create a spend-control rule on a card.

Rule types

Amount limit

%{
  rule_type: "amount_limit",
  limit_amount: 10_000,      # pence
  limit_currency: "GBP",
  limit_interval: "daily"    # "transaction" | "daily" | "weekly" | "monthly"
}

MCC block (block specific merchant categories)

%{rule_type: "mcc_block", mcc_list: ["7995", "6011"]}

Country block

%{rule_type: "country_block", country_list: ["CN", "RU"]}

@spec delete_rule(String.t(), String.t(), keyword()) ::
  :ok | {:error, Railsr.Error.t()}

Delete a card rule.

@spec freeze(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.Card.t()} | {:error, Railsr.Error.t()}

Freeze a card (temporarily blocks all transactions).

@spec get(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.Card.t()} | {:error, Railsr.Error.t()}

Retrieve a card by ID.

@spec get_pan(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Railsr.Error.t()}

Retrieve full PAN, CVV, and expiry via MeaWallet secure display.

The raw PAN is never returned in plaintext to the server — only via the secure MeaWallet widget rendered client-side.

@spec get_programme(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.CardProgramme.t()} | {:error, Railsr.Error.t()}

Get a specific card programme.

@spec get_rule(String.t(), String.t(), keyword()) ::
  {:ok, Railsr.Types.CardRule.t()} | {:error, Railsr.Error.t()}

Get a specific card rule.

@spec list(
  map(),
  keyword()
) :: {:ok, [Railsr.Types.Card.t()]} | {:error, Railsr.Error.t()}

List cards.

Query params

• :ledger_id
• :enduser_id
• :card_type
• :status
• :limit / :offset

@spec list_payment_tokens(
  String.t(),
  keyword()
) :: {:ok, list()} | {:error, Railsr.Error.t()}

List digital wallet tokens provisioned on a card — Labs API.

@spec list_programmes(keyword()) ::
  {:ok, [Railsr.Types.CardProgramme.t()]} | {:error, Railsr.Error.t()}

List card programmes available for the customer.

@spec list_rules(
  String.t(),
  keyword()
) :: {:ok, [Railsr.Types.CardRule.t()]} | {:error, Railsr.Error.t()}

List all rules on a card.

@spec list_transactions(String.t(), map(), keyword()) ::
  {:ok, list()} | {:error, Railsr.Error.t()}

List card transactions (authorisations, clearings, refunds).

Query params

• :from / :to — ISO 8601 datetimes

• :transaction_type — "card-debit" | "card-credit"

• :limit / :offset

@spec replace(String.t(), map(), keyword()) ::
  {:ok, Railsr.Types.Card.t()} | {:error, Railsr.Error.t()}

Replace a card (lost, stolen, or damaged).

Params

• :replacement_reason — "lost" | "stolen" | "damaged" | "expired"

• :card_type — optional, defaults to same type as original
• :physical_delivery_address — required for physical replacements

@spec reset_pin_attempts(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Railsr.Error.t()}

Reset PIN attempt counter after lockout (Debit-Card-2/3 only).

@spec suspend(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.Card.t()} | {:error, Railsr.Error.t()}

Suspend a card (admin-level suspension).

@spec unfreeze(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.Card.t()} | {:error, Railsr.Error.t()}

Unfreeze a card (re-activates a frozen card).

@spec update_status(String.t(), String.t(), keyword()) ::
  {:ok, Railsr.Types.Card.t()} | {:error, Railsr.Error.t()}

Generic card status update.