Ramp.Cards (ramp v1.0.0)

The Cards resource: issuing, listing, updating, suspending, and terminating Ramp cards.

Card issuance is asynchronous on Ramp's side -- create/3 submits a deferred task and, by default, immediately blocks (via Ramp.Poller) until it completes and returns the created Ramp.Cards.Card. Pass poll: false to instead get back a Ramp.DeferredTaskRef immediately and poll it yourself later (e.g. from a different process).

Summary

Types

create_opt()

list_opt()

update_opt()

Functions

create(client, user_id, display_name, opts \\ [])

Issues a new virtual card for user_id.

get(client, card_id)

Fetches a single card by ID.

list(client, opts \\ [])

Returns a lazily auto-paginating Stream of Ramp.Cards.Cards. See Ramp.Pagination for streaming semantics.

list_page(client, opts \\ [])

Fetches a single page of cards. See Ramp.Page.

suspend(client, card_id)

Temporarily suspends a card (reversible via unsuspend/2).

terminate(client, card_id)

Permanently closes a card. This action is irreversible.

unsuspend(client, card_id)

Re-enables a suspended card.

update(client, card_id, opts)

Updates a card's display name and/or notification setting.

Types

create_opt()

@type create_opt() ::
  {:spend_limit_id, String.t()}
  | {:spend_program_id, String.t()}
  | {:idempotency_key, String.t()}
  | {:poll, boolean()}
  | {:poll_timeout_ms, pos_integer()}

list_opt()

@type list_opt() ::
  {:start, String.t()}
  | {:page_size, pos_integer()}
  | {:user_id, String.t()}
  | {:status, String.t()}
  | {:updated_after, DateTime.t()}

update_opt()

@type update_opt() ::
  {:display_name, String.t()} | {:has_notifications_enabled, boolean()}

Functions

create(client, user_id, display_name, opts \\ [])

@spec create(Ramp.Client.t(), String.t(), String.t(), [create_opt()]) ::
  {:ok, Ramp.Cards.Card.t()}
  | {:ok, Ramp.DeferredTaskRef.t()}
  | {:error, Ramp.Error.t()}

Issues a new virtual card for user_id.

Blocks and polls until issuance completes by default, returning the created Card. Pass poll: false to get a Ramp.DeferredTaskRef back immediately instead.

An :idempotency_key is strongly recommended (and generated for you if omitted) to prevent duplicate card issuance if the request is retried.

Examples

{:ok, card} = Ramp.Cards.create(client, "usr_123", "Marketing Team Card")

{:ok, task_ref} =
  Ramp.Cards.create(client, "usr_123", "Ops Card", poll: false)

get(client, card_id)

@spec get(Ramp.Client.t(), String.t()) ::
  {:ok, Ramp.Cards.Card.t()} | {:error, Ramp.Error.t()}

Fetches a single card by ID.

list(client, opts \\ [])

@spec list(Ramp.Client.t(), [list_opt()]) :: Enumerable.t(Ramp.Cards.Card.t())

Returns a lazily auto-paginating Stream of Ramp.Cards.Cards. See Ramp.Pagination for streaming semantics.

Options

:user_id - only cards belonging to this user
:status - "ACTIVE", "SUSPENDED", "TERMINATED", or "UNACTIVATED"
:updated_after - a DateTime
:page_size, :start - pagination controls (usually left to the stream)

list_page(client, opts \\ [])

@spec list_page(Ramp.Client.t(), [list_opt()]) ::
  {:ok, Ramp.Page.t(Ramp.Cards.Card.t())} | {:error, Ramp.Error.t()}

Fetches a single page of cards. See Ramp.Page.

suspend(client, card_id)

@spec suspend(Ramp.Client.t(), String.t()) :: :ok | {:error, Ramp.Error.t()}

Temporarily suspends a card (reversible via unsuspend/2).

terminate(client, card_id)

@spec terminate(Ramp.Client.t(), String.t()) :: :ok | {:error, Ramp.Error.t()}

Permanently closes a card. This action is irreversible.

unsuspend(client, card_id)

@spec unsuspend(Ramp.Client.t(), String.t()) :: :ok | {:error, Ramp.Error.t()}

Re-enables a suspended card.

update(client, card_id, opts)

@spec update(Ramp.Client.t(), String.t(), [update_opt()]) ::
  {:ok, Ramp.Cards.Card.t()} | {:error, Ramp.Error.t()}

Updates a card's display name and/or notification setting.