Marqeta.VelocityControls (marqeta v1.0.0)

Limit how much and how frequently users can spend.

Controls can be scoped to a user, card product, or entire program (null association — requires Program Manager permission).

A program supports up to 90 combined velocity + authorization controls. When multiple controls apply, the user cannot exceed any of them.

Velocity Windows

DAY, WEEK, MONTH, LIFETIME, TRANSACTION

Examples

# $500/day per user
{:ok, _} = Marqeta.VelocityControls.create(%{
  association: %{user_token: "user_01"},
  currency_code: "USD",
  amount_limit: 500.00,
  velocity_window: "DAY",
  include_purchases: true,
  include_withdrawals: true,
  include_cashback: false,
  include_credits: false,
  active: true
})

# 10 transactions/week on a card product
{:ok, _} = Marqeta.VelocityControls.create(%{
  association: %{card_product_token: "cp_01"},
  currency_code: "USD",
  amount_limit: 10_000.00,
  transaction_limit: 10,
  velocity_window: "WEEK",
  active: true
})

Summary

Functions

create(params \\ %{}, opts \\ [])

Creates a new velocity control.

create!(params \\ %{}, opts \\ [])

Creates a new velocity control. Raises Marqeta.Error on failure.

get(token, opts \\ [])

Retrieves a velocity control by token.

get!(token, opts \\ [])

Retrieves a velocity control by token. Raises Marqeta.Error on failure.

list(params \\ %{}, opts \\ [])

Lists velocity control resources.

list!(params \\ %{}, opts \\ [])

Lists velocity control resources. Raises Marqeta.Error on failure.

list_by_card_product(token, params \\ %{}, opts \\ [])

Returns velocity controls for a card product.

list_by_user(user_token, params \\ %{}, opts \\ [])

Returns velocity controls available to a user (all applicable controls).

stream(params \\ %{}, opts \\ [])

Returns a lazy Stream that auto-paginates velocity control resources.

update(token, params, opts \\ [])

Updates an existing velocity control.

update!(token, params, opts \\ [])

Updates an existing velocity control. Raises Marqeta.Error on failure.

Functions

create(params \\ %{}, opts \\ [])

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

Creates a new velocity control.

Returns {:ok, map()} on success, {:error, %Marqeta.Error{}} on failure.

create!(params \\ %{}, opts \\ [])

@spec create!(
  map(),
  keyword()
) :: map()

Creates a new velocity control. Raises Marqeta.Error on failure.

get(token, opts \\ [])

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

Retrieves a velocity control by token.

Returns {:ok, map()} on success, {:error, %Marqeta.Error{}} on failure.

get!(token, opts \\ [])

@spec get!(
  String.t(),
  keyword()
) :: map()

Retrieves a velocity control by token. Raises Marqeta.Error on failure.

list(params \\ %{}, opts \\ [])

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

Lists velocity control resources.

Accepts standard Marqeta pagination params: count, start_index, sort_by, sort_order, fields.

Use stream/2 to lazily iterate all pages automatically.

list!(params \\ %{}, opts \\ [])

@spec list!(
  map(),
  keyword()
) :: map()

Lists velocity control resources. Raises Marqeta.Error on failure.

list_by_card_product(token, params \\ %{}, opts \\ [])

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

Returns velocity controls for a card product.

list_by_user(user_token, params \\ %{}, opts \\ [])

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

Returns velocity controls available to a user (all applicable controls).

stream(params \\ %{}, opts \\ [])

@spec stream(
  map(),
  keyword()
) :: Enumerable.t()

Returns a lazy Stream that auto-paginates velocity control resources.

update(token, params, opts \\ [])

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

Updates an existing velocity control.

Returns {:ok, map()} on success, {:error, %Marqeta.Error{}} on failure.

update!(token, params, opts \\ [])

@spec update!(String.t(), map(), keyword()) :: map()

Updates an existing velocity control. Raises Marqeta.Error on failure.