Card APIs

Full card lifecycle: card types, issuance, balance, deposit/withdraw, freeze/unfreeze, cancel, activate (physical), PIN management, and 5 transaction query types.

Base URL: POST /api/v2.1/fincard/virtual/card/...

Support Bins (Card Types)

Returns all available card types with pricing, features, and cardholder requirements.

POST /api/v2.1/fincard/virtual/card/v2/cardTypes

Request: {} (empty body) Response data[]:

Field	Type	Description
`cardTypeId`	Long	Card type ID (use in create card)
`organization`	String	`Visa` / `MasterCard` / `Discover`
`country`	String	Issue country (ISO alpha-2)
`mode`	String	`PREPAID_CARD` / `BUDGET_CARD` (shared)
`bankCardBin`	String	Card BIN (e.g. `531993`)
`type`	String	`Virtual` / `Physical`
`category`	String	`GIFT` / `PURCHASE` / `SUBSCRIPTION` / `PHYSICAL`
`cardName`	String	Display name
`cardDesc`	String	Description
`cardPrice`	BigDecimal	Card creation fee
`cardPriceCurrency`	String	Fee currency
`support`	List	Supported merchant names (reference only)
`risk`	List	High-risk merchants (card cancellation risk)
`needCardHolder`	Boolean	true = must create cardholder first
`supportHolderRegin`	List	Supported cardholder nationalities (ISO alpha-2)
`supportHolderAreaCode`	List	Supported mobile area codes
`needDepositForActiveCard`	Boolean	Initial deposit required
`depositAmountMinQuotaForActiveCard`	BigDecimal	Min initial deposit
`depositAmountMaxQuotaForActiveCard`	BigDecimal	Max initial deposit
`fiatCurrency`	String	Card currency (e.g. `USD`)
`balanceRetentionQuota`	BigDecimal	Min balance for withdrawal
`status`	String	`online` / `offline`
`rechargeCurrency`	String	Deposit currency
`rechargeMinQuota`	BigDecimal	Min deposit amount
`rechargeMaxQuota`	BigDecimal	Max deposit amount
`rechargeFeeRate`	BigDecimal	Deposit fee rate (`1` = 1%)
`rechargeFixedFee`	BigDecimal	Fixed deposit fee
`rechargeDigital`	Integer	Deposit amount decimal places
`enableActiveCard`	Boolean	Card creation enabled
`enableDeposit`	Boolean	Deposit enabled
`enableFreeze`	Boolean	Freeze enabled
`enableUnFreeze`	Boolean	Unfreeze enabled
`metadata.cardHolderMaxCardLimit`	Integer	Max cards per cardholder
`metadata.cardHolderModel`	String	`B2B` / `B2C` (cardholder creation mode)
`metadata.spendingControls[]`	List	Default spending limits
`metadata.supportSettingMcc`	Boolean	MCC whitelist/blacklist supported

metadata.cardHolderModel B2B/B2C is an internal code — it does NOT mean company vs individual. Use it to determine which cardholder creation fields are required.

Create Card V2

Create a new virtual or physical card with initial deposit.

POST /api/v2.1/fincard/virtual/card/v2/openCard

Request:

Field	Type	Required	Description
`merchantOrderNo`	String	Yes	Client transaction ID `[20..40]`
`holderId`	Long	No	Cardholder ID (required if `needCardHolder=true`)
`cardTypeId`	Long	Yes	Card type ID from cardTypes
`amount`	BigDecimal	Yes	Initial deposit. Range: `depositAmountMin..Max`
`cardNumber`	String	No	Required for physical card (offline card number)
`accountId`	Long	No	Account ID for shared card mode (BUDGET_CARD)

Response data:

Field	Type	Description
`orderNo`	String	Platform transaction ID
`merchantOrderNo`	String	Client transaction ID
`cardNo`	String	Card ID (use for all subsequent operations)
`currency`	String	Currency
`amount`	BigDecimal	Initial deposit amount
`fee`	BigDecimal	Card creation fee
`receivedAmount`	BigDecimal	Amount credited to card
`receivedCurrency`	String	Currency
`type`	String	`create`
`status`	String	`wait_process` / `processing` / `success` / `fail`
`description`	String	Status description
`transactionTime`	Long	Millisecond timestamp

