Velocity limits define the maximum number and cumulative amount of transactions a customer can perform. You set them separately for credit and debit activity, and — optionally — down to the individual payment method, giving you precise risk management and transaction control for each customer.

Limits are configured once per customer and enforced automatically: once a customer reaches a configured count or amount, further transactions of that type are blocked until the limit resets.

🎛️
One configuration per customer
Velocity limits are stored against a single customer, addressed by id or externalId. Sending the request again replaces the stored configuration with the values in the new request, so always send the full set you want in effect.

Common use cases

Put an overall ceiling on how many transactions, and how much value, a customer can move.
Apply tighter limits to riskier rails (for example, a low ACH debit cap) while leaving others higher.
Set different thresholds for credit and debit activity on the same customer.

How limits are structured

A velocity configuration is a single transactionLimit object with a credit and a debit side. Each side has an overall limit and an optional per-method breakdown:

Level	What it controls
`credit` / `debit`	The overall `totalCount` and `totalAmount` allowed for that direction, across all methods.
`methodControl`	Optional per-method limits within that direction. Credit supports `ach`, `card`, and `check`; debit supports `ach`, `check`, `wire`, `internationalWire`, and `virtualCard`.

Each level takes the same two values: totalCount (maximum number of transactions) and totalAmount (maximum cumulative amount).

Set velocity limits

Send a POST to /v1/customer/{parentIdType}/{customerId}/configuration/velocityControl, where parentIdType is id (the Passport-assigned reference) or externalId (your identifier).

Every request must carry the PromiseMode header: NEVER for a synchronous response, or ALWAYS for asynchronous processing.

Before you begin (all scenarios)

The customer exists, and you have its id or externalId.
You've decided the overall count and amount ceilings for credit and debit, and any per-method limits you want to enforce.

Scenario 1: Set overall credit and debit ceilings

Cap the total number and cumulative amount a customer can move in each direction, without breaking it down by method.

Request

POST /v1/customer/id/4005450/configuration/velocityControl
PromiseMode: NEVER

{
  "transactionLimit": {
    "credit": {
      "totalCount": "99999999",
      "totalAmount": "9999999.00"
    },
    "debit": {
      "totalCount": "9999999",
      "totalAmount": "9999999.00"
    }
  }
}

Scenario 2: Add per-method limits

Layer method-level ceilings on top of the overall limits — for example, a tight ACH debit cap while other rails stay higher. Include a methodControl block for the methods you want to constrain.

Request

POST /v1/customer/id/4005450/configuration/velocityControl
PromiseMode: NEVER

{
  "transactionLimit": {
    "credit": {
      "totalCount": "99999999",
      "totalAmount": "9999999.00",
      "methodControl": {
        "ach": { "totalCount": "999", "totalAmount": "999.00" },
        "card": { "totalCount": "99999999", "totalAmount": "9999999.00" },
        "check": { "totalCount": "99999999", "totalAmount": "9999999.00" }
      }
    },
    "debit": {
      "totalCount": "9999999",
      "totalAmount": "9999999.00",
      "methodControl": {
        "ach": { "totalCount": "99999", "totalAmount": "9999999.00" },
        "check": { "totalCount": "99999", "totalAmount": "9999999.00" },
        "wire": { "totalCount": "99999", "totalAmount": "9999999.00" },
        "internationalWire": { "totalCount": "99999", "totalAmount": "9999999.00" },
        "virtualCard": { "totalCount": "99999", "totalAmount": "9999999.00" }
      }
    }
  }
}

Response: 204 No Content

A successful synchronous request (PromiseMode: NEVER) returns 204 No Content. With PromiseMode: ALWAYS, the request is accepted for asynchronous processing and returns 202 Accepted. Retrieve the configuration to confirm what's stored.

Retrieve velocity limits

Send a GET to /v1/customer/{parentIdType}/{customerId}/configuration/velocityControl with the PromiseMode header to read the current configuration. The response mirrors the request and adds a lastUpdatedOn timestamp for each direction.

Request

GET /v1/customer/id/4005450/configuration/velocityControl
PromiseMode: NEVER

Response: 200 OK

{
  "transactionLimit": {
    "credit": {
      "totalCount": "99999999",
      "totalAmount": "9999999.00",
      "methodControl": {
        "ach": { "totalCount": "999", "totalAmount": "999.00" },
        "card": { "totalCount": "99999999", "totalAmount": "9999999.00" },
        "check": { "totalCount": "99999999", "totalAmount": "9999999.00" }
      },
      "lastUpdatedOn": "08/29/2025 07:44:06"
    },
    "debit": {
      "totalCount": "9999999",
      "totalAmount": "9999999.00",
      "methodControl": {
        "ach": { "totalCount": "99999", "totalAmount": "9999999.00" },
        "check": { "totalCount": "99999", "totalAmount": "9999999.00" },
        "wire": { "totalCount": "99999", "totalAmount": "9999999.00" },
        "internationalWire": { "totalCount": "99999", "totalAmount": "9999999.00" },
        "virtualCard": { "totalCount": "99999", "totalAmount": "9999999.00" }
      },
      "lastUpdatedOn": "08/29/2025 07:44:06"
    }
  }
}

Request reference

Header and path

Parameter	In	Required	Description
`PromiseMode`	header	✓	`NEVER` for a synchronous response, `ALWAYS` for asynchronous processing.
`parentIdType`	path	✓	Identifier type for the customer: `id` (Passport-assigned) or `externalId` (your identifier).
`customerId`	path	✓	The identifier value matching `parentIdType`.

`transactionLimit`

The root object. At least one direction is required.

Field	Required	Description
`credit`	✓	Velocity limits for credit transactions (see below).
`debit`	✓	Velocity limits for debit transactions (see below).

`credit` and `debit`

Each direction takes an overall limit and an optional per-method breakdown.

Field	Required	Description
`totalCount`	✓	Maximum number of transactions allowed in this direction.
`totalAmount`	✓	Maximum cumulative transaction amount in this direction.
`methodControl`	Optional	Per-method limits within this direction (see below).

`methodControl`

Optional per-method limits. Each method takes the same totalCount and totalAmount fields.

Direction	Supported methods
`credit`	`ach`, `card`, `check`
`debit`	`ach`, `check`, `wire`, `internationalWire`, `virtualCard`

Each method object:

Field	Required	Description
`totalCount`	✓	Maximum number of transactions for this method.
`totalAmount`	✓	Maximum cumulative amount for this method.

Best practices

Practice	Description
Send the full set you want in effect	A new request replaces the stored configuration. Include every direction and method you still want enforced, not just the ones you're changing.
Start with overall ceilings	Set `credit` and `debit` totals first, then add `methodControl` only where a rail needs a tighter limit.
Read back after writing	Follow a POST with a GET to confirm exactly what's stored, and check `lastUpdatedOn`.
Keep amounts as strings	`totalAmount` is a string (for example, `"9999999.00"`); send it in that format to avoid precision issues.

Velocity Limits

One configuration per customer

How limits are structured

Set velocity limits

Scenario 1: Set overall credit and debit ceilings

Scenario 2: Add per-method limits

Retrieve velocity limits

Request reference

Header and path

`transactionLimit`

`credit` and `debit`

`methodControl`

Best practices

See also