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
{} (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
| 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) |
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
| Field | Type | Required | Description |
|---|
cardNo | String | Yes | Card ID |
onlySimpleInfo | Boolean | No | Default true. Set false for balance info |
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 |
| 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
{ "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
{ "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
| 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) |
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)
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
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
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
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) |
