Applying for a virtual card

📄 Guide

Issuing always starts with a virtual card: POST /open-api-corp/card/v1/apply returns an cardApplyId on acceptance; risk checks and card creation run fully asynchronously, with the final state pushed via the webhooks CARD_CREATED / CARD_REJECTED and GET /open-api-corp/card/v1/query-apply as the polling fallback. Once the card is created, use the cardId for single-card and list queries. For where this chain sits among the card pages, see Managing cards.

POST /open-api-corp/card/v1/apply

Request parameters

Field	Type	Required	Description
`cardApplyRef`	String	Yes	≤64; your unique application identifier
`subjectType`	String	Yes	`ORGANIZATION` (company card) / `CUSTOMER` (employee card)
`subjectId`	String	Yes	≤20; the holder’s external id: `ORGANIZATION`→`organizationId`, `CUSTOMER`→`customerId`. Must exist, match the type, be ACTIVE and belong to your partnership
`cardProfileId`	String	Yes	The card type code — one of the four types (see the pairing table below for valid `subjectType` combinations)
`custodianCustomerId`	String	Conditional	≤20; required for company cards (`subjectType`≠`CUSTOMER`): the `customerId` of an employee of the same company, who must be ACTIVE
`ruleIds`	`Array<String>`	Conditional	≤5 entries; velocity (amount/count limit) rules bound at issue time, each element a rule external id. Required for company-balance cards (the company-pool profiles, i.e. the company utility card and the corporate-funded employee card); optional for the other types

The four cardProfileId types and their subjectType pairing

A card type is the combination of two orthogonal dimensions: the holder (who the card is issued to) × the balance mode (which account the money comes from). For the full card-type introduction see Overview · Card types.

Card type	`cardProfileId`	`subjectType`	Balance mode	Custodian (`custodianCustomerId`)
Company utility card	`COMPANY_UTILITY_CARD`	`ORGANIZATION`	company pool	Required
Dedicated-purpose company card	`COMPANY_DEDICATED_PURPOSE_CARD`	`ORGANIZATION`	card’s own balance balance	Required
Employee card (company pool)	`EMPLOYEE_CARD_CORPORATE_FUNDED`	`CUSTOMER`	SHARED company pool	Not applicable
Employee card (dedicated balance)	`EMPLOYEE_CARD_SELF_FUNDED`	`CUSTOMER`	DEDICATED balance	Not applicable

Per regulatory requirements, a company card must designate a current employee of the company as its custodian. The custodian is who gets contacted when something is wrong with the card, and who completes verification when a purchase triggers a 3DS challenge.

Binding rules with ruleIds

Every rule in ruleIds must simultaneously: exist, belong to the same company, and be ACTIVE; a rule that configures amount limits must share at least one currency with the card’s settlement currencies. The array must not contain duplicates — carrying the same rule twice is rejected outright (it is not silently deduplicated), so deduplicate before submitting.

Any failing entry rejects the whole request (an early rejection before acceptance — no cardApplyId is produced); there is no partial success. After issuance you can still adjust the targets through the velocity endpoints — see Setting spend limits.

Request examples

// Scenario 1: employee card (company pool, SHARED — ruleIds required)
{
  "cardApplyRef": "ext-card-apply-0001",
  "subjectType": "CUSTOMER",
  "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "cardProfileId": "EMPLOYEE_CARD_CORPORATE_FUNDED",
  "ruleIds": ["5136744097353943556"]
}

// Scenario 2: company utility card (non-personalized — custodianCustomerId required; SHARED — ruleIds required)
{
  "cardApplyRef": "ext-card-apply-0002",
  "subjectType": "ORGANIZATION",
  "subjectId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardProfileId": "COMPANY_UTILITY_CARD",
  "custodianCustomerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "ruleIds": ["5136744097353943556"]
}

Response data and example

Field	Type	Description
`cardApplyId`	String	The card application ID
`status`	String	On successful acceptance this endpoint always returns `PENDING` (the creation result is pushed asynchronously via webhook); the full application status enum is `PENDING` / `SUCCEED` / `REJECTED`

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardApplyId": "5136744097353943553",
    "status": "PENDING"
  }
}

Error codes

