Create individual cards (older API versions)

Individual cards are cards issued to named individuals who are authorized representatives of your business. The individual’s name is listed against the card, and the cards may be issued as virtual or physical cards as well as added to a digital wallet if supported in the applicable region. Individual cards may be issued to employees, contractors, or any representative of the business.

Learn how to create individual cards and retrieve card details.

Before you begin

• Contact your Airwallex Account Manager to enable Cards, Issuing APIs, and other required configuration for your Airwallex account (Integration checklist).
• Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
• Make sure you have sufficient funds in your Airwallex Wallet for future card spend. For more information, see Fund your issuing balance.
• Ensure your onboarding obligations have been met and your Airwallex account is active.
• (Optional) Set up webhooks to receive notifications on card events.

Step 1: Create a cardholder

Individual cards require a cardholder against whom the card will be issued. Use Create a Cardholder API to create a cardholder object with the required parameters such as name, email, address, etc.

You must also provide the individual.express_consent_obtained parameter, and set it to yes to confirm cardholder's consent for identity verification. This consent allows Airwallex to verify the cardholder's identity with Airwallex service providers and database owners in accordance with the Identity Verification Terms

The response returns the cardholder object with all the request parameters, and the following cardholder details:

• cardholder_id: A unique identifier of the cardholder object. You can use this to:
  • Update cardholder details, see Update a cardholder API.
  • Retrieve cardholder details and status anytime, see Get cardholder details API.
• status: The status of the cardholder (see Cardholder statuses).

Example request

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/issuing/cardholders/create'
3--header 'Authorization: Bearer <your_bearer_token>'
4--data '{
5  "address": {
6      "city": "Hong Kong",
7      "country": "HK",
8      "line1": "38 Chengtu Rd",
9      "postcode": "999077",
10      "state" : "Hong Kong"
11  },
12  "email": "[email protected]",
13  "individual": {
14      "date_of_birth": "1982-11-02",
15      "express_consent_obtained": "yes",
16      "identification": {
17          "country": "US",
18          "expiry_date": "2030-08-28",
19          "number": "001238243",
20          "type": "ID_CARD"
21      },
22      "name": {
23          "first_name": "Test",
24          "last_name": "Name"
25      }
26  },
27  "mobile_number": "(257) 563-7401"
28}'

Example response

JSON
1{
2   "address": {
3       "city": "Hong Kong",
4       "country": "HK",
5       "line1": "38 Chengtu Rd",
6       "postcode": "999077",
7       "state": "Hong Kong"
8   },
9   "cardholder_id": "6357c9c9-7a1e-4ff7-a0d9-b235325a5377",
10   "email": "[email protected]",
11   "individual": {
12       "date_of_birth": "1982-11-02",
13       "identification": {
14           "country": "US",
15           "expiry_date": "2030-08-28",
16           "number": "001238243",
17           "type": "ID_CARD"
18       },
19       "name": {
20           "first_name": "Test",
21           "last_name": "Name",
22           "name_on_card": "Test Name"
23       }
24   },
25   "mobile_number": "257-5637401",
26   "status": "PENDING"
27}

Step 2: Create an individual card

After successfully creating a cardholder, create an individual card and assign it to the cardholder. Submit Create a card API request by providing the following parameters:

• issue_to: Set this to INDIVIDUAL to indicate that you want the card issued to an individual.
• cardholder_id: Use the cardholder_id returned in Create a Cardholder API response.
• form_factor: Set this to VIRTUAL or PHYSICAL (if applicable for your region). For information on requirements for physical cards, see Physical cards.
• type: The type of card. If you do not provide a value, the default configuration on your account setting is used. Possible values: PREPAID, DEBIT, GOOD_FUNDS_CREDIT.
• created_by: Your full legal name.
• request_id: Specify a unique request ID.
• authorization_controls.allowed_transaction_count: Specify whether the card is a single (SINGLE) or multi-use (MULTIPLE) card. Single-use cards can only be used for one successful debit transaction.
• authorization_controls.allowed_transaction_limits: Set limits on transactions such as transaction amount, intervals, etc. See Transaction limits.

The response returns the card object with all the request parameters, and the following card details:

• card_id: A unique identifier of the card object. You can use this to:
  • Retrieve the full PAN and CVV of your individual cardholders using Get sensitive card details API, only if you are PCI compliant (see Step 2).
  • Check if you have sufficient funds on the card for your future spend using Get card remaining limits API.
  • Retrieve details of the card object including card status anytime using Get card details API. If you want to retrieve details of all cards issued to your account, see Get all cards API.
  • Update the card object for transaction limits, allowed currencies, allowed merchant categories, etc., using Update a card API.
• card_number: A masked card number.
• card_status: The status of the card (see Card statuses). A virtual card will be automatically set to ACTIVE so you can use the card to transact immediately. For physical cards, see Activate a card.

Example request

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/issuing/cards/create'
3--header 'Authorization: Bearer <your_bearer_token>'
4--data '{ 
5   "request_id": "d1064as2-8ff0-4f9a-a5be-6d34dea8dc60",
6   "form_factor": "VIRTUAL",
7   "issue_to": "INDIVIDUAL",
8   "cardholder_id": "6357c9c9-7a1e-4ff7-a0d9-b235325a5377",
9   "note": "Client note for the card",
10   "client_metadata": "other client details",
11   "authorization_controls": {
12       "allowed_merchant_categories": [],
13       "allowed_transaction_count": "MULTIPLE",
14       "transaction_limits": {
15           "currency": "USD",
16           "limits": [
17               {
18                   "amount": 100,
19                   "interval": "PER_TRANSACTION"
20               }
21           ]
22       }
23   },
24   "created_by": "Test card"
25}'

Example response

JSON
1{
2   "authorization_controls": {
3       "allowed_currencies": [],
4       "allowed_merchant_categories": [],
5       "allowed_transaction_count": "MULTIPLE",
6       "transaction_limits": {
7           "currency": "USD",
8           "limits": [
9               {
10                   "amount": 100.0,
11                   "interval": "PER_TRANSACTION"
12               }
13           ]
14       }
15   },
16   "brand": "VISA",
17   "card_id": "d19529cb-c40a-4de8-ae8e-79fe6ced9f17",
18   "card_status": "PENDING",
19   "cardholder_id": "6357c9c9-7a1e-4ff7-a0d9-b235325a5377",
20   "created_by": "Test card",
21   "form_factor": "VIRTUAL",
22   "issue_to": "INDIVIDUAL",
23   "name_on_card": "Test Name",
24   "note": "Client note for the card",
25   "request_id": "d1064as2-8ff0-4f9a-a5be-6d34dea8dc60",
26   "type": "GOOD_FUNDS_CREDIT"
27}

Retrieve sensitive card details

As an Airwallex customer, you can retrieve sensitive card details of cardholders anytime after card creation as long as you are PCI compliant . To retrieve full PAN and CVV, call Get sensitive card details API by providing the card_id in the endpoint URL.

Alternatively, you can serve up card details via secure iframes (does not require PCI compliance).

Next steps

• Check cardholder status
• Create a commercial card
• Create a consumer card