cardNo is the unique card identifier. Use it for all card operations (info, deposit, withdraw, freeze, cancel).

Card Info

Get card details, status, and optional balance.

POST /api/v2.1/fincard/virtual/card/info

Request:

Field	Type	Required	Description
`cardNo`	String	Yes	Card ID
`onlySimpleInfo`	Boolean	No	Default `true`. Set `false` for balance info

Response data:

Field	Type	Description
`cardTypeId`	Long	Card type ID
`holderId`	Long	Cardholder ID
`cardNo`	String	Card ID
`status`	String	See card statuses below
`blocked`	Boolean	Card blocked by issuer
`bindTime`	Long	Card creation time (ms)
`balanceInfo.cardNo`	String	Card ID
`balanceInfo.amount`	BigDecimal	Available balance
`balanceInfo.usedAmount`	BigDecimal	Amount used
`balanceInfo.currency`	String	Currency
`noPinPaymentAmount`	BigDecimal	PIN-free payment limit (physical)
`spendingControls[]`	List	Spending controls

Card Statuses:

Status	Description
`pending`	Card being created
`un_activated`	Physical card waiting for activation
`Normal`	Active and usable
`Freeze`	Frozen (by merchant)
`Freezing`	Freeze in progress
`UnFreezing`	Unfreeze in progress
`canceling`	Cancel in progress
`cancel`	Cancelled (permanent)
`fail`	Card creation failed

Card Sensitive Info

Get encrypted card number, CVV, and expiry date. Decrypted with merchant’s RSA private key.

POST /api/v2.1/fincard/virtual/card/info/sensitive

Request: { "cardNo": "..." } Response data:

Field	Type	Description
`cardNumber`	String	RSA-encrypted card number
`cvv`	String	RSA-encrypted CVV
`expireDate`	String	RSA-encrypted expiry date
`activateUrl`	String	Gift card redemption URL (gift cards only)

Gift cards only return activateUrl. No card number, CVV, or expiry date.

Card Balance

POST /api/v2.1/fincard/virtual/card/balance

Request: { "cardNo": "..." } Response data: { cardNo, amount, usedAmount, currency }

Card Operations

All card operations follow the same request/response pattern.

Common Request Fields

Field	Type	Required	Description
`cardNo`	String	Yes	Card ID
`merchantOrderNo`	String	Yes	Client tx ID `[20..40]`
`amount`	BigDecimal	Varies	Amount (for deposit/withdraw)
`clientRemark`	String	No	Client remark `[0..50]`

Common Response Fields

Field	Type	Description
`orderNo`	String	Platform tx ID
`merchantOrderNo`	String	Client tx ID
`cardNo`	String	Card ID
`currency`	String	Currency
`amount`	BigDecimal	Amount
`fee`	BigDecimal	Fee
`receivedAmount`	BigDecimal	Net amount
`type`	String	Operation type
`status`	String	`wait_process` / `processing` / `success` / `fail`
`description`	String	Description
`transactionTime`	Long	Millisecond timestamp

Endpoints

Operation	Path	`type`	Amount Required
Deposit	`/card/deposit`	`deposit`	Yes
Withdraw	`/card/withdraw`	`withdraw`	Yes (≥ 0.01)
Freeze	`/card/v2/freeze`	`Freeze`	No
UnFreeze	`/card/v2/unfreeze`	`UnFreeze`	No
Cancel	`/card/cancel`	`cancel`	No
Update	`/card/v2/update`	`card_update`	No
Update PIN	`/card/updatePin`	`update_pin`	No

Cancel is permanent. The card cannot be reactivated after cancellation.

Update Card — Additional Fields

The Update endpoint also accepts:

Field	Type	Description
`noPinPaymentAmount`	BigDecimal	PIN-free limit (physical cards only)
`spendingControls[]`	List	Spending limits (if `supportSetting=true`)
`riskControls.allowedMcc`	List	MCC whitelist (if `supportSettingMcc=true`)
`riskControls.blockedMcc`	List	MCC blacklist