Error code	Description
`CARD_PROFILE_INVALID`	Card type unavailable (e.g. invalid/disabled type code, not enabled for your partnership, or `subjectType` does not match the type’s applicable holder); see message/reason for the specifics
`CARD_LIMIT_EXCEEDED`	Over the card cap (company-level or holder-level; live cards and in-flight applications counted together); see message/reason for which level
`SUBJECT_INVALID`	Company-card custodian missing, or not a valid employee of the company
`SUBJECT_INVALID`	The holder (company) does not exist or is invalid
`CUSTOMER_INVALID`	The holding/custodian employee does not exist or is invalid
`DAPI_PERMISSION_DENIED`	Partner does not exist or is not activated (the partner identity is derived from the AK; this is an authorization issue handled by the gateway authorization codes, HTTP 401; rarely seen)
`APPLY_DUPLICATE`	An in-flight or successful application already exists for this `cardApplyRef`; it cannot be resubmitted
`CARD_RULE_REQUIRED`	A company-balance card carried no `ruleIds` (an empty array counts as none)
`CARD_RULE_DUPLICATE`	The same rule appears more than once in `ruleIds`. It is not silently deduplicated — a duplicate usually means the caller’s view of “which rules are actually bound” has drifted, and quietly collapsing it would leave you believing N rules were bound. Note: when the array both exceeds 5 entries and contains duplicates, this code is returned rather than `CARD_RULE_LIMIT_EXCEEDED`
`CARD_RULE_LIMIT_EXCEEDED`	More than 5 entries in `ruleIds`
`CARD_RULE_INVALID`	The rule does not exist, does not belong to this company, or is not ACTIVE — one code covers all three, so the response cannot be used to probe whether a rule exists under another company; see message for the specifics
`CARD_RULE_CURRENCY_NOT_MATCH`	The rule’s amount-limit currencies share no currency with the card’s settlement currencies

Related webhooks: CARD_CREATED / CARD_REJECTED.

Querying application progress

GET /open-api-corp/card/v1/query-apply?cardApplyId=5136744097353943553

The only request parameter is cardApplyId (String, required, ≤20; the card application ID). Response data:

Field	Type	Description
`cardApplyId`	String	The application ID
`status`	String	The full application status enum: `PENDING` (in acceptance / card creation) / `SUCCEED` / `REJECTED`
`cardId`	String	The card ID once created (empty before creation)
`errorCode`	String	The rejection code: fixed at `CARD_RISK_REJECTED` (only when `REJECTED`)
`errorMessage`	String	The rejection reason: fixed at `risk check refused` (only when `REJECTED`; internal risk codes are not passed through)

// Scenario 1: card created successfully
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardApplyId": "5136744097353943553",
    "status": "SUCCEED",
    "cardId": "5185740066240790530",
    "errorCode": null,
    "errorMessage": null
  }
}

// Scenario 2: rejected by risk
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardApplyId": "5136744097353943553",
    "status": "REJECTED",
    "cardId": null,
    "errorCode": "CARD_RISK_REJECTED",
    "errorMessage": "risk check refused"
  }
}

Error code: APPLY_NOT_FOUND — the application does not exist (or does not belong to your partnership).

Querying a single card

GET /open-api-corp/card/v1/query?cardId=5185740066240790530

The only request parameter is cardId (String, required, ≤20; the card ID). Response data:

Field	Type	Description
`cardId`	String	The card ID
`panFirst6`	String	First 6 digits of the PAN (the BIN; the full PAN is never returned)
`panLast4`	String	Last 4 digits of the PAN (the full PAN is never returned)
`organizationId`	String	The owning company
`subjectType`	String	`ORGANIZATION` / `CUSTOMER`
`subjectId`	String	The holder’s external id
`cardProfileId`	String	The card product code: `COMPANY_UTILITY_CARD` / `COMPANY_DEDICATED_PURPOSE_CARD` / `EMPLOYEE_CARD_CORPORATE_FUNDED` / `EMPLOYEE_CARD_SELF_FUNDED`
`cardNetwork`	String	`VISA` / `MASTERCARD` / `UPI`
`currency`	String	`USD` / `HKD`
`status`	String	Card status: `ACTIVE` / `FROZEN` / `LOCKED` / `RESTRICTED` / `LOST` / `EXPIRED` / `CLOSED`

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "panFirst6": "520983",
    "panLast4": "5492",
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "subjectType": "CUSTOMER",
    "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
    "cardProfileId": "EMPLOYEE_CARD_CORPORATE_FUNDED",
    "cardNetwork": "MASTERCARD",
    "currency": "USD",
    "status": "ACTIVE"
  }
}

Error code: CARD_INVALID — the card does not exist / does not belong to your partnership / is not ACTIVE.

Listing cards

GET /open-api-corp/card/v1/list?organizationId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&subjectType=EMPLOYEE&status=ACTIVE&page=1&pageSize=20

A paginated query over the cards under your partnership; all filters are optional:

Field	Type	Required	Description
`organizationId`	String	No	≤20; filter by owning company
`subjectType`	String	No	`ORGANIZATION` / `CUSTOMER`
`subjectId`	String	No	≤20; filter by holder
`status`	String	No	Filter by card status: `ACTIVE` / `FROZEN` / `LOCKED` / `RESTRICTED` / `LOST` / `EXPIRED` / `CLOSED`
`page`	Integer	No	Starts at 1, default 1
`pageSize`	Integer	No	1~100, default 20

Response data: the paging envelope is page (current page, Integer), pageSize (page size, Integer), total (total count) and result (the cards); each element of result carries exactly the same fields as the single-card query response above (cardId / panFirst6 / panLast4 / organizationId / subjectType / subjectId / cardProfileId / cardNetwork / cardProfileId / currency / status).

Next steps

SHARED cards need bindable velocity rules before issuance: Setting spend limits
Display the PAN and CVV2 once the card is created: Retrieving secure card details

​📄 Guide