Create cardholders

The information within this section is relevant only for API version 2024-03-31 and later. For older API versions, see Create a cardholder.

Cardholders are Airwallex’s representation of a human that uses a card. Depending on your use case, this could be an employee, contractor, payout recipient or someone who only has the ability to temporarily access a card belonging to your business. Regardless what type of card you create, it must be associated with a cardholder(s).

Before you build the cardholder integration, determine the type of cardholder (Delegate or Individual) you would like to create. See cardholder types for more information.

This tutorial will guide you through the steps to create both Delegate and Individual cardholders. Depending on the cardholder type, you can assign them to either a commercial or consumer card. See create cards.

Before you begin

Familiarize yourself with the Airwallex card program offering.
Contact your Airwallex Account Manager to enable Cards, Issuing APIs, and other required configuration for your Airwallex account (see 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.
Ensure your onboarding obligations have been met and your Airwallex account is active.

Create a cardholder

Both commercial and consumer cards require a cardholder against whom the card will be issued. Airwallex's card program supports two types of cardholders:

DELEGATE: A cardholder who may be assigned to non-personalized cards only and acts as an authorized user of the card.
INDIVIDUAL: A cardholder who may be assigned to personalized or non-personalized cards and is a named individual who is an authorized representative of your business.

Use Create a Cardholder API to create a cardholder object and provide the following fields depending on the cardholder type.

DELEGATE cardholder type requirements

type: Set this field to DELEGATE for delegate cardholder type.
email: Email address of the cardholder.
mobile_number: Optional mobile number -— can be used to receive 3D Secure (3DS) authentication step-up requests.

Shell

Example request (Delegate cardholder)

JSON

Example response (Delegate cardholder)

INDIVIDUAL cardholder type requirements

type: Set this field to INDIVIDUAL for individual cardholder type.
email: Email address of the cardholder.
individual.name.first_name: The first name of the individual.
individual.name.last_name: The last name of the individual.
individual.address: Street address of the individual.
individual.date_of_birth: The individual's date of birth, in the format YYYY-MM-DD.
individual.express_consent_obtained: Set this field to yes to confirm individual'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 .

Some regions may require additional KYC identification information such as passport, driver's license, etc., to verify cardholder's identity. If required, upload document images using File Service API and provide the file ID in the request.

Shell

Example request (Individual cardholder)

JSON

Example response (Individual cardholder)

Cardholder API response

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 using Update a cardholder API including upgrading DELEGATE type to INDIVIDUAL, see Upgrade a cardholder.
- Retrieve cardholder details and status anytime, see Get cardholder details API.
status: The status of the cardholder (see Cardholder statuses).

Upgrade a cardholder

A cardholder created as a DELEGATE type can be upgraded to an INDIVIDUAL type by calling Update a cardholder API, setting the type field to INDIVIDUAL and passing the additional information as described in individual cardholder type requirements.

Until approved (generally near instantaneous), the cardholder will remain as a DELEGATE type. Airwallex ensures that an email associated with a cardholder is unique within our system.

If a DELEGATE or INDIVIDUAL type cardholder is the only cardholder assigned to a commercial card, and the cardholder is deleted, Airwallex will automatically close the card. This is because every card must have at least one cardholder assigned to it.