POST////
Use this endpoint to create a Visa Alias.
Header parameter
| Fields | Description |
|---|---|
| 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 |
| participant-id string Required | Visa Business Identifier (BID) that is assigned to the program. Allowable Values: Existing participant ID |
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 |
| userToken string Required | Unique identifier of the user. Allowable Values: 1–128 chars |
| 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 |
| consent object Required | Visa Alias Directory Service (ADS) consent information. Allowable Values: presenter, validFromDateTime, version, expiryDateTime, intermediaries |
| consent.presenter string Required | Presenter of the Visa Alias Directory Service (ADS) consent. Allowable Values: 1–120 chars |
| consent.validFromDateTime datetime Required | Date and time when the validity of the Visa ADS consent begins. Allowable Values: 20 chars Format: YYYY-MM-DDThh:mm:ssZ |
| consent.version string Required | Version of the Visa ADS consent. Allowable Values: 1–9 chars |
| consent.expiryDateTime datetime Optional | Date and time when the validity of the Visa ADS consent ends. This field is returned if it exists in the resource. Allowable Values: 20 chars Format: YYYY-MM-DDThh:mm:ssZ |
| consent.intermediaries array of strings Optional | Intermediaries of the Visa ADS consent. Allowable Values: 1–120 chars |
| paymentCredentials array of objects Required | List of payment credentials associated with the Visa Alias. This array is returned if the Visa Alias exists and one or more payment credentials are linked to it. Allowable Values: cardToken, billingAddress, nameOnCard, cardType, issuerName, currencyCode, preferredFor |
| paymentCredentials[].cardToken string Required | Unique identifier of the card token. Allowable Values: 1–36 chars Existing card token |
| paymentCredentials[].billingAddress object Required | Billing address for the payment credential. Allowable Values: country, addressLine1, addressLine2, buildingNumber, city, minorSubdivision, postalCode, state, streetName |
| paymentCredentials[].billingAddress.country string Required | 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 Optional | Address line 1 of the billing address associated with the payment credential. Allowable Values: 99 char max |
| paymentCredentials[].billingAddress.addressLine2 string Optional | Address line 2 of the billing address associated with the payment credential. Allowable Values: 99 char max |
| paymentCredentials[].billingAddress.buildingNumber string Optional | Building number of the billing address associated with the payment credential. Allowable Values: 1–60 chars |
| paymentCredentials[].billingAddress.city string Optional | City of the billing address associated with the payment credential. Allowable Values: 1–35 chars |
| paymentCredentials[].billingAddress.minorSubdivision string Optional | Minor subdivision of the billing address associated with the payment credential. Allowable Values: 1–50 chars |
| paymentCredentials[].billingAddress.postalCode string Optional | Postal code of the billing address associated with the payment credential. Allowable Values: 1–16 chars |
| paymentCredentials[].billingAddress.state string Optional | State of the billing address associated with the payment credential. Allowable Values: 1–16 chars |
| paymentCredentials[].billingAddress.streetName string Optional | Street name of the billing address associated with the payment credential. Allowable Values: 1–60 chars |
| paymentCredentials[].nameOnCard string Required | Name on the card for the payment credential. Allowable Values: 1–120 chars |
| paymentCredentials[].cardType string Required | Type of card for the payment credential. Allowable Values: 1–70 chars |
| paymentCredentials[].issuerName string Required | Card issuer’s name for the payment credential. Allowable Values: 1–150 chars |
| paymentCredentials[].currencyCode string Optional | Three-digit ISO 4217 currency code for the payment credential. Allowable Values: 3 chars Valid three-digit ISO 4217 currency code (Alpha-3) |
| paymentCredentials[].preferredFor array of strings Optional | Indicates if a payment credential is a preferred Receiving, Sending, or Paying account. Allowable Values: RECEIVE, SEND, PAYING |
| profile object Required | Alias Directory Service (ADS) profile information. Allowable Values: - firstName- lastName- contactInfo- dateOfBirth- firstNameLocal- lastNameLocal- middleName- middleNameLocal- preferredName |
| profile.firstName string Required | First name in the Alias Directory Service (ADS) profile. Allowable Values: 1–35 chars |
| profile.lastName string Required | 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 Optional | 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 Required | Type of contact information in the Alias Directory Service (ADS) profile. Allowable Values: EMAIL, PHONE, DIRECTORY_ALIASID |
| profile.contactInfo[].value string Required | Contact information value, which is the email address or phone number. Allowable Values: 1–320 chars |
| profile.dateOfBirth string Optional | 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 Optional | 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 Optional | 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 Optional | 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 Optional | 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 Optional | 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 |
| identification object Optional | Identification of the user associated with the Visa Alias. Allowable Values: type, value, verificationDetails |
| identification.type string Required | 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 Required | 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 Optional | 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 Optional | 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 Optional | Authentication method used when the user provided the credentials for verification. Allowable Values: 256 char |
| identification.verificationDetails.creationDateTime datetime Optional | 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 Optional | 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 Optional | 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 |
Sample request body
JSON
{
"aliasType": "PHONE",
"userToken": "21267931-7975-4b61-be7a-86915883b2b4",
"aliasValue": "1231231234",
"consent": {
"presenter": "Bank A",
"validFromDateTime": "2024-12-01T10:00:00Z",
"intermediaries": [
"Client A"
],
"version": "1.0",
"expiryDateTime": "2027-06-20T10:00:00Z"
},
"paymentCredentials": [
{
"cardToken": "4111111145551142",
"billingAddress": {
"country": "USA",
"streetName": "12",
"city": "San Francisco",
"postalCode": "94105",
"addressLine1": "1000 Market Street",
"buildingNumber": "56",
"addressLine2": "Suite 101",
"state": "CA",
"minorSubdivisionCode": "CA"
},
"nameOnCard": "John Doe",
"cardType": "Visa Platinum",
"issuerName": "Bank A",
"currencyCode": "USD"
}
],
"profile": {
"firstName": "Alex",
"middleName": "Robert",
"lastName": "Miller",
"firstNameLocal": "Roberto",
"middleNameLocal": "Alexander",
"lastNameLocal": "Miller",
"preferredName": "Miller's Shop",
"dateOfBirth": "1980-02-01",
"contactInfo": [
{
"type": "PHONE",
"value": "1231234321"
}
]
},
"identification": {
"type": "PASSPORT",
"value": "A123456",
"verificationDetails": {
"verifiedPhone": false,
"authMethodReference": "EXTERNAL, SMS OTP, Email OTP",
"authDateTime": "2026-01-01T22:52:46.000Z",
"verifiedEmail": true,
"creationDateTime": "2026-01-01T22:52:46.000Z"
}
}
}
Response body
| Fields | Description |
|---|---|
| id string Returned | UUID generated by Alias Directory, which identifies the Visa Alias. Allowable Values: 36 char max |
| externalId string Conditionally returned | External ID of the Visa Alias. Allowable Values: 1–100 chars |
| paymentCredentials array of objects Conditionally returned | List of payment credentials associated with the Visa Alias. This array is returned if the Visa Alias exists and one or more payment credentials are linked to it. Allowable Values: A valid array of payment credentials |
| paymentCredentials[].id string Returned | Unique identifier of the additional Visa Alias generated by the Alias Directory. Allowable Values: 36 char max |
| paymentCredentials[].type string Returned | The type of payment credential Allowable Values: CARD, BANK |
| paymentCredentials[].externalId string Conditionally returned | External ID of the Visa Alias. Allowable Values: 1–100 chars |
Sample response body
JSON
{
"id": "1f4f5e10-bde6-46a7-b2aa-576550054981",
"externalId": "21267931-7975-4b61-a-8691588sdfsdfa",
"paymentCredentials": [
{
"type": "CARD",
"id": "19e538ea-edfb-4780-915e-2f6e02959e03",
"externalId": "1111111111111111"
}
]
}