# 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

### 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  | <p>INIT: Card opening<br>INIT <em>CREATE</em> CARD: Create Virtual Card<br>INIT <em>CREATE</em> CARD <em>HOLDER: Create Cardholder</em><br><em>INIT</em> ACTIVE <em>CARD: Activate Card</em><br><em>CREATE</em> CARD <em>FAILED</em> REFUND: Card creation failed, full refund<br>ACTIVE: Activated<br>FREEZE: Frozen<br>CANCELLING: Deleting card<br>CANCELED: Deleted<br>DELETED: Permanently delete<br>EXPIRED: Expired</p> |
| └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
}
```