Cardholders
You can create cardholders, which are authorized representatives of your business that can be issued cards.
Please note, this API version is incompatible with any Airwallex Business Account Products such as "Borderless Cards" or "Expense Management" via Airwallex web or mobile applications. If you're using any of these products, please use API version 2024-02-22. Contact your account manager for more information and to verify compatibility.
POST /api/v1/issuing/cardholders/createGET /api/v1/issuing/cardholdersGET /api/v1/issuing/cardholders/{id}POST /api/v1/issuing/cardholders/{id}/updatePOST /api/v1/issuing/cardholders/{id}/delete
Create a cardholder
POST /api/v1/issuing/cardholders/create
Cardholders are an authorized representative of your business. Two types of cardholder are permissible, Individual and Delegate.
INDIVIDUAL: A cardholder who is associated with a named individual that is a representative of your business. Can be associated with a personalized or non-personalized card.
DELEGATE: A cardholder who may be assigned to non-personalized cards only and acts as an authorized user of the card.
Any cards attached to delegate cardholders are associated with the name of your business. Creation of cardholders involves passing a name screening process which requires some basic details about the cardholder.
Email address of the cardholder.
Details about the cardholder. Only relevant for individual cardholder type.
Street address of the cardholder.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
For Canada entities only - By setting this field to yes you confirm that you have the express consent of this.
The individual's date of birth, in the format YYYY-MM-DD.
Information of the individual's employers.
Local business registration number i.e. an official signal of identification for the business.
Country code. (2-letter ISO 3166-2 country code)
Local business registration number i.e. an official signal of identification for the business.
Type of business registration number, depending on what's applicable to the country the business is registered in.
BRN, EIN, SSN, VAT
Name of the employer.
By setting this field to yes you confirm that you have the express consent of this cardholder for Airwallex to perform name and sanction screening or any further identity verification if required.
Identification of the individual cardholder. This object is optional and is only required if name screening fails or if Airwallex deem necessary for your integration.
ISO country code of identification document.
The unique identifier for an image of the back of the given document. This can be retrieved by uploading a file to the file upload endpoint within the API.
The unique identifier for an image of the front of the given document. This can be retrieved by uploading a file to the file upload endpoint within the API.
Expiry date of the identification document provided, in the format YYYY-MM-DD.
Gender as specified on UK drivers license. Not required for other identification types.
M, F
Document number. May be a license number or passport number.
State the document was issued in. Required only if type is DRIVERS_LICENSE and country is AU.
Type of identification being provided. May be PASSPORT, DRIVERS_LICENSE, or ID_CARD.
The full name of the Individual. Only characters in English are supported.
First name of cardholder.
Last name for cardholder.
Optional middle name of cardholder.
Optional title of cardholder.
The 2-letter ISO country code for the individual's nationality.
For Canada entities only - By setting this field to yes you confirm that you consent to paperless notifications. You agree to the Electronic Communications Consent Agreement which states that we may provide you with all disclosures, notices and other communications, about Airwallex's services including this Agreement and any further amendments, in electronic form.
For Canada entities only - By setting this field to yes you confirm that you consent to the terms of the Privacy Policy.
The tax identification number for the individual cardholder. Used for customs or regulatory reporting when required by the shipping destination. Format and requirements may differ by country.
Mobile number of the cardholder.
Optional postal address of the cardholder. Only required if different to address and physical cards are to be issued.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
The type of cardholder. One of INDIVIDUAL or DELEGATE, which are defined as follows:
INDIVIDUAL: A cardholder who is associated with a named individual that is a representative of your business. Can be associated with a personalized or non-personalized card.
DELEGATE: A cardholder who may be assigned to non-personalized cards only and acts as an authorized user of the card.
Unique Identifier for cardholder.
Email address of the cardholder.
Details about the cardholder. Only relevant for individual cardholder type.
Address of the cardholder.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
The individual's date of birth, in the format YYYY-MM-DD.
Information of the individual's employers.
Local business registration number i.e. an official signal of identification for the business.
Country code. (2-letter ISO 3166-2 country code)
Local business registration number i.e. an official signal of identification for the business.
Type of business registration number, depending on what's applicable to the country the business is registered in.
BRN, EIN, SSN, VAT
Name of the employer.
The full name of the Individual. Only characters in English are supported.
First name of cardholder.
Last name for cardholder.
Optional middle name of cardholder.
Optional title of cardholder.
The tax identification number for the individual cardholder. Used for customs or regulatory reporting when required by the shipping destination. Format and requirements may differ by country.
The mobile number of the cardholder.
Postal address for the cardholder.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
The status of the cardholder. One of PENDING, READY, DISABLED or INCOMPLETE, which are defined as follows:
PENDING: Cardholder is currently in review.
READY: Cardholder is ready to be issued cards.
INCOMPLETE: Cardholder record has incomplete information or more data is required to move them to READY.
DELETED: Cardholder record has been deleted.
The type of cardholder. One of INDIVIDUAL or DELEGATE, which are defined as follows:
INDIVIDUAL: A cardholder who is associated with a named individual that is a representative of your business. Can be associated with a personalized or non-personalized card.
DELEGATE: A cardholder who may be assigned to non-personalized cards only and acts as an authorized user of the card.
| Error status | Description |
|---|---|
| 400 | Possible errors: |
| 401 | Possible errors: |
| 429 | Too many requests |
| 500 | Service unavailable |
$curl --request POST \> --url 'https://api-demo.airwallex.com/api/v1/issuing/cardholders/create' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "email": "[email protected]",> "individual": {> "address": {> "city": "Melbourne",> "country": "AU",> "line1": "44 Gillespie St",> "line2": "Unit 2",> "postcode": "3121",> "state": "VIC"> },> "cardholder_agreement_terms_consent_obtained": "yes",> "date_of_birth": "1982-11-02",> "employers": [> {> "business_identifiers": [> {> "country_code": "US",> "number": "A1098762872",> "type": "BRN"> }> ]> }> ],> "express_consent_obtained": "yes",> "identification": {> "country": "AU",> "document_back_file_id": "NzI3ZDAxM2ItZjMzMC00ZDIyLTk4YTQtMTE3ZTA0MjdhZTUyLHwsaG9uZ2tvbmcsfCxwYXNzcG9ydC5qcGdfMTYwNzY0MDI4OQ==",> "document_front_file_id": "NzI3ZDAxM2ItZjMzMC00ZDIyLTk4YTQtMTE3ZTA0MjdhZTUyLHwsaG9uZ2tvbmcsfCxwYXNzcG9ydC5qcGdfMTYwNzY0MDI4OQ==",> "expiry_date": "2028-08-28",> "gender": "F",> "number": "001238243",> "state": "NT",> "type": "DRIVERS_LICENSE"> },> "name": {> "first_name": "John",> "last_name": "Smith",> "middle_name": "Fitzgerald",> "title": "Mr"> },> "nationality": "UK",> "paperless_notification_consent_obtained": "yes",> "privacy_policy_terms_consent_obtained": "yes",> "tax_identification_number": "<string>"> },> "mobile_number": "61432100100",> "postal_address": {> "city": "Melbourne",> "country": "AU",> "line1": "44 Gillespie St",> "line2": "Unit 2",> "postcode": "3121",> "state": "VIC"> },> "type": "INDIVIDUAL">}'
1{2 "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",3 "email": "[email protected]",4 "individual": {5 "address": {6 "city": "Melbourne",7 "country": "AU",8 "line1": "44 Gillespie St",9 "line2": "Unit 2",10 "postcode": "3121",11 "state": "VIC"12 },13 "date_of_birth": "1982-11-02",14 "employers": [15 {16 "business_identifiers": [17 {18 "country_code": "US",19 "number": "A1098762872",20 "type": "BRN"21 }22 ]23 }24 ],25 "name": {26 "first_name": "John",27 "last_name": "Smith",28 "middle_name": "Fitzgerald",29 "title": "Mr"30 },31 "tax_identification_number": "<string>"32 },33 "mobile_number": "61-9922334321",34 "postal_address": {35 "city": "Melbourne",36 "country": "AU",37 "line1": "44 Gillespie St",38 "line2": "Unit 2",39 "postcode": "3121",40 "state": "VIC"41 },42 "status": "PENDING",43 "type": "INDIVIDUAL"44}
Get all cardholders
GET /api/v1/issuing/cardholders
Get all cardholders created within an account
Cardholder status - one of PENDING, READY, INCOMPLETE or DISABLED.
Email address of the cardholder to filter by
Page number, starts from 0.
Number of results per page, between 10 and 200. The default is 100.
Unique Identifier for cardholder.
Email address of the cardholder.
Details about the cardholder. Only relevant for individual cardholder type.
Address of the cardholder.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
The individual's date of birth, in the format YYYY-MM-DD.
Information of the individual's employers.
Local business registration number i.e. an official signal of identification for the business.
Country code. (2-letter ISO 3166-2 country code)
Local business registration number i.e. an official signal of identification for the business.
Type of business registration number, depending on what's applicable to the country the business is registered in.
BRN, EIN, SSN, VAT
Name of the employer.
The full name of the Individual. Only characters in English are supported.
First name of cardholder.
Last name for cardholder.
Optional middle name of cardholder.
Optional title of cardholder.
The tax identification number for the individual cardholder. Used for customs or regulatory reporting when required by the shipping destination. Format and requirements may differ by country.
The mobile number of the cardholder.
Postal address for the cardholder.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
The status of the cardholder. One of PENDING, READY, DISABLED or INCOMPLETE, which are defined as follows:
PENDING: Cardholder is currently in review.
READY: Cardholder is ready to be issued cards.
INCOMPLETE: Cardholder record has incomplete information or more data is required to move them to READY.
DELETED: Cardholder record has been deleted.
The type of cardholder. One of INDIVIDUAL or DELEGATE, which are defined as follows:
INDIVIDUAL: A cardholder who is associated with a named individual that is a representative of your business. Can be associated with a personalized or non-personalized card.
DELEGATE: A cardholder who may be assigned to non-personalized cards only and acts as an authorized user of the card.
| Error status | Description |
|---|---|
| 400 | Possible errors: |
| 401 | Possible errors: |
| 429 | Too many requests |
| 500 | Service unavailable |
$curl --request GET \> --url 'https://api-demo.airwallex.com/api/v1/issuing/cardholders' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "has_more": false,3 "items": [4 {5 "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",6 "email": "[email protected]",7 "individual": {8 "address": {9 "city": "Melbourne",10 "country": "AU",11 "line1": "44 Gillespie St",12 "line2": "Unit 2",13 "postcode": "3121",14 "state": "VIC"15 },16 "date_of_birth": "1982-11-02",17 "employers": [18 {19 "business_identifiers": [20 {21 "country_code": "US",22 "number": "A1098762872",23 "type": "BRN"24 }25 ]26 }27 ],28 "name": {29 "first_name": "John",30 "last_name": "Smith",31 "middle_name": "Fitzgerald",32 "title": "Mr"33 }34 },35 "mobile_number": "61-9922334321",36 "postal_address": {37 "city": "Melbourne",38 "country": "AU",39 "line1": "44 Gillespie St",40 "line2": "Unit 2",41 "postcode": "3121",42 "state": "VIC"43 },44 "status": "PENDING",45 "type": "INDIVIDUAL"46 }47 ]48}
Get cardholder details
GET /api/v1/issuing/cardholders/{id}
Retrieve details for a cardholder
Unique Identifier for cardholder
Unique Identifier for cardholder.
Email address of the cardholder.
Details about the cardholder. Only relevant for individual cardholder type.
Address of the cardholder.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
The individual's date of birth, in the format YYYY-MM-DD.
Information of the individual's employers.
Local business registration number i.e. an official signal of identification for the business.
Country code. (2-letter ISO 3166-2 country code)
Local business registration number i.e. an official signal of identification for the business.
Type of business registration number, depending on what's applicable to the country the business is registered in.
BRN, EIN, SSN, VAT
Name of the employer.
The full name of the Individual. Only characters in English are supported.
First name of cardholder.
Last name for cardholder.
Optional middle name of cardholder.
Optional title of cardholder.
The tax identification number for the individual cardholder. Used for customs or regulatory reporting when required by the shipping destination. Format and requirements may differ by country.
The mobile number of the cardholder.
Postal address for the cardholder.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
The status of the cardholder. One of PENDING, READY, DISABLED or INCOMPLETE, which are defined as follows:
PENDING: Cardholder is currently in review.
READY: Cardholder is ready to be issued cards.
INCOMPLETE: Cardholder record has incomplete information or more data is required to move them to READY.
DELETED: Cardholder record has been deleted.
The type of cardholder. One of INDIVIDUAL or DELEGATE, which are defined as follows:
INDIVIDUAL: A cardholder who is associated with a named individual that is a representative of your business. Can be associated with a personalized or non-personalized card.
DELEGATE: A cardholder who may be assigned to non-personalized cards only and acts as an authorized user of the card.
| Error status | Description |
|---|---|
| 400 | Possible errors: |
| 401 | Possible errors: |
| 429 | Too many requests |
| 500 | Service unavailable |
$curl --request GET \> --url 'https://api-demo.airwallex.com/api/v1/issuing/cardholders/cardholder_id' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",3 "email": "[email protected]",4 "individual": {5 "address": {6 "city": "Melbourne",7 "country": "AU",8 "line1": "44 Gillespie St",9 "line2": "Unit 2",10 "postcode": "3121",11 "state": "VIC"12 },13 "date_of_birth": "1982-11-02",14 "employers": [15 {16 "business_identifiers": [17 {18 "country_code": "US",19 "number": "A1098762872",20 "type": "BRN"21 }22 ]23 }24 ],25 "name": {26 "first_name": "John",27 "last_name": "Smith",28 "middle_name": "Fitzgerald",29 "title": "Mr"30 },31 "tax_identification_number": "<string>"32 },33 "mobile_number": "61-9922334321",34 "postal_address": {35 "city": "Melbourne",36 "country": "AU",37 "line1": "44 Gillespie St",38 "line2": "Unit 2",39 "postcode": "3121",40 "state": "VIC"41 },42 "status": "PENDING",43 "type": "INDIVIDUAL"44}
Update a cardholder
POST /api/v1/issuing/cardholders/{id}/update
Update a cardholder with selected information. All fields are optional, and only those provided will be updated. If a composite object, e.g. name is provided, then all of its child fields must be provided and valid. Updating the cardholder may re-trigger the name screening process.
Unique Identifier for card
Details about the cardholder. Only relevant for individual cardholder type.
Street address of the cardholder.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
For Canada entities only - By setting this field to yes you confirm that you have the express consent of this.
The individual's date of birth, in the format YYYY-MM-DD.
Information of the individual's employers.
Local business registration number i.e. an official signal of identification for the business.
Country code. (2-letter ISO 3166-2 country code)
Local business registration number i.e. an official signal of identification for the business.
Type of business registration number, depending on what's applicable to the country the business is registered in.
BRN, EIN, SSN, VAT
Name of the employer.
By setting this field to yes you confirm that you have the express consent of this cardholder for Airwallex to perform name and sanction screening or any further identity verification if required.
Identification of the individual cardholder. This object is optional and is only required if name screening fails or if Airwallex deem necessary for your integration.
ISO country code of identification document.
The unique identifier for an image of the back of the given document. This can be retrieved by uploading a file to the file upload endpoint within the API.
The unique identifier for an image of the front of the given document. This can be retrieved by uploading a file to the file upload endpoint within the API.
Expiry date of the identification document provided, in the format YYYY-MM-DD.
Gender as specified on UK drivers license. Not required for other identification types.
M, F
Document number. May be a license number or passport number.
State the document was issued in. Required only if type is DRIVERS_LICENSE and country is AU.
Type of identification being provided. May be PASSPORT, DRIVERS_LICENSE, or ID_CARD.
The full name of the Individual. Only characters in English are supported.
First name of cardholder.
Last name for cardholder.
Optional middle name of cardholder.
Optional title of cardholder.
The 2-letter ISO country code for the individual's nationality.
For Canada entities only - By setting this field to yes you confirm that you consent to paperless notifications. You agree to the Electronic Communications Consent Agreement which states that we may provide you with all disclosures, notices and other communications, about Airwallex's services including this Agreement and any further amendments, in electronic form.
For Canada entities only - By setting this field to yes you confirm that you consent to the terms of the Privacy Policy.
The tax identification number for the individual cardholder. Used for customs or regulatory reporting when required by the shipping destination. Format and requirements may differ by country.
Mobile number of the cardholder.
Optional postal address of the cardholder. Only required if different to address and physical cards are to be issued.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
The type of cardholder. One of INDIVIDUAL or DELEGATE, which are defined as follows:
INDIVIDUAL: A cardholder who is associated with a named individual that is a representative of your business. Can be associated with a personalized or non-personalized card.
DELEGATE: A cardholder who may be assigned to non-personalized cards only and acts as an authorized user of the card.
Unique Identifier for cardholder.
Email address of the cardholder.
Details about the cardholder. Only relevant for individual cardholder type.
Address of the cardholder.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
The individual's date of birth, in the format YYYY-MM-DD.
Information of the individual's employers.
Local business registration number i.e. an official signal of identification for the business.
Country code. (2-letter ISO 3166-2 country code)
Local business registration number i.e. an official signal of identification for the business.
Type of business registration number, depending on what's applicable to the country the business is registered in.
BRN, EIN, SSN, VAT
Name of the employer.
The full name of the Individual. Only characters in English are supported.
First name of cardholder.
Last name for cardholder.
Optional middle name of cardholder.
Optional title of cardholder.
The tax identification number for the individual cardholder. Used for customs or regulatory reporting when required by the shipping destination. Format and requirements may differ by country.
The mobile number of the cardholder.
Postal address for the cardholder.
City of address
ISO country code of address
Address line 1
Address line 2
Address postcode or ZIP code
Address state or region
The status of the cardholder. One of PENDING, READY, DISABLED or INCOMPLETE, which are defined as follows:
PENDING: Cardholder is currently in review.
READY: Cardholder is ready to be issued cards.
INCOMPLETE: Cardholder record has incomplete information or more data is required to move them to READY.
DELETED: Cardholder record has been deleted.
The type of cardholder. One of INDIVIDUAL or DELEGATE, which are defined as follows:
INDIVIDUAL: A cardholder who is associated with a named individual that is a representative of your business. Can be associated with a personalized or non-personalized card.
DELEGATE: A cardholder who may be assigned to non-personalized cards only and acts as an authorized user of the card.
| Error status | Description |
|---|---|
| 400 | Possible errors: |
| 401 | Possible errors: |
| 429 | Too many requests |
| 500 | Service unavailable |
$curl --request POST \> --url 'https://api-demo.airwallex.com/api/v1/issuing/cardholders/cardholder_id/update' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "individual": {> "address": {> "city": "Melbourne",> "country": "AU",> "line1": "44 Gillespie St",> "line2": "Unit 2",> "postcode": "3121",> "state": "VIC"> },> "cardholder_agreement_terms_consent_obtained": "yes",> "date_of_birth": "1982-11-02",> "employers": [> {> "business_identifiers": [> {> "country_code": "US",> "number": "A1098762872",> "type": "BRN"> }> ]> }> ],> "express_consent_obtained": "yes",> "identification": {> "country": "AU",> "document_back_file_id": "NzI3ZDAxM2ItZjMzMC00ZDIyLTk4YTQtMTE3ZTA0MjdhZTUyLHwsaG9uZ2tvbmcsfCxwYXNzcG9ydC5qcGdfMTYwNzY0MDI4OQ==",> "document_front_file_id": "NzI3ZDAxM2ItZjMzMC00ZDIyLTk4YTQtMTE3ZTA0MjdhZTUyLHwsaG9uZ2tvbmcsfCxwYXNzcG9ydC5qcGdfMTYwNzY0MDI4OQ==",> "expiry_date": "2028-08-28",> "gender": "F",> "number": "001238243",> "state": "NT",> "type": "DRIVERS_LICENSE"> },> "name": {> "first_name": "John",> "last_name": "Smith",> "middle_name": "Fitzgerald",> "title": "Mr"> },> "nationality": "UK",> "paperless_notification_consent_obtained": "yes",> "privacy_policy_terms_consent_obtained": "yes",> "tax_identification_number": "<string>"> },> "mobile_number": "61432100100",> "postal_address": {> "city": "Melbourne",> "country": "AU",> "line1": "44 Gillespie St",> "line2": "Unit 2",> "postcode": "3121",> "state": "VIC"> },> "type": "INDIVIDUAL">}'
1{2 "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",3 "email": "[email protected]",4 "individual": {5 "address": {6 "city": "Melbourne",7 "country": "AU",8 "line1": "44 Gillespie St",9 "line2": "Unit 2",10 "postcode": "3121",11 "state": "VIC"12 },13 "date_of_birth": "1982-11-02",14 "employers": [15 {16 "business_identifiers": [17 {18 "country_code": "US",19 "number": "A1098762872",20 "type": "BRN"21 }22 ]23 }24 ],25 "name": {26 "first_name": "John",27 "last_name": "Smith",28 "middle_name": "Fitzgerald",29 "title": "Mr"30 },31 "tax_identification_number": "<string>"32 },33 "mobile_number": "61-9922334321",34 "postal_address": {35 "city": "Melbourne",36 "country": "AU",37 "line1": "44 Gillespie St",38 "line2": "Unit 2",39 "postcode": "3121",40 "state": "VIC"41 },42 "status": "PENDING",43 "type": "INDIVIDUAL"44}
Delete cardholder
POST /api/v1/issuing/cardholders/{id}/delete
Deletes the cardholder with the corresponding unique identifier. Deleting the cardholder will also cause all employee cards that are linked to the cardholder to also be closed.
Unique Identifier for cardholder
Unique Identifier for cardholder.
Will be set to true if the cardholder was deleted successfully.
| Error status | Description |
|---|---|
| 400 | Possible errors: |
| 401 | Possible errors: |
| 429 | Too many requests |
| 500 | Service unavailable |
$curl --request POST \> --url 'https://api-demo.airwallex.com/api/v1/issuing/cardholders/cardholder_id/delete' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",3 "deleted": true4}