Only one of allowedMcc or blockedMcc can be set. Send empty array [] to remove.

Update PIN — Rules

PIN must be 6 digits with these constraints:

No 3+ consecutive repeated digits
Not entirely ascending or descending
No repeated 2-3 digit segments (e.g. 123123)

Activate Card (Physical)

Activate a physical card with PIN and activation code.

POST /api/v2.1/fincard/virtual/card/activate

Request:

Field	Type	Required	Description
`merchantOrderNo`	String	Yes	Client tx ID `[20..40]`
`cardNo`	String	Yes	Card ID
`pin`	String	Yes	6-digit PIN
`activeCode`	String	Yes	Activation code (from webhook or email)
`noPinPaymentAmount`	BigDecimal	No	PIN-free limit (0-2000 USD, default 500)

Response data: { merchantOrderNo, cardNo, type: "card_activated", status, remark }

Transaction Queries

All transaction queries return { total, records[] } with pagination (pageNum, pageSize).

Card Purchase Transactions

Card fee and initial deposit records.

POST /api/v2.1/fincard/virtual/card/purchase/transaction

Card Operation Transactions (V1 / V2)

Card lifecycle operations (create, deposit, withdraw, freeze, cancel, etc.)

POST /api/v2.1/fincard/virtual/card/transaction       # V1
POST /api/v2.1/fincard/virtual/card/v2/transaction     # V2 (recommended)

Filter: type = create / deposit / cancel / Freeze / UnFreeze / withdraw / update_pin / blocked / card_update / overdraft_statement

Card Authorization Transactions

Consumption (auth), refund, verification, reversal, and maintenance fee records.

POST /api/v2.1/fincard/virtual/card/authorize/transaction

Filter: type = auth / refund / verification / Void / maintain_fee Statuses: authorized / failed / succeed

Card Authorization Fee Transactions

Fee records when card balance is insufficient for authorization fees.

POST /api/v2.1/fincard/virtual/card/auth/fee/transaction

Filter: tradeType = card_patch_fee / card_patch_cross_border

Card 3DS Transactions

3DS OTP codes, authorization URLs, and physical card activation codes.

POST /api/v2.1/fincard/virtual/card/3ds/transaction

Filter: type = third_3ds_otp / auth_url / activation_code

Field	Type	Description
`values`	String	RSA-encrypted value (OTP, URL, or activation code)
`expirationTime`	Long	Expiration time (ms)

Connectors

PaaS Journey

PaaS Operations

FinCard Virtual

Cards

Card APIs

Support Bins (Card Types)

Create Card V2

Card Info

Card Sensitive Info

Card Balance

Card Operations

Common Request Fields

Common Response Fields

Endpoints

Update Card — Additional Fields

Update PIN — Rules

Activate Card (Physical)

Transaction Queries

Card Purchase Transactions

Card Operation Transactions (V1 / V2)

Card Authorization Transactions

Card Authorization Fee Transactions

Card 3DS Transactions

​Card APIs

​Support Bins (Card Types)

​Create Card V2

​Card Info

​Card Sensitive Info

​Card Balance

​Card Operations

​Common Request Fields

​Common Response Fields

​Endpoints

​Update Card — Additional Fields

​Update PIN — Rules

​Activate Card (Physical)

​Transaction Queries

​Card Purchase Transactions

​Card Operation Transactions (V1 / V2)

​Card Authorization Transactions

​Card Authorization Fee Transactions

​Card 3DS Transactions

Card APIs

Support Bins (Card Types)

Create Card V2

Card Info

Card Sensitive Info

Card Balance

Card Operations

Common Request Fields

Common Response Fields

Endpoints

Update Card — Additional Fields

Update PIN — Rules

Activate Card (Physical)

Transaction Queries

Card Purchase Transactions

Card Operation Transactions (V1 / V2)

Card Authorization Transactions

Card Authorization Fee Transactions

Card 3DS Transactions