API For Creating Virtual Card

Description

Create virtual card

Request URL

/open/api/card/create

Request Method

POST

Request Parameter

ParameterMandatoryTypeDescription
vidYstringCard range ID
+cardHolderNobjectCardholder
└firstNameYstringCardholder's surname [a-zA-Z] {3,}
└lastNameYstringCardholder Name [a-zA-Z] {3,}
depositYstringRecharge amount (USD), 1000 represents $10.00
orderNoYstringCustom customer transaction flow ID
callbackUrlYstringCallback Url
feeTypeYstringMonthly fee types {ONE, TWO, THREE}.

Notice:

  • In the system, the currency denomination follows a rule where the deposit amount for virtual card recharge (initial deposit) is represented using cents. For example, 1 means 1 cent, and 1000 represents $10.00. This rule applies to all monetary amounts in the system, including balance and consumption values.
  • The system allows for a single recharge amount from 5 USD to 5000 USD. This means that the minimum amount for a single recharge is 5 USD, and the maximum is 5000 USD.
  • The "vid" is the card range ID, which can be queried from API to fetch usable card range.
  • To enhance user experience, the creation of virtual cards can be performed as an asynchronous operation. After creating a virtual card, typically, the card will go through the following stages: Opening Card -> Creating Cardholder -> Creating Virtual Card -> Activating Card -> Activated
  • If the single recharge amount is >1000 USD, the system will verify whether the user's email account has completed KYC. If it is not completed, an error will be returned. The merchant can use the ACH KYC interface to complete user KYC authentication. If the user has already completed KYC authentication through another platform, the merchant can synchronize the user information through the shared KYC interface.

Request Example

{
    "cardHolder": {
        "firstName": "Milton",
        "lastName": "Schmitt"
    },
    "deposit": "1000",
    "vid": "vab_069af8a792ad",
    "orderNo": "v_5bc814",
    "callbackUrl": "https://www.baidu.com",
}

Response Parameter

+cardHolderobjectCardholder Information
└firstNamestringCardholder's surname
└lastNamestringCardholder Name
└streetstringStreet
└citystringCity
└statestringState
└countrystringCountry
└zipCodestringZipcode
+cardobjectCard information
└userIdstringUser ID
└cardHolderIdstringCardholder ID
└cardIdstringCard ID
└customerIdstringCustom Customer ID
└cardSeqNostringCARD series number
└depositintegerDeposit, 1000 represents $10.00
└consumeintegerConsumption, 1000 represents $10.00
└balanceintegerBalance, 1000 represents $10.00
└cvcstringCvc virtual card verification code, also known as cvv in VISA cards
└numberstringCard number
└cardBinstringCard section (top 6 digits of card number)
└last4stringLast four digits
└statusstringINIT: Card opening
INIT CREATE CARD: Create Virtual Card
INIT CREATE CARD HOLDER: Create Cardholder
INIT
ACTIVE CARD: Activate Card
CREATE
CARD FAILED REFUND: Card creation failed, full refund
ACTIVE: Activated
FREEZE: Frozen
CANCELLING: Deleting card
CANCELED: Deleted
DELETED: Permanently delete
EXPIRED: Expired
└statusTextstringCard Status Text
└expYearintegerCard expiration year
└expMonthintegerCard Expiration Month
└gmtCreatestringCard opening time
tagsarrayCard Label List
stringCard Label

Response Example

{
    "success": true,
    "error":false,
    "msg": "成功",
    "code": 0,
    "model": {
        "cardHolder": {
            "firstName": "Milton",
            "lastName": "Schmitt",
             "street": "1010 Pine St LOT 12-E",
             "city": "Vienna",
              "state": "GA",
              "country": "US",
              "zipCode": "31092"

        },
        "card": {
            "userId": "u_xxxxxxxx",
            "customerId" : "user_id_123",
            "cardHolderId": "ch_xxxxxxxxx",
            "holderName": "Milton Schmitt",
            "cardId": "c_xxxxxxxxx",
            "cardSeqNo": "CXXXXXXXX",
            "deposit": 1000,
            "consume": 0,
            "balance": 1000,
            "cvc": "-",
            "number": "-",
            "cardBin": "-",
            "last4": "-",
            "status": "INIT",
            "expYear": 0,
            "expMonth": 0,
            "gmtCreate": null
        },
        "tags": [
            "test"
        ]
    },
    "traceId": 1646648711017
}