Cardholders
You can create cardholders, which are authorized representatives of your business that can be issued cards.
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 any authorized representative of your business with the ability to own cards. Creation of cardholders involves passing a name screening process which requires some basic details about the cardholder.
Street address of the cardholder.
City of address
ISO country code of address
Address line 1
Address postcode or ZIP code
Address line 2
Address state or region
Email address of the cardholder.
Details about the individual cardholder.
The individual's date of birth, in the format YYYY-MM-DD.
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.
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.
For Canada entities only - By setting this field to yes you confirm that you have the express consent of this.
The form of identification used to verify the individual's identity. This object is optional and is only required if name screening fails.
ISO country code of identification document.
Expiry date of the identification document provided, in the format YYYY-MM-DD.
Document number. May be a license number or passport number.
Type of identification being provided. May be PASSPORT, DRIVERS_LICENSE, or ID_CARD.
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.
Gender as specified on UK drivers license. Not required for other identification types.
M, F
State the document was issued in. Required only if type is DRIVERS_LICENSE and country is AU.
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.
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 postcode or ZIP code
Address line 2
Address state or region
Address of the cardholder.
City of address
ISO country code of address
Address line 1
Address postcode or ZIP code
Address line 2
Address state or region
Unique Identifier for cardholder.
Email address of the cardholder.
Details about the cardholder.
The individual's date of birth, in the format YYYY-MM-DD.
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 postcode or ZIP code
Address line 2
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.
INCOMPLETE, PENDING, READY, DISABLED, DELETED
| 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 '{> "address": {> "city": "Melbourne",> "country": "AU",> "line1": "44 Gillespie St",> "line2": "Unit 2",> "postcode": "3121",> "state": "VIC"> },> "email": "[email protected]",> "individual": {> "cardholder_agreement_terms_consent_obtained": "yes",> "date_of_birth": "1982-11-02",> "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"> },> "mobile_number": "61432100100",> "postal_address": {> "city": "Melbourne",> "country": "AU",> "line1": "44 Gillespie St",> "line2": "Unit 2",> "postcode": "3121",> "state": "VIC"> }>}'
1{2 "address": {3 "city": "Melbourne",4 "country": "AU",5 "line1": "44 Gillespie St",6 "line2": "Unit 2",7 "postcode": "3121",8 "state": "VIC"9 },10 "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",11 "email": "[email protected]",12 "individual": {13 "date_of_birth": "1982-11-02",14 "name": {15 "first_name": "John",16 "last_name": "Smith",17 "middle_name": "Fitzgerald",18 "title": "Mr"19 },20 "tax_identification_number": "<string>"21 },22 "mobile_number": "61-9922334321",23 "postal_address": {24 "city": "Melbourne",25 "country": "AU",26 "line1": "44 Gillespie St",27 "line2": "Unit 2",28 "postcode": "3121",29 "state": "VIC"30 },31 "status": "PENDING"32}
Get all cardholders
GET /api/v1/issuing/cardholders
Get all cardholders created within an account
Cardholder status to filter by - one of PENDING, READY, DISABLED
PENDING, READY, DISABLED, INCOMPLETE
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.
Address of the cardholder.
City of address
ISO country code of address
Address line 1
Address postcode or ZIP code
Address line 2
Address state or region
Unique Identifier for cardholder.
Email address of the cardholder.
Details about the cardholder.
The individual's date of birth, in the format YYYY-MM-DD.
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 postcode or ZIP code
Address line 2
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.
INCOMPLETE, PENDING, READY, DISABLED, DELETED
| 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 "address": {6 "city": "Melbourne",7 "country": "AU",8 "line1": "44 Gillespie St",9 "line2": "Unit 2",10 "postcode": "3121",11 "state": "VIC"12 },13 "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",14 "email": "[email protected]",15 "individual": {16 "date_of_birth": "1982-11-02",17 "name": {18 "first_name": "John",19 "last_name": "Smith",20 "middle_name": "Fitzgerald",21 "title": "Mr"22 }23 },24 "mobile_number": "61-9922334321",25 "postal_address": {26 "city": "Melbourne",27 "country": "AU",28 "line1": "44 Gillespie St",29 "line2": "Unit 2",30 "postcode": "3121",31 "state": "VIC"32 },33 "status": "PENDING"34 }35 ]36}
Get cardholder details
GET /api/v1/issuing/cardholders/{id}
Retrieve details for a cardholder
Unique Identifier for cardholder
Address of the cardholder.
City of address
ISO country code of address
Address line 1
Address postcode or ZIP code
Address line 2
Address state or region
Unique Identifier for cardholder.
Email address of the cardholder.
Details about the cardholder.
The individual's date of birth, in the format YYYY-MM-DD.
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 postcode or ZIP code
Address line 2
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.
INCOMPLETE, PENDING, READY, DISABLED, DELETED
| 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 "address": {3 "city": "Melbourne",4 "country": "AU",5 "line1": "44 Gillespie St",6 "line2": "Unit 2",7 "postcode": "3121",8 "state": "VIC"9 },10 "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",11 "email": "[email protected]",12 "individual": {13 "date_of_birth": "1982-11-02",14 "name": {15 "first_name": "John",16 "last_name": "Smith",17 "middle_name": "Fitzgerald",18 "title": "Mr"19 },20 "tax_identification_number": "<string>"21 },22 "mobile_number": "61-9922334321",23 "postal_address": {24 "city": "Melbourne",25 "country": "AU",26 "line1": "44 Gillespie St",27 "line2": "Unit 2",28 "postcode": "3121",29 "state": "VIC"30 },31 "status": "PENDING"32}
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
Street address of the cardholder.
City of address
ISO country code of address
Address line 1
Address postcode or ZIP code
Address line 2
Address state or region
Details about the individual cardholder.
The individual's date of birth, in the format YYYY-MM-DD.
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.
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.
For Canada entities only - By setting this field to yes you confirm that you have the express consent of this.
The form of identification used to verify the individual's identity. This object is optional and is only required if name screening fails.
ISO country code of identification document.
Expiry date of the identification document provided, in the format YYYY-MM-DD.
Document number. May be a license number or passport number.
Type of identification being provided. May be PASSPORT, DRIVERS_LICENSE, or ID_CARD.
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.
Gender as specified on UK drivers license. Not required for other identification types.
M, F
State the document was issued in. Required only if type is DRIVERS_LICENSE and country is AU.
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.
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 postcode or ZIP code
Address line 2
Address state or region
Address of the cardholder.
City of address
ISO country code of address
Address line 1
Address postcode or ZIP code
Address line 2
Address state or region
Unique Identifier for cardholder.
Email address of the cardholder.
Details about the cardholder.
The individual's date of birth, in the format YYYY-MM-DD.
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 postcode or ZIP code
Address line 2
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.
INCOMPLETE, PENDING, READY, DISABLED, DELETED
| 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 '{> "address": {> "city": "Melbourne",> "country": "AU",> "line1": "44 Gillespie St",> "line2": "Unit 2",> "postcode": "3121",> "state": "VIC"> },> "individual": {> "cardholder_agreement_terms_consent_obtained": "yes",> "date_of_birth": "1982-11-02",> "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"> },> "mobile_number": "61432100100",> "postal_address": {> "city": "Melbourne",> "country": "AU",> "line1": "44 Gillespie St",> "line2": "Unit 2",> "postcode": "3121",> "state": "VIC"> }>}'
1{2 "address": {3 "city": "Melbourne",4 "country": "AU",5 "line1": "44 Gillespie St",6 "line2": "Unit 2",7 "postcode": "3121",8 "state": "VIC"9 },10 "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",11 "email": "[email protected]",12 "individual": {13 "date_of_birth": "1982-11-02",14 "name": {15 "first_name": "John",16 "last_name": "Smith",17 "middle_name": "Fitzgerald",18 "title": "Mr"19 },20 "tax_identification_number": "<string>"21 },22 "mobile_number": "61-9922334321",23 "postal_address": {24 "city": "Melbourne",25 "country": "AU",26 "line1": "44 Gillespie St",27 "line2": "Unit 2",28 "postcode": "3121",29 "state": "VIC"30 },31 "status": "PENDING"32}
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}