POST/////
Retrieve information about a Visa Alias and all the associated payment credentials.
Header parameter
| Fields | Description |
|---|---|
| participant-id string Required | Visa Business Identifier (BID) that is assigned to the program. Allowable Values: Existing participant ID |
| req-sys-id string Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta. Allowable Values: 36 char max |
Request body
| Fields | Description |
|---|---|
| aliasType string Required | Type of Visa Alias in the Alias Directory Service (ADS) profile. Visa supports phone and email as Visa Alias types that can be used in place of sensitive payment credentials details. Allowable Values: EMAIL, PHONE, DIRECTORY_ALIASID, PAYNAME |
| aliasValue string Required | Visa Alias value, which can be an email, a phone number, ID of an alias directory, or a payname. If a phone number is used for the Visa Alias, it must follow ITU-T E.164 (2010) number structure. NOTE: In the E.164 format, the ”+” sign is not included. Allowable Values: 1–128 chars |
| filters array of objects Optional | List of filters to apply in the request for Visa Alias resolution. Allowable Values: field, value |
| filters[].field string Optional | Fields used to filter the Visa Aliases. Allowable Values: DIRECTORY_NAME, EXCLUDED_DIRECTORY_NAME, ENTITY_ID |
| filters[].value array of strings Optional | Values used to filter the Visa Aliases. Visa Alias values are either an email address or phone number. Allowable Values: 1–128 chars |
| transactionDetails object Optional | Details of the transaction associated with the Alias. Allowable Values: currencyCode |
| transactionDetails.currencyCode string Optional | The currency code for the transaction in ISO 4217 (Alpha-3) format. Allowable Values: 3 chars |
| userDetails object Optional | Details of the user requesting the Visa Alias information. The information must not contain personal identifiable information (PII). Allowable Values: userName |
| userDetails.userName string Optional | Unique identifier of the user. Allowable Values: 1–50 chars |
Sample request body
JSON
{
"aliasType": "PHONE",
"aliasValue": "1231231234",
"transactionDetails": {
"currencyCode": "USD"
},
"filters": [
{
"field": "DIRECTORY_NAME",
"value": [
"DIRECTORY_A",
"DIRECTORY_B",
"DIRECTORY_C"
]
}
],
"userDetails": {
"userName": "username1234"
}
}
Response body
| Fields | Description |
|---|---|
| profile object Returned | Alias Directory Service (ADS) profile information. Allowable Values: - firstName- lastName- contactInfo- dateOfBirth- firstNameLocal- lastNameLocal- middleName- middleNameLocal- preferredName |
| profile.firstName string Returned | First name in the Alias Directory Service (ADS) profile. Allowable Values: 1–35 chars |
| profile.lastName string Returned | Last name in the Alias Directory Service (ADS) profile. Participants in the CEMEA and EU regions must only use the initial of the consumer’s last name followed by a period to create or modify a Visa Alias record. Allowable Values: 1–35 chars |
| profile.contactInfo array of objects Conditionally returned | Contact information in the Alias Directory Service (ADS) profile. This array is returned if the Visa Alias’ contact information details exist. Allowable Values: A valid array of contact information details |
| profile.contactInfo[].type string Returned | Type of contact information in the Alias Directory Service (ADS) profile. Allowable Values: EMAIL, PHONE, DIRECTORY_ALIASID |
| profile.contactInfo[].value string Returned | Contact information value, which is the email address or phone number. Allowable Values: 1–320 chars |
| profile.dateOfBirth string Conditionally returned | Date of birth in the Alias Directory Service (ADS) profile. This field is returned if it exists in the resource. Allowable Values: 10 chars |
| profile.firstNameLocal string Conditionally returned | First name in the Alias Directory Service (ADS) profile, expressed in the user’s local language. This field is returned if it exists in the resource. Allowable Values: 1–35 chars |
| profile.lastNameLocal string Conditionally returned | Last name in the Alias Directory Service (ADS) profile, expressed in the user’s local language. This field is returned if it exists in the resource. Allowable Values: 1–35 chars |
| profile.middleName string Conditionally returned | Middle name in the Alias Directory Service (ADS) profile. This field is returned if it exists in the resource. Allowable Values: 1–35 chars |
| profile.middleNameLocal string Conditionally returned | Middle name in the Alias Directory Service (ADS) profile, expressed in the user’s local language. This field is returned if it exists in the resource. Allowable Values: 1–35 chars |
| profile.preferredName string Conditionally returned | Preferred name in the Alias Directory Service (ADS) profile, as provided by the user. This field is returned if it exists in the resource. Allowable Values: 1–35 chars |
| directoryName string Conditionally returned | The directory name of the Visa Alias. Allowable Values: 1–128 chars |
| identification object Conditionally returned | Identification of the user associated with the Visa Alias. Allowable Values: type, value, verificationDetails |
| identification.type string Returned | Type of identification provided by the user associated with the Visa Alias. Allowable Values: DNI, CE, PASSPORT, PTP, FFPP, FFAA, CCD, COI, PN, CIE, CPF, DL, DPI, NIDN |
| identification.value string Returned | Value of the identification provided by the user associated with the Visa Alias, which is used to validate the user. Passport number, for example. Allowable Values: 1–35 chars |
| identification.verificationDetails object Conditionally returned | Verification details associated with the Visa Alias. This field is returned if it exists in the resource. Allowable Values: authDateTime, authMethodReference, creationDateTime, verifiedEmail, verifiedPhone |
| identification.verificationDetails.authDateTime datetime Conditionally returned | Time when the user provided the credentials for verification in ISO UTC format. Allowable Values: format: YYYY-MM-DDThh:mm:ss.000Z |
| identification.verificationDetails.authMethodReference string Conditionally returned | Authentication method used when the user provided the credentials for verification. Allowable Values: 256 char |
| identification.verificationDetails.creationDateTime datetime Conditionally returned | Time when the user was created or enrolled in ISO UTC format. Allowable Values: format: YYYY-MM-DDThh:mm:ss.000Z |
| identification.verificationDetails.verifiedEmail boolean Conditionally returned | Returns true if an email was verified during the verification process. This email does not need to match the Alias or contact info if an email was used.Allowable Values: true, false |
| identification.verificationDetails.verifiedPhone boolean Conditionally returned | Returns true if a phone number was verified during the verification process. This phone number does not need to match the Alias or contact info if a phone number was used.Allowable Values: true, false |
| paymentCredentials array of objects Conditionally returned | List of payment credentials associated with the Visa Alias. Allowable Values: accountNumber, billingAddress, type, accountNumberType, cardType, createdOn, currencyCode, expirationDate, externalId, id, issuerName, lastFourDigits, lastUpdatedOn, nameOnCard, preferredFor, status |
| paymentCredentials[].accountNumber string Returned | Account number of the payment credential. Allowable Values: 12–19 chars |
| paymentCredentials[].billingAddress object Returned | Billing address for the payment credential. Allowable Values: country, addressLine1, addressLine2, buildingNumber, city, minorSubdivision, postalCode, state, streetName |
| paymentCredentials[].billingAddress.country string Returned | Country of the billing address associated with the payment credential, expressed as an ISO 3166 code. For example, the numeric code for the United States is 840 and the alpha-3 code is USA.The ISO maintains the full list of ISO 3166 country codes. Allowable Values: 3 chars |
| paymentCredentials[].billingAddress.addressLine1 string Conditionally returned | Address line 1 of the billing address associated with the payment credential. Allowable Values: 99 char max |
| paymentCredentials[].billingAddress.addressLine2 string Conditionally returned | Address line 2 of the billing address associated with the payment credential. Allowable Values: 99 char max |
| paymentCredentials[].billingAddress.buildingNumber string Conditionally returned | Building number of the billing address associated with the payment credential. Allowable Values: 1–60 chars |
| paymentCredentials[].billingAddress.city string Conditionally returned | City of the billing address associated with the payment credential. Allowable Values: 1–35 chars |
| paymentCredentials[].billingAddress.minorSubdivision string Conditionally returned | Minor subdivision of the billing address associated with the payment credential. Allowable Values: 1–50 chars |
| paymentCredentials[].billingAddress.postalCode string Conditionally returned | Postal code of the billing address associated with the payment credential. Allowable Values: 1–16 chars |
| paymentCredentials[].billingAddress.state string Conditionally returned | State of the billing address associated with the payment credential. Allowable Values: 1–16 chars |
| paymentCredentials[].billingAddress.streetName string Conditionally returned | Street name of the billing address associated with the payment credential. Allowable Values: 1–60 chars |
| paymentCredentials[].type string Returned | Type of payment credential associated with the Visa Alias. Allowable Values: CARD |
| paymentCredentials[].accountNumberType string Conditionally returned | Type of account number associated with the payment credential. Allowable Values: PAN, NIUBIZ, TOKEN |
| paymentCredentials[].cardType string Conditionally returned | Type of card associated with the payment credential. Allowable Values: 1–70 chars |
| paymentCredentials[].createdOn datetime Conditionally returned | Date and time when the payment credential was created. Allowable Values: 24 chars Format: YYYY-MM-DDTHH:MM:SS.000Z |
| paymentCredentials[].currencyCode string Conditionally returned | Three-digit ISO 4217 currency code for the payment credential. Allowable Values: 3 chars Valid three-digit ISO 4217 currency code (Alpha-3) |
| paymentCredentials[].expirationDate string Conditionally returned | Expiration date of the card. Allowable Values: 7 chars Format: YYYY-MM |
| paymentCredentials[].externalId string Conditionally returned | External ID of the payment credential, which corresponds to Marqeta’s card token. Allowable Values: 1–100 chars |
| paymentCredentials[].id string Conditionally returned | Unique identifier of the payment credential generated by Alias Directory. Allowable Values: 1–36 chars |
| paymentCredentials[].issuerName string Conditionally returned | Name of the issuer of the payment credential. Allowable Values: 1–150 chars |
| paymentCredentials[].lastFourDigits string Conditionally returned | Last four digits of the card number. Allowable Values: 4 chars |
| paymentCredentials[].lastUpdatedOn datetime Conditionally returned | Date and time when the payment credential was last updated. Allowable Values: 24 chars Format: YYYY-MM-DDTHH:MM:SS.000Z |
| paymentCredentials[].nameOnCard string Conditionally returned | Name on the card associated with the payment credential. Allowable Values: 1–120 chars |
| paymentCredentials[].preferredFor array of objects Conditionally returned | Indicates if a payment credential is a preferred Receiving, Sending, or Paying account. This array is returned if you passed the preferredFor field when creating a Visa Alias or when adding a new payment credential to an existing Visa Alias.Allowable Values: A valid array of preferredFor objects |
| paymentCredentials[].preferredFor[].type string Returned | Type of operation associated with the payment credential. Allowable Values: RECEIVE, SEND, PAY |
| paymentCredentials[].preferredFor[].date string Conditionally returned | Date of the Receiving, Sending, or Paying operation. Allowable Values: 10 chars Format: YYYY-MM-DD |
| paymentCredentials[].status string Conditionally returned | Status of the payment credential associated with the Visa Alias. Allowable Values: ACTIVE, BLOCKED, DISABLED, EXPIRED |
Sample response body
JSON
[
{
"directoryName": "DIRECTORY_A",
"paymentCredentials": [
{
"type": "CARD",
"cardType": "Visa Platinum",
"issuerName": "Bank A",
"nameOnCard": "Alex Miller",
"currencyCode": "USD",
"accountNumber": "4111111145551142",
"billingAddress": {
"city": "San Francisco",
"state": "CA",
"country": "USA",
"postalCode": "94105",
"streetName": "12",
"addressLine1": "1000 Market Street",
"addressLine2": "Suite 101",
"buildingNumber": "56",
"minorSubdivisionCode": "CA"
},
"expirationDate": "2026-01",
"lastFourDigits": "1142",
"accountNumberType": "TOKEN",
"modifiedOn": "2026-01-01T22:52:46.000Z",
"preferredFor": [
{
"date": "2026-01-01",
"type": "RECEIVE"
}
]
}
],
"profile": {
"lastName": "Miller",
"firstName": "Alex",
"middleName": "Robert",
"contactInfo": [
{
"type": "PHONE",
"value": "1231234321"
}
],
"dateOfBirth": "1980-02-01",
"lastNameLocal": "Miller",
"preferredName": "Miller's Shop",
"firstNameLocal": "Alexander",
"middleNameLocal": "Roberto"
},
"identification": {
"type": "PASSPORT",
"value": "A123456",
"verificationDetails": {
"authDateTime": "2026-01-01T22:52:46Z",
"verifiedEmail": true,
"verifiedPhone": false,
"creationDateTime": "2026-01-01T22:52:46Z",
"authMethodReference": "EXTERNAL, SMS OTP, Email OTP"
}
}
}
]