Binding and unbinding - DCS Technical Documentation

📄 Guide

Rules and targets (card CARD / employee CUSTOMER) are bound many-to-many: a rule constrains nothing after creation and only takes effect once bound. Both bind and unbind are batch endpoints that address one rule and a batch of subjects: rule-level problems (missing / not ACTIVE / not owned by the company) reject the whole batch, while subject-level problems are item-independent with partial success — the response splits results into successTargets and failTargets, with per-item reasons in failTargets[].errorCode. Rule creation is covered in Creating velocity rules; the full code set is in the Error code dictionary.

Besides the bind endpoint on this page, rules can also be bound at issue time through the ruleIds field of the card application (no more than 5) — see Applying for virtual cards. Whichever path you take, a single card or a single employee carries at most 5 rules.

Batch bind

POST /open-api-corp/velocity/v1/bind

Request parameters

Field	Type	Required	Description
`organizationId`	String	Yes	≤36; the company that owns the rule and the subjects
`ruleId`	String	Yes	≤32; the rule to bind (one request addresses a single rule)
`targets`	Array	Yes	non-empty; the subjects to bind
`targets[].subjectType`	Enum	Yes	`CARD` / `CUSTOMER`; any other value rejects the whole batch (`SUBJECT_TYPE_NOT_ALLOWED`)
`targets[].subjectId`	String	Yes	≤36; `cardId` (numeric string) for `CARD` / `customerId` for `CUSTOMER`

Response data

Field	Type	Description
`successTargets`	Array	Successful entries
`successTargets[].subjectType`	Enum	`CARD` / `CUSTOMER`
`successTargets[].subjectId`	String	The subject’s identifier
`successTargets[].errorCode`	String	Always `null` for successful entries
`successTargets[].errorMessage`	String	Always `null` for successful entries
`failTargets`	Array	Failed entries, same shape; `errorCode` / `errorMessage` carry the per-item failure reason

The endpoint returns no successCount / failCount: both equal the array lengths, and a second source of truth is avoided on purpose.

Per-item errorCode values for bind:

errorCode	Description
`SUBJECT_INVALID`	Subject missing, not ACTIVE, or not under the given company
`CARD_RULE_DUPLICATE`	The subject is already bound to this rule (no silent dedup)
`CARD_RULE_CURRENCY_NOT_MATCH`	No overlap between the rule’s currencies and the card’s chargeable currencies (chargeable = opened VA currencies ∪ card BIN currency)
`CARD_RULE_LIMIT_EXCEEDED`	The subject already has the maximum number of rules (5)

Request example

{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "ruleId": "5136744097353943556",
  "targets": [
    { "subjectType": "CARD",     "subjectId": "5136759791164443137" },
    { "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c" },
    { "subjectType": "CARD",     "subjectId": "5136765336134994434" }
  ]
}

Response example

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "successTargets": [
      { "subjectType": "CARD",     "subjectId": "5136759791164443137",
        "errorCode": null, "errorMessage": null },
      { "subjectType": "CARD",     "subjectId": "5136765336134994434",
        "errorCode": null, "errorMessage": null }
    ],
    "failTargets": [
      { "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
        "errorCode": "SUBJECT_INVALID",
        "errorMessage": "target not found or not active" }
    ]
  }
}

Batch-level error codes

Error code	Description
`ORGANIZATION_INVALID`	Company missing, not ACTIVE, or not owned by this partner
`VELOCITY_RULE_NOT_FOUND`	Rule missing, or not owned by the given company — whole batch rejected
`VELOCITY_RULE_STATUS_INVALID`	Rule not ACTIVE, cannot be bound — whole batch rejected
`SUBJECT_TYPE_NOT_ALLOWED`	Any entry’s `subjectType` is not `CARD` / `CUSTOMER` (whole batch rejected)

Batch unbind

POST /open-api-corp/velocity/v1/unbind Same shape as bind: one request addresses a single rule, items are processed independently, and one failure does not affect the rest.

Request parameters

Field	Type	Required	Description
`organizationId`	String	Yes	≤36; the company that owns the rule and the subjects
`ruleId`	String	Yes	≤32; the rule to unbind
`targets`	Array	Yes	non-empty; the subjects to unbind
`targets[].subjectType`	Enum	Yes	`CARD` / `CUSTOMER`
`targets[].subjectId`	String	Yes	≤36; `cardId` (numeric string) for `CARD` / `customerId` for `CUSTOMER`

The response has the same shape as bind (successTargets / failTargets); per-item errorCode values for unbind:

errorCode	Description
`SUBJECT_INVALID`	Subject missing, not ACTIVE, or not under the given company
`VELOCITY_BINDING_NOT_FOUND`	The subject is not bound to this rule

Request example

{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "ruleId": "5136744097353943556",
  "targets": [
    { "subjectType": "CARD",     "subjectId": "5136759791164443137" },
    { "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c" },
    { "subjectType": "CARD",     "subjectId": "5136765336134994434" }
  ]
}

Response example

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "successTargets": [
      { "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
        "errorCode": null, "errorMessage": null },
      { "subjectType": "CARD", "subjectId": "5136765336134994434",
        "errorCode": null, "errorMessage": null }
    ],
    "failTargets": [
      { "subjectType": "CARD", "subjectId": "5136759791164443137",
        "errorCode": "VELOCITY_BINDING_NOT_FOUND",
        "errorMessage": "the subject is not bound to this rule" }
    ]
  }
}

Batch-level error codes

Error code	Description
`ORGANIZATION_INVALID`	Company missing, not ACTIVE, or not owned by this partner
`VELOCITY_RULE_NOT_FOUND`	Rule missing, or not owned by the given company
`SUBJECT_TYPE_NOT_ALLOWED`	Any entry’s `subjectType` is not `CARD` / `CUSTOMER` (whole batch rejected)

Listing a rule’s targets

GET /open-api-corp/velocity/v1/list-rule-targets — lists the cards and employees bound to a rule, paginated, newest binding first.

Field	Type	Required	Description
`organizationId`	String	Yes	≤20
`ruleId`	String	Yes	≤32
`page`	Integer	No	Page number, from 1, default 1
`pageSize`	Integer	No	Page size, default 20, capped at 100 (values above are truncated to 100)

The response data is a page: total / page / pageSize plus result[], each entry carrying subjectType (CARD / CUSTOMER), subjectId, and modifyTime (ISO-8601).

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "result": [
      { "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c", "modifyTime": "2026-08-12T11:05:00Z" },
      { "subjectType": "CARD",     "subjectId": "5136759791164443137",                  "modifyTime": "2026-08-12T11:00:00Z" }
    ]
  }
}

Error code	Description
`VELOCITY_RULE_NOT_FOUND`	Rule does not exist, or does not belong to the requesting `organizationId` (no empty page is returned — an empty page would be indistinguishable from “the rule exists but has no targets”)

Returning an error instead of an empty page when the rule does not exist is deliberate: an empty page would be indistinguishable from “the rule exists but has no targets”. When you receive an empty result, you can be sure the rule exists and simply has nothing bound to it yet.

Listing the rules constraining a target

GET /open-api-corp/velocity/v1/list-target-rules — lists the rules constraining a card / employee, paginated.

Field	Type	Required	Description
`organizationId`	String	Yes	≤20
`subjectType`	Enum	Yes	`CARD` / `CUSTOMER`
`subjectId`	String	Yes	≤36; `cardId` (numeric string) for `CARD` / `customerId` for `CUSTOMER`
`status`	Boolean	No	Default `true`: return `ACTIVE` rules only; pass `false` to include `INACTIVE`
`page`	Integer	No	Page number, from 1, default 1
`pageSize`	Integer	No	Page size, default 20, capped at 100 (values above are truncated to 100)

The response data is a page: total (the number of rules bound to this target) / page / pageSize plus result[], each entry carrying ruleId, ruleName, status (ACTIVE / INACTIVE), and modifyTime.

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "result": [
      { "ruleId": "R000457", "ruleName": "Cash advance control",     "status": "ACTIVE", "modifyTime": "2026-08-12T11:10:00Z" },
      { "ruleId": "R000456", "ruleName": "Employee travel", "status": "ACTIVE", "modifyTime": "2026-08-12T11:00:00Z" }
    ]
  }
}

Error code	Description
`SUBJECT_TYPE_NOT_ALLOWED`	`subjectType` is not `CARD` / `CUSTOMER`

Next steps

Query the merged quota and current usage once targets take effect: Quota query and adjustment
How bound rules participate in authorization: Authorization and 3DS

​📄 Guide

​Batch bind

​Request parameters

​Response data

​Request example

​Response example

​Batch-level error codes

​Batch unbind

​Request parameters

​Request example

​Response example

​Batch-level error codes

​Listing a rule’s targets

​Listing the rules constraining a target

​Next steps

📄 Guide

Batch bind

Request parameters

Response data

Request example

Response example

Batch-level error codes

Batch unbind

Request parameters

Request example

Response example

Batch-level error codes

Listing a rule’s targets

Listing the rules constraining a target

Next steps