API For Creating Virtual Card

Description

Create virtual card

Request URL

/open/api/card/create

Request Method

POST

Request Parameter

Parameter	Mandatory	Type	Description
vid	Y	string	Card range ID
+cardHolder	N	object	Cardholder
└firstName	Y	string	Cardholder's surname [a-zA-Z] {3,}
└lastName	Y	string	Cardholder Name [a-zA-Z] {3,}
deposit	Y	string	Recharge amount (USD), 1000 represents $10.00
orderNo	Y	string	Custom customer transaction flow ID
callbackUrl	Y	string	Callback Url

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",
    "customerId": "user_id_123",
}

Response Parameter


+cardHolder	object	Cardholder Information
└firstName	string	Cardholder's surname
└lastName	string	Cardholder Name
└street	string	Street
└city	string	City
└state	string	State
└country	string	Country
└zipCode	string	Zipcode
+card	object	Card information
└userId	string	User ID
└cardHolderId	string	Cardholder ID
└cardId	string	Card ID
└customerId	string	Custom Customer ID
└cardSeqNo	string	CARD series number
└deposit	integer	Deposit, 1000 represents $10.00
└consume	integer	Consumption, 1000 represents $10.00
└balance	integer	Balance, 1000 represents $10.00
└cvc	string	Cvc virtual card verification code, also known as cvv in VISA cards
└number	string	Card number
└cardBin	string	Card section (top 6 digits of card number)
└last4	string	Last four digits
└status	string	INIT: 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
└statusText	string	Card Status Text
└expYear	integer	Card expiration year
└expMonth	integer	Card Expiration Month
└gmtCreate	string	Card opening time
tags	array	Card Label List
└	string	Card 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
}