Create digital wallet token provisioning request for Apple Wallet
Action:POSTEndpoint:
/digitalwalletprovisionrequests/applepay
Use this endpoint to return card data for use in provisioning a digital wallet token into Apple Wallet.
The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your PCI compliance overhead.
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 |
Request body
| Fields | Description |
|---|---|
| card_token string Required | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| certificates array of strings Required | Base64-encoded leaf and sub-CA certificates provided by Apple. The first element of the array should be the leaf certificate, followed by the sub-CA. Allowable Values: An array of one or more certificates provided by Apple |
| device_type string Required | Type of device into which the digital wallet token will be provisioned. Allowable Values: MOBILE_PHONE, WATCH, TABLET |
| nonce string Required | One-time-use nonce provided by Apple for security purposes. Allowable Values: Base64-encoded nonce from Apple |
| nonce_signature string Required | Apple-provided signature to the nonce. Allowable Values: Base64-encoded nonce signature from Apple |
| provisioning_app_version string Required | Version of the application making the provisioning request. Used for debugging and fraud prevention. Allowable Values: 1–50 chars |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| activation_data string Returned | Cryptographic one-time passcode conforming to the payment network operator or service provider specifications. Allowable Values: Any value |
| card_token string Returned | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| created_time datetime Returned | Date and time when the digital wallet provisioning request was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| encrypted_pass_data string Returned | Payload encrypted with a shared key derived from the Apple Public Certificates and the generated ephemeral private key. Allowable Values: Any value |
| ephemeral_public_key string Returned | Ephemeral public key used for the provisioning attempt. Allowable Values: Any value |
| last_modified_time datetime Returned | Date and time when the digital wallet token provisioning request was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
Submit a post-tokenization authentication decision
Action:POSTEndpoint:
/digitalwallets/postTokenizationAuthenticationDecision
Use this endpoint to submit a post-tokenization authentication decision from the customer to Marqeta in a secure card on file scenario. Marqeta validates the request, stores it, and forwards the authentication decision to Mastercard MDES in real time. Marqeta then returns the MDES response back to the customer synchronously. This enables issuers to notify Mastercard Digital Enablement Service (MDES) of the cardholder’s authentication outcome following tokenization, ensuring that the token requestor receives timely and accurate decisioning.
Request body
| Fields | Description |
|---|---|
| tokenUniqueReference string Required | Unique identifier of the token allocated to the card. Allowable Values: 1–64 chars |
| authRequestCorrelationId string Optional | Correlates multiple authentication requests. Allowable Values: 1–64 chars |
| authenticationMethod string Required | Authentication method used to verify the cardholder. Allowable Values: Issuer Application, Web Portal |
| decision string Required | Issuer decision after cardholder authentication. Allowable Values: SUCCESS, FAILED |
| commentText string Optional | Optional comment related to the decision. Allowable Values: 500 char max |
Response body
| Fields | Description |
|---|---|
| status string Returned | Indicates if the operation was successful. Allowable Values: SUCCESS, FAILED |
| message string Returned | Human-readable description of the outcome. Allowable Values: 255 char max |
Create digital wallet token provisioning request for Google Wallet
Action:POSTEndpoint:
/digitalwalletprovisionrequests/androidpay
Use this endpoint to return card data for use in provisioning a digital wallet token into Google Wallet.
The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your PCI compliance overhead.
Request body
| Fields | Description |
|---|---|
| card_token string Required | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| device_id string Required | Unique identifier of the user’s Google device, as provided by Google during the provisioning process. Allowable Values: 1–24 chars |
| device_type string Required | Type of device into which the digital wallet token will be provisioned. Allowable Values: MOBILE_PHONE, TABLET, WATCH |
| provisioning_app_version string Required | Version of the application making the provisioning request. Used for debugging and fraud prevention. Allowable Values: 1–50 chars |
| wallet_account_id string Required | User’s Google Wallet account ID, as provided by Google during the provisioning process. Allowable Values: 1–50 chars |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| card_token string Returned | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| created_time datetime Returned | Date and time when the digital wallet provisioning request was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| last_modified_time datetime Returned | Date and time when the digital wallet token provisioning request was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| push_tokenize_request_data object Returned | Contains details about a card tokenization push request. Allowable Values: card_type, display_name, opaque_payment_card, last_digits, network, token_service_provider |
| push_tokenize_request_data.display_name string Conditionally returned | Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). Visa 5678, for example.Allowable Values: Any value |
| push_tokenize_request_data.opaque_payment_card string Conditionally returned | Encrypted data field created by the issuer and passed to Google Wallet during the push provisioning process. Allowable Values: Any value |
| push_tokenize_request_data.last_digits string Conditionally returned | Last four digits of the primary account number of the physical or virtual card. Allowable Values: 4 chars |
| push_tokenize_request_data.network string Conditionally returned | Specifies the card network of the physical or virtual card. Allowable Values: Visa, Mastercard |
| push_tokenize_request_data.token_service_provider string Conditionally returned | Specifies the network that provides the digital wallet token service. Allowable Values: TOKEN_PROVIDER_VISA, TOKEN_PROVIDER_MASTERCARD |
| push_tokenize_request_data.user_address object Conditionally returned | Specifies the cardholder address. Allowable Values: name, address1, address2, city, state, postal_code, country, phone |
| push_tokenize_request_data.user_address.name string Returned | Name of the cardholder. Allowable Values: Any value |
| push_tokenize_request_data.user_address.address1 string Returned | Street address of the cardholder. Allowable Values: Any value |
| push_tokenize_request_data.user_address.address2 string Returned | Additional address information for the cardholder, such as a suite or apartment number.Suite 600, for example.Allowable Values: Any value |
| push_tokenize_request_data.user_address.city string Returned | City of the cardholder. Allowable Values: Any value |
| push_tokenize_request_data.user_address.state string Returned | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: Any value |
| push_tokenize_request_data.user_address.postal_code string Returned | Postal code of the cardholder, such as a United States ZIP code. 94612, for example.Allowable Values: 255 char max |
| push_tokenize_request_data.user_address.country string Returned | Two-character ISO alpha-2 country code. US, for example.Allowable Values: 255 char max |
| push_tokenize_request_data.user_address.phone string Returned | Telephone number of the cardholder. Allowable Values: 255 char max |
Sample response body
JSON
Create digital wallet token provisioning request for Samsung Wallet
Action:POSTEndpoint:
/digitalwalletprovisionrequests/samsungpay
Note
This endpoint is limited in availability. For more information, contact your Marqeta representative.
This endpoint is limited in availability. For more information, contact your Marqeta representative.
Request body
| Fields | Description |
|---|---|
| card_token string Required | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| device_id string Required | User’s Samsung device unique identifier, as provided by Samsung during the provisioning process. Allowable Values: 1–24 chars |
| device_type string Required | Type of device into which the digital wallet token will be provisioned. Allowable Values: MOBILE_PHONE, TABLET, WATCH |
| provisioning_app_version string Required | Version of the application making the provisioning request. Used for debugging and fraud prevention. Allowable Values: 1–50 chars |
| wallet_user_id string Required | User’s Samsung Wallet account ID, as provided by Samsung during the provisioning process. Allowable Values: 1–50 chars |
Response body
| Fields | Description |
|---|---|
| card_token string Returned | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| created_time datetime Returned | Date and time when the digital wallet provisioning request was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| last_modified_time datetime Returned | Date and time when the digital wallet token provisioning request was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| push_tokenize_request_data object Conditionally returned | Contains details about a card tokenization push request. Allowable Values: card_type, display_name, extra_provision_payload, last_digits, network, token_service_provider |
| push_tokenize_request_data.card_type string Conditionally returned | Specifies the type of card. Allowable Values: PAYMENT, DEBIT, CREDIT, LOYALTY, GIFT |
| push_tokenize_request_data.display_name string Conditionally returned | Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). Visa 5678, for example.Allowable Values: Any value |
| push_tokenize_request_data.extra_provision_payload string Conditionally returned | Encrypted card or cardholder details. Allowable Values: Any value |
| push_tokenize_request_data.last_digits string Conditionally returned | Last four digits of the primary account number of the physical or virtual card. Allowable Values: 4 chars |
| push_tokenize_request_data.network string Conditionally returned | Specifies the card network of the physical or virtual card. Allowable Values: Visa, Mastercard |
| push_tokenize_request_data.token_service_provider string Conditionally returned | Specifies the network that provides the digital wallet token service, as determined by the Samsung Wallet library. Allowable Values: VI, MC |
Create digital wallet token provisioning request for XPay
Action:POSTEndpoint:
/digitalwalletprovisionrequests/xpay
Note
This endpoint is limited in availability. For more information, contact your Marqeta representative.
This endpoint is limited in availability. For more information, contact your Marqeta representative.
Request body
| Fields | Description |
|---|---|
| card_token string Required | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| device_id string Required | Unique identifier of the user’s XPay device, as provided by XPay during the provisioning process. Allowable Values: 1–24 chars |
| device_type string Required | Type of device into which the digital wallet token will be provisioned. Allowable Values: MOBILE_PHONE, TABLET, WATCH |
| provisioning_app_version string Required | Version of the application making the provisioning request. Used for debugging and fraud prevention. Allowable Values: 1–50 chars |
| token_requestor_id string Required | Unique numerical identifier of the digital wallet token requestor within the card network. These ID numbers map to token_requestor_name field values as follows:Mastercard - 50110030273 – APPLE_PAY- 50120834693 – ANDROID_PAY- 50139059239 – SAMSUNG_PAYVisa - 40010030273 – APPLE_PAY- 40010075001 – ANDROID_PAY- 40010043095 – SAMSUNG_PAY- 40010075196 – MICROSOFT_PAY- 40010075338 – VISA_CHECKOUT- 40010075449 – FACEBOOK- 40010075839 – NETFLIX- 40010077056 – FITBIT_PAY- 40010069887 – GARMIN_PAYAllowable Values: 11 char max Example Values: - Mastercard – 50110030273, 50120834693, 50139059239 - Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095 |
| wallet_account_id string Required | User’s XPay account identifier, as provided by XPay during the provisioning process. Allowable Values: 1–50 chars |
Response body
| Fields | Description |
|---|---|
| card_token string Returned | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| created_time datetime Returned | Date and time when the digital wallet provisioning request was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| last_modified_time datetime Returned | Date and time when the digital wallet token provisioning request was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| push_tokenize_request_data object Conditionally returned | Contains details about a card tokenization push request. Allowable Values: card_type, display_name, extra_provision_payload, last_digits, network, token_service_provider |
| push_tokenize_request_data.card_type string Conditionally returned | Specifies the type of card. Allowable Values: PAYMENT, DEBIT, CREDIT, LOYALTY, GIFT |
| push_tokenize_request_data.display_name string Conditionally returned | Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). Visa 5678, for example.Allowable Values: Any value |
| push_tokenize_request_data.extra_provision_payload string Conditionally returned | Encrypted card or cardholder details. Allowable Values: Any value |
| push_tokenize_request_data.last_digits string Conditionally returned | Last four digits of the primary account number of the physical or virtual card. Allowable Values: 4 chars |
| push_tokenize_request_data.network string Conditionally returned | Specifies the card network of the physical or virtual card. Allowable Values: Visa, Mastercard |
| push_tokenize_request_data.token_service_provider string Conditionally returned | Specifies the network that provides the digital wallet token service. Allowable Values: TOKEN_PROVIDER_VISA, TOKEN_PROVIDER_MASTERCARD |
Create digital wallet token transition
Action:POSTEndpoint:
/digitalwallettokentransitions
Use this endpoint to transition a digital wallet token from one state to another.
Request body
| Fields | Description |
|---|---|
| channel string Optional | Mechanism by which the transition was initiated. Allowable Values: TOKEN_SERVICE_PROVIDER, TOKEN_SERVICE_PROVIDER_API, DIGITAL_WALLET, API, IVR, FRAUD, ADMIN, SYSTEM |
| digital_wallet_token object Required | Contains identifiers of the digital wallet token resource and the card resource. Allowable Values: Unique identifiers of the digital wallet token resource and the card resource |
| digital_wallet_token.token string Required | Unique identifier of the digital wallet token resource. Allowable Values: 1–36 chars |
| digital_wallet_token.card_token string Optional | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| reason string Optional | The reason for the transition. Allowable Values: 255 char max |
| reason_code string Optional | Standard code describing the reason for the transition. NOTE: This field is required if your program uses v2 of the user_card_state_version, which is a program-specific configuration value that is managed by Marqeta and cannot be accessed via the API. To learn more about the user_card_state_version program configuration, contact your Marqeta representative.- 00: Object activated for the first time - 01: Requested by you - 02: Inactivity over time - 03: This address cannot accept mail or the addressee is unknown - 04: Negative account balance - 05: Account under review - 06: Suspicious activity was identified - 07: Activity outside the program parameters was identified - 08: Confirmed fraud was identified - 09: Matched with an Office of Foreign Assets Control list - 10: Card was reported lost - 11: Card information was cloned - 12: Account or card information was compromised - 13: Temporary status change while on hold/leave - 14: Initiated by Marqeta - 15: Initiated by issuer - 16: Card expired - 17: Failed KYC - 18: Changed to ACTIVE because information was properly validated- 19: Changed to ACTIVE because account activity was properly validated- 20: Change occurred prior to the normalization of reason codes - 21: Initiated by a third party, often a digital wallet provider - 22: PIN retry limit reached - 23: Card was reported stolen - 24: Address issue - 25: Name issue - 26: SSN issue - 27: DOB issue - 28: Email issue - 29: Phone issue - 30: Account/fulfillment mismatch - 31: Other reason - 32: Unblock request - 86: Notification of death Allowable Values: 00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86 |
| state string Required | Specifies the state to which the digital wallet token will transition. The original state is REQUESTED. You cannot modify the state if its current value is either REQUEST_DECLINED or TERMINATED.Allowable Values: ACTIVE, SUSPENDED, TERMINATED |
| token string Optional | The unique identifier of the digital wallet token transition (not the identifier of the digital wallet token itself). If you do not include a value for the token field, the system will generate one automatically. This value is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.Allowable Values: 1–36 chars |
| token_reference_id string Optional | The unique identifier of the digital wallet token within the card network. The token_reference_id is unique at the card network level.Allowable Values: 255 char max |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| card_swap object Conditionally returned | Contains identifiers for swapping digital wallet tokens between cards. Allowable Values: new_card_token, previous_card_token |
| card_swap.new_card_token string Returned | Unique identifier of the new card resource to which the digital wallet tokens are assigned. Allowable Values: 1–36 chars |
| card_swap.previous_card_token string Returned | Unique identifier of the existing card resource that has digital wallet tokens assigned to it. Allowable Values: 1–36 chars |
| channel string Returned | Mechanism by which the transition was initiated. Allowable Values: TOKEN_SERVICE_PROVIDER, DIGITAL_WALLET, API, IVR, FRAUD, ADMIN, SYSTEM, TOKEN_SERVICE_PROVIDER_API |
| created_time datetime Conditionally returned | Date and time when the transition was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| digital_wallet_token object Returned | Contains identifiers of the digital wallet token resource and the card resource. Allowable Values: Unique identifiers of the digital wallet token resource and the card resource |
| digital_wallet_token.token string Returned | Unique identifier of the digital wallet token resource. Allowable Values: 1–36 chars |
| digital_wallet_token.card_token string Conditionally returned | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| fulfillment_status string Returned | Provisioning status of the digital wallet token. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED |
| reason string Conditionally returned | Reason for the transition. Allowable Values: 255 char max |
| reason_code string Conditionally returned | Standard code describing the reason for the transition: - 00: Object activated for the first time - 01: Requested by you - 02: Inactivity over time - 03: This address cannot accept mail or the addressee is unknown - 04: Negative account balance - 05: Account under review - 06: Suspicious activity was identified - 07: Activity outside the program parameters was identified - 08: Confirmed fraud was identified - 09: Matched with an Office of Foreign Assets Control list - 10: Card was reported lost - 11: Card information was cloned - 12: Account or card information was compromised - 13: Temporary status change while on hold/leave - 14: Initiated by Marqeta - 15: Initiated by issuer - 16: Card expired - 17: Failed KYC - 18: Changed to ACTIVE because information was properly validated- 19: Changed to ACTIVE because account activity was properly validated- 20: Change occurred prior to the normalization of reason codes - 21: Initiated by a third party, often a digital wallet provider - 22: PIN retry limit reached - 23: Card was reported stolen - 24: Address issue - 25: Name issue - 26: SSN issue - 27: DOB issue - 28: Email issue - 29: Phone issue - 30: Account/fulfillment mismatch - 31: Other reason - 32: Unblock request - 86: Notification of death Allowable Values: 00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86 |
| state string Returned | Specifies the state to which the digital wallet token is transitioning. Allowable Values: REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED |
| token string Returned | Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself. Allowable Values: 1–36 chars |
| type string Returned | Type of digital wallet token transition. state.activated, for example.Allowable Values: 36 char max |
Sample response body
JSON
Retrieve digital wallet token transition
Action:GETEndpoint:
/digitalwallettokentransitions/{token}
Use this endpoint to retrieve a specific digital wallet token transition.
This endpoint supports field filtering.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the digital wallet token (DWT) transition. Allowable Values: Existing DWT transition token |
URL query parameters
| Fields | Description |
|---|---|
| fields string Optional | Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.Allowable Values: Comma-delimited list of fields, or blank |
Response body
| Fields | Description |
|---|---|
| card_swap object Conditionally returned | Contains identifiers for swapping digital wallet tokens between cards. Allowable Values: new_card_token, previous_card_token |
| card_swap.new_card_token string Returned | Unique identifier of the new card resource to which the digital wallet tokens are assigned. Allowable Values: 1–36 chars |
| card_swap.previous_card_token string Returned | Unique identifier of the existing card resource that has digital wallet tokens assigned to it. Allowable Values: 1–36 chars |
| channel string Returned | Mechanism by which the transition was initiated. Allowable Values: TOKEN_SERVICE_PROVIDER, DIGITAL_WALLET, API, IVR, FRAUD, ADMIN, SYSTEM, TOKEN_SERVICE_PROVIDER_API |
| created_time datetime Conditionally returned | Date and time when the transition was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| digital_wallet_token object Returned | Contains identifiers of the digital wallet token resource and the card resource. Allowable Values: Unique identifiers of the digital wallet token resource and the card resource |
| digital_wallet_token.token string Returned | Unique identifier of the digital wallet token resource. Allowable Values: 1–36 chars |
| digital_wallet_token.card_token string Conditionally returned | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| fulfillment_status string Returned | Provisioning status of the digital wallet token. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED |
| reason string Conditionally returned | Reason for the transition. Allowable Values: 255 char max |
| reason_code string Conditionally returned | Standard code describing the reason for the transition: - 00: Object activated for the first time - 01: Requested by you - 02: Inactivity over time - 03: This address cannot accept mail or the addressee is unknown - 04: Negative account balance - 05: Account under review - 06: Suspicious activity was identified - 07: Activity outside the program parameters was identified - 08: Confirmed fraud was identified - 09: Matched with an Office of Foreign Assets Control list - 10: Card was reported lost - 11: Card information was cloned - 12: Account or card information was compromised - 13: Temporary status change while on hold/leave - 14: Initiated by Marqeta - 15: Initiated by issuer - 16: Card expired - 17: Failed KYC - 18: Changed to ACTIVE because information was properly validated- 19: Changed to ACTIVE because account activity was properly validated- 20: Change occurred prior to the normalization of reason codes - 21: Initiated by a third party, often a digital wallet provider - 22: PIN retry limit reached - 23: Card was reported stolen - 24: Address issue - 25: Name issue - 26: SSN issue - 27: DOB issue - 28: Email issue - 29: Phone issue - 30: Account/fulfillment mismatch - 31: Other reason - 32: Unblock request - 86: Notification of death Allowable Values: 00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86 |
| state string Returned | Specifies the state to which the digital wallet token is transitioning. Allowable Values: REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED |
| token string Returned | Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself. Allowable Values: 1–36 chars |
| type string Returned | Type of digital wallet token transition. state.activated, for example.Allowable Values: 36 char max |
Sample response body
JSON
List transitions for digital wallet token
Action:GETEndpoint:
/digitalwallettokentransitions/digitalwallettoken/{token}
Use this endpoint to return an array of all transitions for a particular digital wallet token.
This endpoint supports field filtering, pagination, and sorting.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the digital wallet token (DWT). Allowable Values: Existing DWT token |
URL query parameters
| Fields | Description |
|---|---|
| count integer Optional | Number of digital wallet transitions to retrieve. Allowable Values: Any integer Default value: 5 |
| start_index integer Optional | The sort order index of the first digital wallet token in the returned array. Allowable Values: Any integer Default value: 0 |
| fields string Optional | Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.Allowable Values: Comma-delimited list of fields, or blank |
| sort_by string Optional | Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.Allowable Values: createdTime, lastModifiedTime, or any field in the resource modelDefault value: -id |
Response body
| Fields | Description |
|---|---|
| count integer Conditionally returned | Number of resources returned. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
| data array of objects Conditionally returned | Array of digital wallet token transition resources. Resources are returned as appropriate to your query. Allowable Values: One or more digital wallet token transition resources |
| data[].card_swap object Conditionally returned | Contains identifiers for swapping digital wallet tokens between cards. Allowable Values: new_card_token, previous_card_token |
| data[].card_swap.new_card_token string Returned | Unique identifier of the new card resource to which the digital wallet tokens are assigned. Allowable Values: 1–36 chars |
| data[].card_swap.previous_card_token string Returned | Unique identifier of the existing card resource that has digital wallet tokens assigned to it. Allowable Values: 1–36 chars |
| data[].channel string Returned | Mechanism by which the transition was initiated. Allowable Values: TOKEN_SERVICE_PROVIDER, DIGITAL_WALLET, API, IVR, FRAUD, ADMIN, SYSTEM, TOKEN_SERVICE_PROVIDER_API |
| data[].created_time datetime Conditionally returned | Date and time when the transition was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].digital_wallet_token object Returned | Contains identifiers of the digital wallet token resource and the card resource. Allowable Values: Unique identifiers of the digital wallet token resource and the card resource |
| data[].digital_wallet_token.token string Returned | Unique identifier of the digital wallet token resource. Allowable Values: 1–36 chars |
| data[].digital_wallet_token.card_token string Conditionally returned | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| data[].fulfillment_status string Returned | Provisioning status of the digital wallet token. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED |
| data[].reason string Conditionally returned | Reason for the transition. Allowable Values: 255 char max |
| data[].reason_code string Conditionally returned | Standard code describing the reason for the transition: - 00: Object activated for the first time - 01: Requested by you - 02: Inactivity over time - 03: This address cannot accept mail or the addressee is unknown - 04: Negative account balance - 05: Account under review - 06: Suspicious activity was identified - 07: Activity outside the program parameters was identified - 08: Confirmed fraud was identified - 09: Matched with an Office of Foreign Assets Control list - 10: Card was reported lost - 11: Card information was cloned - 12: Account or card information was compromised - 13: Temporary status change while on hold/leave - 14: Initiated by Marqeta - 15: Initiated by issuer - 16: Card expired - 17: Failed KYC - 18: Changed to ACTIVE because information was properly validated- 19: Changed to ACTIVE because account activity was properly validated- 20: Change occurred prior to the normalization of reason codes - 21: Initiated by a third party, often a digital wallet provider - 22: PIN retry limit reached - 23: Card was reported stolen - 24: Address issue - 25: Name issue - 26: SSN issue - 27: DOB issue - 28: Email issue - 29: Phone issue - 30: Account/fulfillment mismatch - 31: Other reason - 32: Unblock request - 86: Notification of death Allowable Values: 00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86 |
| data[].state string Returned | Specifies the state to which the digital wallet token is transitioning. Allowable Values: REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED |
| data[].token string Returned | Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself. Allowable Values: 1–36 chars |
| data[].type string Returned | Type of digital wallet token transition. state.activated, for example.Allowable Values: 36 char max |
| end_index integer Conditionally returned | Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
| is_more boolean Conditionally returned | A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.This field is returned if there are resources in your returned array. Allowable Values: true, false |
| start_index integer Conditionally returned | Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
Sample response body
JSON
List digital wallet tokens
Action:GETEndpoint:
/digitalwallettokens
Use this endpoint to retrieve a list of digital wallet tokens.
URL query parameters
| Fields | Description |
|---|---|
| count integer Optional | Number of digital wallet token resources to retrieve. Allowable Values: 1–100 Default value: 10 |
| start_index integer Optional | Sort order index of the first digital wallet token resource in the returned array. Allowable Values: Any integer Default value: 0 |
| fields string Optional | Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.Allowable Values: Comma-delimited list of fields, or blank |
| sort_by string Optional | Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.Allowable Values: createdTime, lastModifiedTime, or any field in the resource modelDefault value: -createdTime |
| start_date string Optional | Date when the digital wallet token becomes active. Allowable Values: Format: yyyy-MM-dd |
| end_date string Optional | Expiration date of the digital wallet token. Allowable Values: Format: yyyy-MM-dd |
| pan_reference_id string Optional | Unique identifier of the digital wallet token primary account number (PAN) within the card network. This value may vary, depending on the digital wallet. For example, the pan_reference_id may be different in Apple Wallet and Google Wallet for the same digital wallet token.Allowable Values: 255 char max |
| token_reference_id string Optional | Unique identifier of the digital wallet token within the card network. The token_reference_id is unique at the card network level.Allowable Values: 255 char max |
| correlation_id string Optional | Unique value representing a tokenization request (Mastercard only). Allowable Values: 255 char max |
| token_type string Optional | Comma-delimited list of digital wallet token types to display. Allowable Values: 255 char max Example Values: DEVICE_SECURE_ELEMENT, MERCHANT_CARD_ON_FILE, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT. |
| token_requestor_name string Optional | Name of the token requestor within the card network. NOTE: The list of example values for this field is maintained by the card networks and is subject to change. Allowable Values: 255 char max Example Values: - Mastercard – APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY- Visa – APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY |
| state string Optional | Comma-delimited list of digital wallet token states to display. Allowable Values: 255 char max Example Values: REQUESTED, REQUEST_DECLINED, TERMINATED, SUSPENDED, ACTIVE |
| embed string Optional | An optional embedded user object. Allowable Values: user |
Response body
| Fields | Description |
|---|---|
| count integer Conditionally returned | Number of resources returned. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
| data array of objects Conditionally returned | Array of digital wallet token resources. Resources are returned as appropriate to your query. Allowable Values: Valid array of one or more digital wallet token resources |
| data[].address_verification object Conditionally returned | Contains address verification information. Allowable Values: name, postal_code, street_address, zip |
| data[].address_verification.name string Conditionally returned | Name of the cardholder. Allowable Values: 40 char max |
| data[].address_verification.postal_code string Conditionally returned | Postal code. Allowable Values: 10 char max |
| data[].address_verification.street_address string Conditionally returned | Street address provided by the cardholder. Allowable Values: 40 char max |
| data[].address_verification.zip string Conditionally returned | United States ZIP code. Allowable Values: 10 char max |
| data[].card_token string Conditionally returned | Unique identifier of the card. Allowable Values: Existing card token |
| data[].created_time datetime Conditionally returned | Date and time when the digital wallet token object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].device object Conditionally returned | Contains information related to the device being provisioned. Allowable Values: device_id, ip_address, language_code, location, name, phone_number, token, type |
| data[].device.device_id string Conditionally returned | Identity number of the device. Allowable Values: 24 char max |
| data[].device.ip_address string Conditionally returned | Device’s IP address. Allowable Values: IP address format, 50 char max |
| data[].device.language_code string Conditionally returned | Language the device is configured to use. Allowable Values: 50 char max |
| data[].device.location string Conditionally returned | Geographic coordinates of the device. Allowable Values: Latitude and longitude in DDD.DD/DDD.DD format.NOTE: Both the longitude and latitude are prefixed with either a + or - symbol, for example: +42.29/-71.07. |
| data[].device.name string Conditionally returned | Name of the device. Allowable Values: 50 char max |
| data[].device.phone_number string Conditionally returned | Device’s telephone number. Allowable Values: 50 char max |
| data[].device.token string Conditionally returned | Unique identifier of the device object. Allowable Values: 36 char max |
| data[].device.type string Conditionally returned | Type of device being provisioned. Allowable Values: MOBILE_PHONE, WATCH, TABLET, MOBILE_PHONE_OR_TABLET, VEHICLE, APPLIANCE, LAPTOP, GAMING_DEVICE, WEARABLE_DEVICE, UNKNOWN |
| data[].fulfillment_status string Conditionally returned | Digital wallet token’s provisioning status. For fulfillment status descriptions, see Create digital wallet token transition. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED |
| data[].issuer_eligibility_decision string Conditionally returned | The Marqeta platform’s decision as to whether the digital wallet token should be provisioned. - 0000 – The token should be provisioned. - token.activation.verification.required – Provisioning is pending; further action is required for completion. For all other values, check the value of the fulfillment_status field to definitively ascertain the provisioning outcome.NOTE: The value invalid.cid indicates an invalid CVV2 number.Allowable Values: 0000, cardaccount.verified, card.suspicious, token.activation.verification.required, token.activation-request.decline, card.not.active, invalid.cid, card.expired, card.suspended, cardholder.not.active |
| data[].last_modified_time datetime Conditionally returned | Date and time when the digital wallet token object was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].metadata object Conditionally returned | Contains additional information about the digital wallet token. Allowable Values: cardproduct_preferred_notification_language, issuer_product_config_id |
| data[].metadata.cardproduct_preferred_notification_language string Conditionally returned | Language specified in the config.transaction_controls.notification_language field of the card product:- ces – Czech - deu – German - eng – English - fra – French - grc – Greek - ita – Italian - nld – Dutch - pol – Polish - por – Portuguese - rou – Romanian - spa – Spanish - swe – Swedish By default, notifications are sent in English. The ISO maintains the full list of ISO 3166 two- and three-digit numeric country codes. Allowable Values: ces, deu, eng, fra, grc, ita, nld, pol, por, rou, spa, swe |
| data[].metadata.issuer_product_config_id string Conditionally returned | Unique identifier of the product configuration on the Marqeta platform. Allowable Values: 255 char max |
| data[].state string Conditionally returned | State of the digital wallet token. For state descriptions, see Transitioning Token States. Allowable Values: REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED |
| data[].state_reason string Conditionally returned | Reason why the digital wallet token transitioned to its current state. Allowable Values: 255 char max |
| data[].token string Conditionally returned | Unique identifier of the digital wallet token. Allowable Values: Existing digital wallet token. |
| data[].token_service_provider object Conditionally returned | Contains information held and provided by the token service provider (card network). Allowable Values: correlation_id, pan_reference_id, token_assurance_level, token_eligibility_decision, token_expiration, token_pan, token_reference_id, token_requestor_id, token_requestor_name, token_score, token_type |
| data[].token_service_provider.correlation_id string Conditionally returned | For Mastercard only. Unique value representing a tokenization request. Allowable Values: Existing correlation identifier |
| data[].token_service_provider.pan_reference_id string Conditionally returned | Unique identifier of the digital wallet token primary account number (PAN) within the card network. Allowable Values: Existing PAN Reference ID |
| data[].token_service_provider.token_assurance_level string Conditionally returned | For Mastercard only. Represents the confidence level in the digital wallet token. Allowable Values: 0-99 |
| data[].token_service_provider.token_eligibility_decision string Conditionally returned | Digital wallet’s decision as to whether the digital wallet token should be provisioned. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN |
| data[].token_service_provider.token_expiration string Conditionally returned | Expiration date of the digital wallet token. Allowable Values: Format: MMyy |
| data[].token_service_provider.token_pan string Conditionally returned | Primary account number (PAN) of the digital wallet token. Allowable Values: 16 char max |
| data[].token_service_provider.token_reference_id string Conditionally returned | Unique identifier of the digital wallet token within the card network. Allowable Values: Existing Token Reference ID |
| data[].token_service_provider.token_requestor_id string Conditionally returned | Unique numerical identifier of the token requestor within the card network. These ID numbers map to token_requestor_name field values as follows:Mastercard - 50110030273 – APPLE_PAY- 50120834693 – ANDROID_PAY- 50139059239 – SAMSUNG_PAYVisa - 40010030273 – APPLE_PAY- 40010075001 – ANDROID_PAY- 40010043095 – SAMSUNG_PAY- 40010075196 – MICROSOFT_PAY- 40010075338 – VISA_CHECKOUT- 40010075449 – FACEBOOK- 40010075839 – NETFLIX- 40010077056 – FITBIT_PAY- 40010069887 – GARMIN_PAYAllowable Values: 11 char max Example Values: - Mastercard – 50110030273, 50120834693, 50139059239 - Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095 |
| data[].token_service_provider.token_requestor_name string Conditionally returned | Name of the token requestor within the card network. NOTE: The list of example values for this field is maintained by the card networks and is subject to change. Allowable Values: 255 char max Example Values: - Mastercard – APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY- Visa – APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY |
| data[].token_service_provider.token_score string Conditionally returned | Token score assigned by the digital wallet. Allowable Values: 25 char max |
| data[].token_service_provider.token_type string Conditionally returned | Type of the digital wallet token. Allowable Values: MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET |
| data[].transaction_device object Conditionally returned | Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution. Allowable Values: binding_id, ip_address, location, phone_number |
| data[].transaction_device.binding_id string Conditionally returned | Unique identifier of the data component bound to the credential. Allowable Values: 48 char max |
| data[].transaction_device.ip_address string Conditionally returned | IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction. Allowable Values: IP address format, 39 char max |
| data[].transaction_device.location string Conditionally returned | Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location. Allowable Values: Latitude and longitude in DDD.DD/DDD.DD format. |
| data[].transaction_device.phone_number string Conditionally returned | Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer. Allowable Values: 15 char max |
| data[].user object Conditionally returned | Contains information about a cardholder. Allowable Values: account_holder_group_token, active, address1, address2, authentication, birth_date, birth_place, business_token, city, company, corporate_card_holder, country, created_time, email, first_name, gender, honorific, id_card_expiration_date, id_card_number, identifications, ip_address, last_modified_time, last_name, metadata, middle_name, nationality, notes, parent_token, passport_expiration_date, passport_number, password, phone, postal_code, ssn, state, status, title, token, uses_parent_account, zip |
| data[].user.account_holder_group_token string Conditionally returned | Associates the specified account holder group with the cardholder. Allowable Values: 36 char max |
| data[].user.active boolean Conditionally returned | Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.Allowable Values: true, false |
| data[].user.address1 string Conditionally returned | Cardholder’s address. Allowable Values: 255 char max |
| data[].user.address2 string Conditionally returned | Additional address information for the cardholder. Allowable Values: 255 char max |
| data[].user.authentication object Conditionally returned | Contains the cardholder’s email address and password information. Allowable Values: email_verified, email_verified_time, last_password_update_channel, last_password_update_time |
| data[].user.authentication.email_verified boolean Conditionally returned | Specifies whether the email address has been verified. Allowable Values: true, false |
| data[].user.authentication.email_verified_time datetime Conditionally returned | Date and time when the email address was verified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].user.authentication.last_password_update_channel string Conditionally returned | Specifies the channel through which the password was last changed. Allowable Values: USER_CHANGE, USER_RESET |
| data[].user.authentication.last_password_update_time datetime Conditionally returned | Date and time when the password was last changed. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].user.birth_date string Conditionally returned | Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd |
| data[].user.birth_place string Conditionally returned | Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is US.The ISO maintains the full list of ISO-3166 country codes. |
| data[].user.business_token string Conditionally returned | Unique identifier of the business resource. Allowable Values: Existing business resource token |
| data[].user.city string Conditionally returned | City where the cardholder resides. Allowable Values: 40 char max |
| data[].user.company string Conditionally returned | Company name. Allowable Values: 255 char max |
| data[].user.corporate_card_holder boolean Conditionally returned | Specifies if the cardholder holds a corporate card. Allowable Values: true, false |
| data[].user.country string Conditionally returned | Country where the cardholder resides. Allowable Values: 40 char max |
| data[].user.created_time datetime Returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].user.email string Conditionally returned | Valid email address of the cardholder. Allowable Values: 1–255 chars |
| data[].user.first_name string Conditionally returned | Cardholder’s first name. Allowable Values: 40 char max |
| data[].user.gender string Conditionally returned | Gender of the cardholder. Allowable Values: F, M |
| data[].user.honorific string Conditionally returned | Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
| data[].user.id_card_expiration_date string Conditionally returned | Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd |
| data[].user.id_card_number string Conditionally returned | Cardholder’s identification card number. Allowable Values: 255 char max |
| data[].user.identifications array of objects Conditionally returned | One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more identifications objects |
| data[].user.identifications[].expiration_date string Conditionally returned | Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
| data[].user.identifications[].type string Conditionally returned | Type of identification. Allowable Values: SSN, TIN, SIN, NIN, PASSPORT_NUMBER, DRIVERS_LICENSE, BUSINESS_NUMBER, BUSINESS_TAX_ID, TAXPAYER_REFERENCE |
| data[].user.identifications[].value string Conditionally returned | Number associated with the identification. Allowable Values: 255 char max |
| data[].user.ip_address string Conditionally returned | Cardholder’s IP address. Allowable Values: 39 char max |
| data[].user.last_modified_time datetime Returned | Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].user.last_name string Conditionally returned | Cardholder’s last name. Allowable Values: 40 char max |
| data[].user.metadata object Conditionally returned | Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1" |
| data[].user.middle_name string Conditionally returned | Cardholder’s middle name. Allowable Values: 40 char max |
| data[].user.nationality string Conditionally returned | Cardholder’s nationality. Allowable Values: 255 char max |
| data[].user.notes string Conditionally returned | Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
| data[].user.parent_token string Conditionally returned | Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars |
| data[].user.passport_expiration_date string Conditionally returned | Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
| data[].user.passport_number string Conditionally returned | Cardholder’s passport number. Allowable Values: 40 char max |
| data[].user.password string Conditionally returned | Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars |
| data[].user.phone string Conditionally returned | Cardholder’s telephone number. Allowable Values: 255 char max |
| data[].user.postal_code string Conditionally returned | Postal code of the cardholder’s address. Allowable Values: 10 char max |
| data[].user.ssn string Conditionally returned | Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters. |
| data[].user.state string Conditionally returned | State or province where the cardholder resides. Allowable Values: 2 char max |
| data[].user.status string Conditionally returned | Specifies the status of the cardholder on the Marqeta platform. Allowable Values: UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED |
| data[].user.title string Conditionally returned | Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max |
| data[].user.token string Conditionally returned | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
| data[].user.uses_parent_account boolean Conditionally returned | Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).Allowable Values: true, false |
| data[].user.zip string Conditionally returned | United States ZIP code of the cardholder’s address. Allowable Values: 10 char max |
| data[].wallet_provider_profile object Conditionally returned | Contains information held and provided by the digital wallet provider. Allowable Values: account, device_score, pan_source, reason_code, recommendation_reasons, risk_assessment |
| data[].wallet_provider_profile.account object Conditionally returned | Contains information related to the cardholder and provided by the digital wallet provider. Allowable Values: email_address, id, score |
| data[].wallet_provider_profile.account.email_address string Conditionally returned | Digital wallet provider’s email address for the cardholder. Allowable Values: 255 char max |
| data[].wallet_provider_profile.account.id string Conditionally returned | Digital wallet provider’s identity number for the cardholder. Allowable Values: 20 char max |
| data[].wallet_provider_profile.account.score string Conditionally returned | Score from the digital wallet provider. Allowable Values: 50 char max |
| data[].wallet_provider_profile.device_score string Conditionally returned | Score from the device. Allowable Values: 50 char max |
| data[].wallet_provider_profile.pan_source string Conditionally returned | Source from which the digital wallet provider obtained the card primary account number (PAN). Allowable Values: KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP |
| data[].wallet_provider_profile.reason_code string Conditionally returned | Reason for the wallet provider’s provisioning decision. - 01 – Cardholder’s wallet account is too new relative to launch. - 02 – Cardholder’s wallet account is too new relative to provisioning request. - 03 – Cardholder’s wallet account/card pair is newer than date threshold. - 04 – Changes made to account data within the account threshold. - 05 – Suspicious transactions linked to this account. - 06 – Account has not had activity in the last year. - 07 – Suspended cards in the secure element. - 08 – Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B – The card provisioning attempt contains a distinct name in excess of the threshold. - 0C – The device score is less than 3. - 0D – The account score is less than 4. - 0E – Device provisioning location outside of the cardholder’s wallet account home country. - 0G – Suspect fraud. Allowable Values: 01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G |
| data[].wallet_provider_profile.recommendation_reasons array of strings Conditionally returned | Array of recommendation reasons from the digital wallet provider. Allowable Values: Valid array of one or more recommendation reasons |
| data[].wallet_provider_profile.risk_assessment object Conditionally returned | Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token. Allowable Values: score, version |
| data[].wallet_provider_profile.risk_assessment.score string Conditionally returned | Wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN |
| data[].wallet_provider_profile.risk_assessment.version string Conditionally returned | Wallet provider’s risk assessment version. Allowable Values: Version information, as provided by the wallet provider |
| end_index integer Conditionally returned | Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
| is_more boolean Conditionally returned | A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.This field is returned if there are resources in your returned array. Allowable Values: true, false |
| start_index integer Conditionally returned | Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
Retrieve digital wallet token
Action:GETEndpoint:
/digitalwallettokens/{token}
Use this endpoint to retrieve a specific digital wallet token.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the digital wallet token (DWT). Allowable Values: Existing DWT token |
Response body
| Fields | Description |
|---|---|
| address_verification object Conditionally returned | Contains address verification information. Allowable Values: name, postal_code, street_address, zip |
| address_verification.name string Conditionally returned | Name of the cardholder. Allowable Values: 40 char max |
| address_verification.postal_code string Conditionally returned | Postal code. Allowable Values: 10 char max |
| address_verification.street_address string Conditionally returned | Street address provided by the cardholder. Allowable Values: 40 char max |
| address_verification.zip string Conditionally returned | United States ZIP code. Allowable Values: 10 char max |
| card_token string Conditionally returned | Unique identifier of the card. Allowable Values: Existing card token |
| created_time datetime Conditionally returned | Date and time when the digital wallet token object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| device object Conditionally returned | Contains information related to the device being provisioned. Allowable Values: device_id, ip_address, language_code, location, name, phone_number, token, type |
| device.device_id string Conditionally returned | Identity number of the device. Allowable Values: 24 char max |
| device.ip_address string Conditionally returned | Device’s IP address. Allowable Values: IP address format, 50 char max |
| device.language_code string Conditionally returned | Language the device is configured to use. Allowable Values: 50 char max |
| device.location string Conditionally returned | Geographic coordinates of the device. Allowable Values: Latitude and longitude in DDD.DD/DDD.DD format.NOTE: Both the longitude and latitude are prefixed with either a + or - symbol, for example: +42.29/-71.07. |
| device.name string Conditionally returned | Name of the device. Allowable Values: 50 char max |
| device.phone_number string Conditionally returned | Device’s telephone number. Allowable Values: 50 char max |
| device.token string Conditionally returned | Unique identifier of the device object. Allowable Values: 36 char max |
| device.type string Conditionally returned | Type of device being provisioned. Allowable Values: MOBILE_PHONE, WATCH, TABLET, MOBILE_PHONE_OR_TABLET, VEHICLE, APPLIANCE, LAPTOP, GAMING_DEVICE, WEARABLE_DEVICE, UNKNOWN |
| fulfillment_status string Conditionally returned | Digital wallet token’s provisioning status. For fulfillment status descriptions, see Create digital wallet token transition. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED |
| issuer_eligibility_decision string Conditionally returned | The Marqeta platform’s decision as to whether the digital wallet token should be provisioned. - 0000 – The token should be provisioned. - token.activation.verification.required – Provisioning is pending; further action is required for completion. For all other values, check the value of the fulfillment_status field to definitively ascertain the provisioning outcome.NOTE: The value invalid.cid indicates an invalid CVV2 number.Allowable Values: 0000, cardaccount.verified, card.suspicious, token.activation.verification.required, token.activation-request.decline, card.not.active, invalid.cid, card.expired, card.suspended, cardholder.not.active |
| last_modified_time datetime Conditionally returned | Date and time when the digital wallet token object was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| metadata object Conditionally returned | Contains additional information about the digital wallet token. Allowable Values: cardproduct_preferred_notification_language, issuer_product_config_id |
| metadata.cardproduct_preferred_notification_language string Conditionally returned | Language specified in the config.transaction_controls.notification_language field of the card product:- ces – Czech - deu – German - eng – English - fra – French - grc – Greek - ita – Italian - nld – Dutch - pol – Polish - por – Portuguese - rou – Romanian - spa – Spanish - swe – Swedish By default, notifications are sent in English. The ISO maintains the full list of ISO 3166 two- and three-digit numeric country codes. Allowable Values: ces, deu, eng, fra, grc, ita, nld, pol, por, rou, spa, swe |
| metadata.issuer_product_config_id string Conditionally returned | Unique identifier of the product configuration on the Marqeta platform. Allowable Values: 255 char max |
| state string Conditionally returned | State of the digital wallet token. For state descriptions, see Transitioning Token States. Allowable Values: REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED |
| state_reason string Conditionally returned | Reason why the digital wallet token transitioned to its current state. Allowable Values: 255 char max |
| token string Conditionally returned | Unique identifier of the digital wallet token. Allowable Values: Existing digital wallet token. |
| token_service_provider object Conditionally returned | Contains information held and provided by the token service provider (card network). Allowable Values: correlation_id, pan_reference_id, token_assurance_level, token_eligibility_decision, token_expiration, token_pan, token_reference_id, token_requestor_id, token_requestor_name, token_score, token_type |
| token_service_provider.correlation_id string Conditionally returned | For Mastercard only. Unique value representing a tokenization request. Allowable Values: Existing correlation identifier |
| token_service_provider.pan_reference_id string Conditionally returned | Unique identifier of the digital wallet token primary account number (PAN) within the card network. Allowable Values: Existing PAN Reference ID |
| token_service_provider.token_assurance_level string Conditionally returned | For Mastercard only. Represents the confidence level in the digital wallet token. Allowable Values: 0-99 |
| token_service_provider.token_eligibility_decision string Conditionally returned | Digital wallet’s decision as to whether the digital wallet token should be provisioned. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN |
| token_service_provider.token_expiration string Conditionally returned | Expiration date of the digital wallet token. Allowable Values: Format: MMyy |
| token_service_provider.token_pan string Conditionally returned | Primary account number (PAN) of the digital wallet token. Allowable Values: 16 char max |
| token_service_provider.token_reference_id string Conditionally returned | Unique identifier of the digital wallet token within the card network. Allowable Values: Existing Token Reference ID |
| token_service_provider.token_requestor_id string Conditionally returned | Unique numerical identifier of the token requestor within the card network. These ID numbers map to token_requestor_name field values as follows:Mastercard - 50110030273 – APPLE_PAY- 50120834693 – ANDROID_PAY- 50139059239 – SAMSUNG_PAYVisa - 40010030273 – APPLE_PAY- 40010075001 – ANDROID_PAY- 40010043095 – SAMSUNG_PAY- 40010075196 – MICROSOFT_PAY- 40010075338 – VISA_CHECKOUT- 40010075449 – FACEBOOK- 40010075839 – NETFLIX- 40010077056 – FITBIT_PAY- 40010069887 – GARMIN_PAYAllowable Values: 11 char max Example Values: - Mastercard – 50110030273, 50120834693, 50139059239 - Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095 |
| token_service_provider.token_requestor_name string Conditionally returned | Name of the token requestor within the card network. NOTE: The list of example values for this field is maintained by the card networks and is subject to change. Allowable Values: 255 char max Example Values: - Mastercard – APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY- Visa – APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY |
| token_service_provider.token_score string Conditionally returned | Token score assigned by the digital wallet. Allowable Values: 25 char max |
| token_service_provider.token_type string Conditionally returned | Type of the digital wallet token. Allowable Values: MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET |
| transaction_device object Conditionally returned | Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution. Allowable Values: binding_id, ip_address, location, phone_number |
| transaction_device.binding_id string Conditionally returned | Unique identifier of the data component bound to the credential. Allowable Values: 48 char max |
| transaction_device.ip_address string Conditionally returned | IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction. Allowable Values: IP address format, 39 char max |
| transaction_device.location string Conditionally returned | Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location. Allowable Values: Latitude and longitude in DDD.DD/DDD.DD format. |
| transaction_device.phone_number string Conditionally returned | Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer. Allowable Values: 15 char max |
| user object Conditionally returned | Contains information about a cardholder. Allowable Values: account_holder_group_token, active, address1, address2, authentication, birth_date, birth_place, business_token, city, company, corporate_card_holder, country, created_time, email, first_name, gender, honorific, id_card_expiration_date, id_card_number, identifications, ip_address, last_modified_time, last_name, metadata, middle_name, nationality, notes, parent_token, passport_expiration_date, passport_number, password, phone, postal_code, ssn, state, status, title, token, uses_parent_account, zip |
| user.account_holder_group_token string Conditionally returned | Associates the specified account holder group with the cardholder. Allowable Values: 36 char max |
| user.active boolean Conditionally returned | Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.Allowable Values: true, false |
| user.address1 string Conditionally returned | Cardholder’s address. Allowable Values: 255 char max |
| user.address2 string Conditionally returned | Additional address information for the cardholder. Allowable Values: 255 char max |
| user.authentication object Conditionally returned | Contains the cardholder’s email address and password information. Allowable Values: email_verified, email_verified_time, last_password_update_channel, last_password_update_time |
| user.authentication.email_verified boolean Conditionally returned | Specifies whether the email address has been verified. Allowable Values: true, false |
| user.authentication.email_verified_time datetime Conditionally returned | Date and time when the email address was verified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| user.authentication.last_password_update_channel string Conditionally returned | Specifies the channel through which the password was last changed. Allowable Values: USER_CHANGE, USER_RESET |
| user.authentication.last_password_update_time datetime Conditionally returned | Date and time when the password was last changed. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| user.birth_date string Conditionally returned | Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd |
| user.birth_place string Conditionally returned | Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is US.The ISO maintains the full list of ISO-3166 country codes. |
| user.business_token string Conditionally returned | Unique identifier of the business resource. Allowable Values: Existing business resource token |
| user.city string Conditionally returned | City where the cardholder resides. Allowable Values: 40 char max |
| user.company string Conditionally returned | Company name. Allowable Values: 255 char max |
| user.corporate_card_holder boolean Conditionally returned | Specifies if the cardholder holds a corporate card. Allowable Values: true, false |
| user.country string Conditionally returned | Country where the cardholder resides. Allowable Values: 40 char max |
| user.created_time datetime Returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| user.email string Conditionally returned | Valid email address of the cardholder. Allowable Values: 1–255 chars |
| user.first_name string Conditionally returned | Cardholder’s first name. Allowable Values: 40 char max |
| user.gender string Conditionally returned | Gender of the cardholder. Allowable Values: F, M |
| user.honorific string Conditionally returned | Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
| user.id_card_expiration_date string Conditionally returned | Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd |
| user.id_card_number string Conditionally returned | Cardholder’s identification card number. Allowable Values: 255 char max |
| user.identifications array of objects Conditionally returned | One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more identifications objects |
| user.identifications[].expiration_date string Conditionally returned | Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
| user.identifications[].type string Conditionally returned | Type of identification. Allowable Values: SSN, TIN, SIN, NIN, PASSPORT_NUMBER, DRIVERS_LICENSE, BUSINESS_NUMBER, BUSINESS_TAX_ID, TAXPAYER_REFERENCE |
| user.identifications[].value string Conditionally returned | Number associated with the identification. Allowable Values: 255 char max |
| user.ip_address string Conditionally returned | Cardholder’s IP address. Allowable Values: 39 char max |
| user.last_modified_time datetime Returned | Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| user.last_name string Conditionally returned | Cardholder’s last name. Allowable Values: 40 char max |
| user.metadata object Conditionally returned | Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1" |
| user.middle_name string Conditionally returned | Cardholder’s middle name. Allowable Values: 40 char max |
| user.nationality string Conditionally returned | Cardholder’s nationality. Allowable Values: 255 char max |
| user.notes string Conditionally returned | Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
| user.parent_token string Conditionally returned | Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars |
| user.passport_expiration_date string Conditionally returned | Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
| user.passport_number string Conditionally returned | Cardholder’s passport number. Allowable Values: 40 char max |
| user.password string Conditionally returned | Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars |
| user.phone string Conditionally returned | Cardholder’s telephone number. Allowable Values: 255 char max |
| user.postal_code string Conditionally returned | Postal code of the cardholder’s address. Allowable Values: 10 char max |
| user.ssn string Conditionally returned | Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters. |
| user.state string Conditionally returned | State or province where the cardholder resides. Allowable Values: 2 char max |
| user.status string Conditionally returned | Specifies the status of the cardholder on the Marqeta platform. Allowable Values: UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED |
| user.title string Conditionally returned | Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max |
| user.token string Conditionally returned | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
| user.uses_parent_account boolean Conditionally returned | Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).Allowable Values: true, false |
| user.zip string Conditionally returned | United States ZIP code of the cardholder’s address. Allowable Values: 10 char max |
| wallet_provider_profile object Conditionally returned | Contains information held and provided by the digital wallet provider. Allowable Values: account, device_score, pan_source, reason_code, recommendation_reasons, risk_assessment |
| wallet_provider_profile.account object Conditionally returned | Contains information related to the cardholder and provided by the digital wallet provider. Allowable Values: email_address, id, score |
| wallet_provider_profile.account.email_address string Conditionally returned | Digital wallet provider’s email address for the cardholder. Allowable Values: 255 char max |
| wallet_provider_profile.account.id string Conditionally returned | Digital wallet provider’s identity number for the cardholder. Allowable Values: 20 char max |
| wallet_provider_profile.account.score string Conditionally returned | Score from the digital wallet provider. Allowable Values: 50 char max |
| wallet_provider_profile.device_score string Conditionally returned | Score from the device. Allowable Values: 50 char max |
| wallet_provider_profile.pan_source string Conditionally returned | Source from which the digital wallet provider obtained the card primary account number (PAN). Allowable Values: KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP |
| wallet_provider_profile.reason_code string Conditionally returned | Reason for the wallet provider’s provisioning decision. - 01 – Cardholder’s wallet account is too new relative to launch. - 02 – Cardholder’s wallet account is too new relative to provisioning request. - 03 – Cardholder’s wallet account/card pair is newer than date threshold. - 04 – Changes made to account data within the account threshold. - 05 – Suspicious transactions linked to this account. - 06 – Account has not had activity in the last year. - 07 – Suspended cards in the secure element. - 08 – Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B – The card provisioning attempt contains a distinct name in excess of the threshold. - 0C – The device score is less than 3. - 0D – The account score is less than 4. - 0E – Device provisioning location outside of the cardholder’s wallet account home country. - 0G – Suspect fraud. Allowable Values: 01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G |
| wallet_provider_profile.recommendation_reasons array of strings Conditionally returned | Array of recommendation reasons from the digital wallet provider. Allowable Values: Valid array of one or more recommendation reasons |
| wallet_provider_profile.risk_assessment object Conditionally returned | Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token. Allowable Values: score, version |
| wallet_provider_profile.risk_assessment.score string Conditionally returned | Wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN |
| wallet_provider_profile.risk_assessment.version string Conditionally returned | Wallet provider’s risk assessment version. Allowable Values: Version information, as provided by the wallet provider |
Sample response body
JSON
List digital wallet tokens for card
Action:GETEndpoint:
/digitalwallettokens/card/{card_token}
Use this endpoint to return an array of all digital wallet tokens for a particular card.
This endpoint supports pagination.
URL path parameters
| Fields | Description |
|---|---|
| card_token string Required | Unique identifier of the card. Used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Allowable Values: Existing card token |
URL query parameters
| Fields | Description |
|---|---|
| count integer Optional | Number of digital wallet token resources to retrieve. Allowable Values: Any integer Default value: 5 |
| start_index integer Optional | Sort order index of the first digital wallet token resource in the returned array. Allowable Values: Any integer Default value: 0 |
| sort_by string Optional | Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.Allowable Values: createdTime, lastModifiedTime, or any field in the resource modelDefault value: -createdTime |
Response body
| Fields | Description |
|---|---|
| count integer Conditionally returned | Number of resources returned. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
| data array of objects Conditionally returned | Array of digital wallet token resources. Resources are returned as appropriate to your query. Allowable Values: Valid array of one or more digital wallet token resources |
| data[].address_verification object Conditionally returned | Contains address verification information. Allowable Values: name, postal_code, street_address, zip |
| data[].address_verification.name string Conditionally returned | Name of the cardholder. Allowable Values: 40 char max |
| data[].address_verification.postal_code string Conditionally returned | Postal code. Allowable Values: 10 char max |
| data[].address_verification.street_address string Conditionally returned | Street address provided by the cardholder. Allowable Values: 40 char max |
| data[].address_verification.zip string Conditionally returned | United States ZIP code. Allowable Values: 10 char max |
| data[].card_token string Conditionally returned | Unique identifier of the card. Allowable Values: Existing card token |
| data[].created_time datetime Conditionally returned | Date and time when the digital wallet token object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].device object Conditionally returned | Contains information related to the device being provisioned. Allowable Values: device_id, ip_address, language_code, location, name, phone_number, token, type |
| data[].device.device_id string Conditionally returned | Identity number of the device. Allowable Values: 24 char max |
| data[].device.ip_address string Conditionally returned | Device’s IP address. Allowable Values: IP address format, 50 char max |
| data[].device.language_code string Conditionally returned | Language the device is configured to use. Allowable Values: 50 char max |
| data[].device.location string Conditionally returned | Geographic coordinates of the device. Allowable Values: Latitude and longitude in DDD.DD/DDD.DD format.NOTE: Both the longitude and latitude are prefixed with either a + or - symbol, for example: +42.29/-71.07. |
| data[].device.name string Conditionally returned | Name of the device. Allowable Values: 50 char max |
| data[].device.phone_number string Conditionally returned | Device’s telephone number. Allowable Values: 50 char max |
| data[].device.token string Conditionally returned | Unique identifier of the device object. Allowable Values: 36 char max |
| data[].device.type string Conditionally returned | Type of device being provisioned. Allowable Values: MOBILE_PHONE, WATCH, TABLET, MOBILE_PHONE_OR_TABLET, VEHICLE, APPLIANCE, LAPTOP, GAMING_DEVICE, WEARABLE_DEVICE, UNKNOWN |
| data[].fulfillment_status string Conditionally returned | Digital wallet token’s provisioning status. For fulfillment status descriptions, see Create digital wallet token transition. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED |
| data[].issuer_eligibility_decision string Conditionally returned | The Marqeta platform’s decision as to whether the digital wallet token should be provisioned. - 0000 – The token should be provisioned. - token.activation.verification.required – Provisioning is pending; further action is required for completion. For all other values, check the value of the fulfillment_status field to definitively ascertain the provisioning outcome.NOTE: The value invalid.cid indicates an invalid CVV2 number.Allowable Values: 0000, cardaccount.verified, card.suspicious, token.activation.verification.required, token.activation-request.decline, card.not.active, invalid.cid, card.expired, card.suspended, cardholder.not.active |
| data[].last_modified_time datetime Conditionally returned | Date and time when the digital wallet token object was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].metadata object Conditionally returned | Contains additional information about the digital wallet token. Allowable Values: cardproduct_preferred_notification_language, issuer_product_config_id |
| data[].metadata.cardproduct_preferred_notification_language string Conditionally returned | Language specified in the config.transaction_controls.notification_language field of the card product:- ces – Czech - deu – German - eng – English - fra – French - grc – Greek - ita – Italian - nld – Dutch - pol – Polish - por – Portuguese - rou – Romanian - spa – Spanish - swe – Swedish By default, notifications are sent in English. The ISO maintains the full list of ISO 3166 two- and three-digit numeric country codes. Allowable Values: ces, deu, eng, fra, grc, ita, nld, pol, por, rou, spa, swe |
| data[].metadata.issuer_product_config_id string Conditionally returned | Unique identifier of the product configuration on the Marqeta platform. Allowable Values: 255 char max |
| data[].state string Conditionally returned | State of the digital wallet token. For state descriptions, see Transitioning Token States. Allowable Values: REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED |
| data[].state_reason string Conditionally returned | Reason why the digital wallet token transitioned to its current state. Allowable Values: 255 char max |
| data[].token string Conditionally returned | Unique identifier of the digital wallet token. Allowable Values: Existing digital wallet token. |
| data[].token_service_provider object Conditionally returned | Contains information held and provided by the token service provider (card network). Allowable Values: correlation_id, pan_reference_id, token_assurance_level, token_eligibility_decision, token_expiration, token_pan, token_reference_id, token_requestor_id, token_requestor_name, token_score, token_type |
| data[].token_service_provider.correlation_id string Conditionally returned | For Mastercard only. Unique value representing a tokenization request. Allowable Values: Existing correlation identifier |
| data[].token_service_provider.pan_reference_id string Conditionally returned | Unique identifier of the digital wallet token primary account number (PAN) within the card network. Allowable Values: Existing PAN Reference ID |
| data[].token_service_provider.token_assurance_level string Conditionally returned | For Mastercard only. Represents the confidence level in the digital wallet token. Allowable Values: 0-99 |
| data[].token_service_provider.token_eligibility_decision string Conditionally returned | Digital wallet’s decision as to whether the digital wallet token should be provisioned. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN |
| data[].token_service_provider.token_expiration string Conditionally returned | Expiration date of the digital wallet token. Allowable Values: Format: MMyy |
| data[].token_service_provider.token_pan string Conditionally returned | Primary account number (PAN) of the digital wallet token. Allowable Values: 16 char max |
| data[].token_service_provider.token_reference_id string Conditionally returned | Unique identifier of the digital wallet token within the card network. Allowable Values: Existing Token Reference ID |
| data[].token_service_provider.token_requestor_id string Conditionally returned | Unique numerical identifier of the token requestor within the card network. These ID numbers map to token_requestor_name field values as follows:Mastercard - 50110030273 – APPLE_PAY- 50120834693 – ANDROID_PAY- 50139059239 – SAMSUNG_PAYVisa - 40010030273 – APPLE_PAY- 40010075001 – ANDROID_PAY- 40010043095 – SAMSUNG_PAY- 40010075196 – MICROSOFT_PAY- 40010075338 – VISA_CHECKOUT- 40010075449 – FACEBOOK- 40010075839 – NETFLIX- 40010077056 – FITBIT_PAY- 40010069887 – GARMIN_PAYAllowable Values: 11 char max Example Values: - Mastercard – 50110030273, 50120834693, 50139059239 - Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095 |
| data[].token_service_provider.token_requestor_name string Conditionally returned | Name of the token requestor within the card network. NOTE: The list of example values for this field is maintained by the card networks and is subject to change. Allowable Values: 255 char max Example Values: - Mastercard – APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY- Visa – APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY |
| data[].token_service_provider.token_score string Conditionally returned | Token score assigned by the digital wallet. Allowable Values: 25 char max |
| data[].token_service_provider.token_type string Conditionally returned | Type of the digital wallet token. Allowable Values: MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET |
| data[].transaction_device object Conditionally returned | Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution. Allowable Values: binding_id, ip_address, location, phone_number |
| data[].transaction_device.binding_id string Conditionally returned | Unique identifier of the data component bound to the credential. Allowable Values: 48 char max |
| data[].transaction_device.ip_address string Conditionally returned | IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction. Allowable Values: IP address format, 39 char max |
| data[].transaction_device.location string Conditionally returned | Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location. Allowable Values: Latitude and longitude in DDD.DD/DDD.DD format. |
| data[].transaction_device.phone_number string Conditionally returned | Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer. Allowable Values: 15 char max |
| data[].user object Conditionally returned | Contains information about a cardholder. Allowable Values: account_holder_group_token, active, address1, address2, authentication, birth_date, birth_place, business_token, city, company, corporate_card_holder, country, created_time, email, first_name, gender, honorific, id_card_expiration_date, id_card_number, identifications, ip_address, last_modified_time, last_name, metadata, middle_name, nationality, notes, parent_token, passport_expiration_date, passport_number, password, phone, postal_code, ssn, state, status, title, token, uses_parent_account, zip |
| data[].user.account_holder_group_token string Conditionally returned | Associates the specified account holder group with the cardholder. Allowable Values: 36 char max |
| data[].user.active boolean Conditionally returned | Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.Allowable Values: true, false |
| data[].user.address1 string Conditionally returned | Cardholder’s address. Allowable Values: 255 char max |
| data[].user.address2 string Conditionally returned | Additional address information for the cardholder. Allowable Values: 255 char max |
| data[].user.authentication object Conditionally returned | Contains the cardholder’s email address and password information. Allowable Values: email_verified, email_verified_time, last_password_update_channel, last_password_update_time |
| data[].user.authentication.email_verified boolean Conditionally returned | Specifies whether the email address has been verified. Allowable Values: true, false |
| data[].user.authentication.email_verified_time datetime Conditionally returned | Date and time when the email address was verified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].user.authentication.last_password_update_channel string Conditionally returned | Specifies the channel through which the password was last changed. Allowable Values: USER_CHANGE, USER_RESET |
| data[].user.authentication.last_password_update_time datetime Conditionally returned | Date and time when the password was last changed. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].user.birth_date string Conditionally returned | Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd |
| data[].user.birth_place string Conditionally returned | Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is US.The ISO maintains the full list of ISO-3166 country codes. |
| data[].user.business_token string Conditionally returned | Unique identifier of the business resource. Allowable Values: Existing business resource token |
| data[].user.city string Conditionally returned | City where the cardholder resides. Allowable Values: 40 char max |
| data[].user.company string Conditionally returned | Company name. Allowable Values: 255 char max |
| data[].user.corporate_card_holder boolean Conditionally returned | Specifies if the cardholder holds a corporate card. Allowable Values: true, false |
| data[].user.country string Conditionally returned | Country where the cardholder resides. Allowable Values: 40 char max |
| data[].user.created_time datetime Returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].user.email string Conditionally returned | Valid email address of the cardholder. Allowable Values: 1–255 chars |
| data[].user.first_name string Conditionally returned | Cardholder’s first name. Allowable Values: 40 char max |
| data[].user.gender string Conditionally returned | Gender of the cardholder. Allowable Values: F, M |
| data[].user.honorific string Conditionally returned | Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
| data[].user.id_card_expiration_date string Conditionally returned | Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd |
| data[].user.id_card_number string Conditionally returned | Cardholder’s identification card number. Allowable Values: 255 char max |
| data[].user.identifications array of objects Conditionally returned | One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more identifications objects |
| data[].user.identifications[].expiration_date string Conditionally returned | Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
| data[].user.identifications[].type string Conditionally returned | Type of identification. Allowable Values: SSN, TIN, SIN, NIN, PASSPORT_NUMBER, DRIVERS_LICENSE, BUSINESS_NUMBER, BUSINESS_TAX_ID, TAXPAYER_REFERENCE |
| data[].user.identifications[].value string Conditionally returned | Number associated with the identification. Allowable Values: 255 char max |
| data[].user.ip_address string Conditionally returned | Cardholder’s IP address. Allowable Values: 39 char max |
| data[].user.last_modified_time datetime Returned | Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].user.last_name string Conditionally returned | Cardholder’s last name. Allowable Values: 40 char max |
| data[].user.metadata object Conditionally returned | Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1" |
| data[].user.middle_name string Conditionally returned | Cardholder’s middle name. Allowable Values: 40 char max |
| data[].user.nationality string Conditionally returned | Cardholder’s nationality. Allowable Values: 255 char max |
| data[].user.notes string Conditionally returned | Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
| data[].user.parent_token string Conditionally returned | Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars |
| data[].user.passport_expiration_date string Conditionally returned | Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
| data[].user.passport_number string Conditionally returned | Cardholder’s passport number. Allowable Values: 40 char max |
| data[].user.password string Conditionally returned | Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars |
| data[].user.phone string Conditionally returned | Cardholder’s telephone number. Allowable Values: 255 char max |
| data[].user.postal_code string Conditionally returned | Postal code of the cardholder’s address. Allowable Values: 10 char max |
| data[].user.ssn string Conditionally returned | Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters. |
| data[].user.state string Conditionally returned | State or province where the cardholder resides. Allowable Values: 2 char max |
| data[].user.status string Conditionally returned | Specifies the status of the cardholder on the Marqeta platform. Allowable Values: UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED |
| data[].user.title string Conditionally returned | Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max |
| data[].user.token string Conditionally returned | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
| data[].user.uses_parent_account boolean Conditionally returned | Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).Allowable Values: true, false |
| data[].user.zip string Conditionally returned | United States ZIP code of the cardholder’s address. Allowable Values: 10 char max |
| data[].wallet_provider_profile object Conditionally returned | Contains information held and provided by the digital wallet provider. Allowable Values: account, device_score, pan_source, reason_code, recommendation_reasons, risk_assessment |
| data[].wallet_provider_profile.account object Conditionally returned | Contains information related to the cardholder and provided by the digital wallet provider. Allowable Values: email_address, id, score |
| data[].wallet_provider_profile.account.email_address string Conditionally returned | Digital wallet provider’s email address for the cardholder. Allowable Values: 255 char max |
| data[].wallet_provider_profile.account.id string Conditionally returned | Digital wallet provider’s identity number for the cardholder. Allowable Values: 20 char max |
| data[].wallet_provider_profile.account.score string Conditionally returned | Score from the digital wallet provider. Allowable Values: 50 char max |
| data[].wallet_provider_profile.device_score string Conditionally returned | Score from the device. Allowable Values: 50 char max |
| data[].wallet_provider_profile.pan_source string Conditionally returned | Source from which the digital wallet provider obtained the card primary account number (PAN). Allowable Values: KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP |
| data[].wallet_provider_profile.reason_code string Conditionally returned | Reason for the wallet provider’s provisioning decision. - 01 – Cardholder’s wallet account is too new relative to launch. - 02 – Cardholder’s wallet account is too new relative to provisioning request. - 03 – Cardholder’s wallet account/card pair is newer than date threshold. - 04 – Changes made to account data within the account threshold. - 05 – Suspicious transactions linked to this account. - 06 – Account has not had activity in the last year. - 07 – Suspended cards in the secure element. - 08 – Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B – The card provisioning attempt contains a distinct name in excess of the threshold. - 0C – The device score is less than 3. - 0D – The account score is less than 4. - 0E – Device provisioning location outside of the cardholder’s wallet account home country. - 0G – Suspect fraud. Allowable Values: 01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G |
| data[].wallet_provider_profile.recommendation_reasons array of strings Conditionally returned | Array of recommendation reasons from the digital wallet provider. Allowable Values: Valid array of one or more recommendation reasons |
| data[].wallet_provider_profile.risk_assessment object Conditionally returned | Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token. Allowable Values: score, version |
| data[].wallet_provider_profile.risk_assessment.score string Conditionally returned | Wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN |
| data[].wallet_provider_profile.risk_assessment.version string Conditionally returned | Wallet provider’s risk assessment version. Allowable Values: Version information, as provided by the wallet provider |
| end_index integer Conditionally returned | Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
| is_more boolean Conditionally returned | A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.This field is returned if there are resources in your returned array. Allowable Values: true, false |
| start_index integer Conditionally returned | Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
Sample response body
JSON
Retrieve digital wallet token PAN
Action:GETEndpoint:
/digitalwallettokens/{token}/showtokenpan
Use this endpoint to retrieve a digital wallet token with the entire primary account number (PAN) displayed. The PAN returned is of the digital wallet token and not of the card. (For security reasons, the PAN is not fully visible on the digital wallet token returned by GET /digitalwallettokens/{token}.)
Warning
Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.
Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the digital wallet token (DWT). Allowable Values: Existing DWT token |
Response body
| Fields | Description |
|---|---|
| address_verification object Conditionally returned | Contains address verification information. Allowable Values: name, postal_code, street_address, zip |
| address_verification.name string Conditionally returned | Name of the cardholder. Allowable Values: 40 char max |
| address_verification.postal_code string Conditionally returned | Postal code. Allowable Values: 10 char max |
| address_verification.street_address string Conditionally returned | Street address provided by the cardholder. Allowable Values: 40 char max |
| address_verification.zip string Conditionally returned | United States ZIP code. Allowable Values: 10 char max |
| card_token string Conditionally returned | Unique identifier of the card. Allowable Values: Existing card token |
| created_time datetime Conditionally returned | Date and time when the digital wallet token object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| device object Conditionally returned | Contains information related to the device being provisioned. Allowable Values: device_id, ip_address, language_code, location, name, phone_number, token, type |
| device.device_id string Conditionally returned | Identity number of the device. Allowable Values: 24 char max |
| device.ip_address string Conditionally returned | Device’s IP address. Allowable Values: IP address format, 50 char max |
| device.language_code string Conditionally returned | Language the device is configured to use. Allowable Values: 50 char max |
| device.location string Conditionally returned | Geographic coordinates of the device. Allowable Values: Latitude and longitude in DDD.DD/DDD.DD format.NOTE: Both the longitude and latitude are prefixed with either a + or - symbol, for example: +42.29/-71.07. |
| device.name string Conditionally returned | Name of the device. Allowable Values: 50 char max |
| device.phone_number string Conditionally returned | Device’s telephone number. Allowable Values: 50 char max |
| device.token string Conditionally returned | Unique identifier of the device object. Allowable Values: 36 char max |
| device.type string Conditionally returned | Type of device being provisioned. Allowable Values: MOBILE_PHONE, WATCH, TABLET, MOBILE_PHONE_OR_TABLET, VEHICLE, APPLIANCE, LAPTOP, GAMING_DEVICE, WEARABLE_DEVICE, UNKNOWN |
| fulfillment_status string Conditionally returned | Digital wallet token’s provisioning status. For fulfillment status descriptions, see Create digital wallet token transition. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED |
| issuer_eligibility_decision string Conditionally returned | The Marqeta platform’s decision as to whether the digital wallet token should be provisioned. - 0000 – The token should be provisioned. - token.activation.verification.required – Provisioning is pending; further action is required for completion. For all other values, check the value of the fulfillment_status field to definitively ascertain the provisioning outcome.NOTE: The value invalid.cid indicates an invalid CVV2 number.Allowable Values: 0000, cardaccount.verified, card.suspicious, token.activation.verification.required, token.activation-request.decline, card.not.active, invalid.cid, card.expired, card.suspended, cardholder.not.active |
| last_modified_time datetime Conditionally returned | Date and time when the digital wallet token object was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| metadata object Conditionally returned | Contains additional information about the digital wallet token. Allowable Values: cardproduct_preferred_notification_language, issuer_product_config_id |
| metadata.cardproduct_preferred_notification_language string Conditionally returned | Language specified in the config.transaction_controls.notification_language field of the card product:- ces – Czech - deu – German - eng – English - fra – French - grc – Greek - ita – Italian - nld – Dutch - pol – Polish - por – Portuguese - rou – Romanian - spa – Spanish - swe – Swedish By default, notifications are sent in English. The ISO maintains the full list of ISO 3166 two- and three-digit numeric country codes. Allowable Values: ces, deu, eng, fra, grc, ita, nld, pol, por, rou, spa, swe |
| metadata.issuer_product_config_id string Conditionally returned | Unique identifier of the product configuration on the Marqeta platform. Allowable Values: 255 char max |
| state string Conditionally returned | State of the digital wallet token. For state descriptions, see Transitioning Token States. Allowable Values: REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED |
| state_reason string Conditionally returned | Reason why the digital wallet token transitioned to its current state. Allowable Values: 255 char max |
| token string Conditionally returned | Unique identifier of the digital wallet token. Allowable Values: Existing digital wallet token. |
| token_service_provider object Conditionally returned | Contains information held and provided by the token service provider (card network). Allowable Values: correlation_id, pan_reference_id, token_assurance_level, token_eligibility_decision, token_expiration, token_pan, token_reference_id, token_requestor_id, token_requestor_name, token_score, token_type |
| token_service_provider.correlation_id string Conditionally returned | For Mastercard only. Unique value representing a tokenization request. Allowable Values: Existing correlation identifier |
| token_service_provider.pan_reference_id string Conditionally returned | Unique identifier of the digital wallet token primary account number (PAN) within the card network. Allowable Values: Existing PAN Reference ID |
| token_service_provider.token_assurance_level string Conditionally returned | For Mastercard only. Represents the confidence level in the digital wallet token. Allowable Values: 0-99 |
| token_service_provider.token_eligibility_decision string Conditionally returned | Digital wallet’s decision as to whether the digital wallet token should be provisioned. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN |
| token_service_provider.token_expiration string Conditionally returned | Expiration date of the digital wallet token. Allowable Values: Format: MMyy |
| token_service_provider.token_pan string Conditionally returned | Primary account number (PAN) of the digital wallet token. Allowable Values: 16 char max |
| token_service_provider.token_reference_id string Conditionally returned | Unique identifier of the digital wallet token within the card network. Allowable Values: Existing Token Reference ID |
| token_service_provider.token_requestor_id string Conditionally returned | Unique numerical identifier of the token requestor within the card network. These ID numbers map to token_requestor_name field values as follows:Mastercard - 50110030273 – APPLE_PAY- 50120834693 – ANDROID_PAY- 50139059239 – SAMSUNG_PAYVisa - 40010030273 – APPLE_PAY- 40010075001 – ANDROID_PAY- 40010043095 – SAMSUNG_PAY- 40010075196 – MICROSOFT_PAY- 40010075338 – VISA_CHECKOUT- 40010075449 – FACEBOOK- 40010075839 – NETFLIX- 40010077056 – FITBIT_PAY- 40010069887 – GARMIN_PAYAllowable Values: 11 char max Example Values: - Mastercard – 50110030273, 50120834693, 50139059239 - Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095 |
| token_service_provider.token_requestor_name string Conditionally returned | Name of the token requestor within the card network. NOTE: The list of example values for this field is maintained by the card networks and is subject to change. Allowable Values: 255 char max Example Values: - Mastercard – APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY- Visa – APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY |
| token_service_provider.token_score string Conditionally returned | Token score assigned by the digital wallet. Allowable Values: 25 char max |
| token_service_provider.token_type string Conditionally returned | Type of the digital wallet token. Allowable Values: MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET |
| transaction_device object Conditionally returned | Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution. Allowable Values: binding_id, ip_address, location, phone_number |
| transaction_device.binding_id string Conditionally returned | Unique identifier of the data component bound to the credential. Allowable Values: 48 char max |
| transaction_device.ip_address string Conditionally returned | IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction. Allowable Values: IP address format, 39 char max |
| transaction_device.location string Conditionally returned | Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location. Allowable Values: Latitude and longitude in DDD.DD/DDD.DD format. |
| transaction_device.phone_number string Conditionally returned | Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer. Allowable Values: 15 char max |
| user object Conditionally returned | Contains information about a cardholder. Allowable Values: account_holder_group_token, active, address1, address2, authentication, birth_date, birth_place, business_token, city, company, corporate_card_holder, country, created_time, email, first_name, gender, honorific, id_card_expiration_date, id_card_number, identifications, ip_address, last_modified_time, last_name, metadata, middle_name, nationality, notes, parent_token, passport_expiration_date, passport_number, password, phone, postal_code, ssn, state, status, title, token, uses_parent_account, zip |
| user.account_holder_group_token string Conditionally returned | Associates the specified account holder group with the cardholder. Allowable Values: 36 char max |
| user.active boolean Conditionally returned | Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.Allowable Values: true, false |
| user.address1 string Conditionally returned | Cardholder’s address. Allowable Values: 255 char max |
| user.address2 string Conditionally returned | Additional address information for the cardholder. Allowable Values: 255 char max |
| user.authentication object Conditionally returned | Contains the cardholder’s email address and password information. Allowable Values: email_verified, email_verified_time, last_password_update_channel, last_password_update_time |
| user.authentication.email_verified boolean Conditionally returned | Specifies whether the email address has been verified. Allowable Values: true, false |
| user.authentication.email_verified_time datetime Conditionally returned | Date and time when the email address was verified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| user.authentication.last_password_update_channel string Conditionally returned | Specifies the channel through which the password was last changed. Allowable Values: USER_CHANGE, USER_RESET |
| user.authentication.last_password_update_time datetime Conditionally returned | Date and time when the password was last changed. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| user.birth_date string Conditionally returned | Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd |
| user.birth_place string Conditionally returned | Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is US.The ISO maintains the full list of ISO-3166 country codes. |
| user.business_token string Conditionally returned | Unique identifier of the business resource. Allowable Values: Existing business resource token |
| user.city string Conditionally returned | City where the cardholder resides. Allowable Values: 40 char max |
| user.company string Conditionally returned | Company name. Allowable Values: 255 char max |
| user.corporate_card_holder boolean Conditionally returned | Specifies if the cardholder holds a corporate card. Allowable Values: true, false |
| user.country string Conditionally returned | Country where the cardholder resides. Allowable Values: 40 char max |
| user.created_time datetime Returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| user.email string Conditionally returned | Valid email address of the cardholder. Allowable Values: 1–255 chars |
| user.first_name string Conditionally returned | Cardholder’s first name. Allowable Values: 40 char max |
| user.gender string Conditionally returned | Gender of the cardholder. Allowable Values: F, M |
| user.honorific string Conditionally returned | Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
| user.id_card_expiration_date string Conditionally returned | Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd |
| user.id_card_number string Conditionally returned | Cardholder’s identification card number. Allowable Values: 255 char max |
| user.identifications array of objects Conditionally returned | One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more identifications objects |
| user.identifications[].expiration_date string Conditionally returned | Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
| user.identifications[].type string Conditionally returned | Type of identification. Allowable Values: SSN, TIN, SIN, NIN, PASSPORT_NUMBER, DRIVERS_LICENSE, BUSINESS_NUMBER, BUSINESS_TAX_ID, TAXPAYER_REFERENCE |
| user.identifications[].value string Conditionally returned | Number associated with the identification. Allowable Values: 255 char max |
| user.ip_address string Conditionally returned | Cardholder’s IP address. Allowable Values: 39 char max |
| user.last_modified_time datetime Returned | Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| user.last_name string Conditionally returned | Cardholder’s last name. Allowable Values: 40 char max |
| user.metadata object Conditionally returned | Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1" |
| user.middle_name string Conditionally returned | Cardholder’s middle name. Allowable Values: 40 char max |
| user.nationality string Conditionally returned | Cardholder’s nationality. Allowable Values: 255 char max |
| user.notes string Conditionally returned | Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
| user.parent_token string Conditionally returned | Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars |
| user.passport_expiration_date string Conditionally returned | Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
| user.passport_number string Conditionally returned | Cardholder’s passport number. Allowable Values: 40 char max |
| user.password string Conditionally returned | Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars |
| user.phone string Conditionally returned | Cardholder’s telephone number. Allowable Values: 255 char max |
| user.postal_code string Conditionally returned | Postal code of the cardholder’s address. Allowable Values: 10 char max |
| user.ssn string Conditionally returned | Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters. |
| user.state string Conditionally returned | State or province where the cardholder resides. Allowable Values: 2 char max |
| user.status string Conditionally returned | Specifies the status of the cardholder on the Marqeta platform. Allowable Values: UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED |
| user.title string Conditionally returned | Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max |
| user.token string Conditionally returned | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
| user.uses_parent_account boolean Conditionally returned | Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).Allowable Values: true, false |
| user.zip string Conditionally returned | United States ZIP code of the cardholder’s address. Allowable Values: 10 char max |
| wallet_provider_profile object Conditionally returned | Contains information held and provided by the digital wallet provider. Allowable Values: account, device_score, pan_source, reason_code, recommendation_reasons, risk_assessment |
| wallet_provider_profile.account object Conditionally returned | Contains information related to the cardholder and provided by the digital wallet provider. Allowable Values: email_address, id, score |
| wallet_provider_profile.account.email_address string Conditionally returned | Digital wallet provider’s email address for the cardholder. Allowable Values: 255 char max |
| wallet_provider_profile.account.id string Conditionally returned | Digital wallet provider’s identity number for the cardholder. Allowable Values: 20 char max |
| wallet_provider_profile.account.score string Conditionally returned | Score from the digital wallet provider. Allowable Values: 50 char max |
| wallet_provider_profile.device_score string Conditionally returned | Score from the device. Allowable Values: 50 char max |
| wallet_provider_profile.pan_source string Conditionally returned | Source from which the digital wallet provider obtained the card primary account number (PAN). Allowable Values: KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP |
| wallet_provider_profile.reason_code string Conditionally returned | Reason for the wallet provider’s provisioning decision. - 01 – Cardholder’s wallet account is too new relative to launch. - 02 – Cardholder’s wallet account is too new relative to provisioning request. - 03 – Cardholder’s wallet account/card pair is newer than date threshold. - 04 – Changes made to account data within the account threshold. - 05 – Suspicious transactions linked to this account. - 06 – Account has not had activity in the last year. - 07 – Suspended cards in the secure element. - 08 – Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B – The card provisioning attempt contains a distinct name in excess of the threshold. - 0C – The device score is less than 3. - 0D – The account score is less than 4. - 0E – Device provisioning location outside of the cardholder’s wallet account home country. - 0G – Suspect fraud. Allowable Values: 01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G |
| wallet_provider_profile.recommendation_reasons array of strings Conditionally returned | Array of recommendation reasons from the digital wallet provider. Allowable Values: Valid array of one or more recommendation reasons |
| wallet_provider_profile.risk_assessment object Conditionally returned | Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token. Allowable Values: score, version |
| wallet_provider_profile.risk_assessment.score string Conditionally returned | Wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN |
| wallet_provider_profile.risk_assessment.version string Conditionally returned | Wallet provider’s risk assessment version. Allowable Values: Version information, as provided by the wallet provider |
Sample response body
JSON
Create request for Apple Wallet web push provisioning
Action:POSTEndpoint:
/digitalwallets/wpp/applePayJWT
Use this endpoint to add a card to Apple Wallet via a web application.
Request body
| Fields | Description |
|---|---|
| card_token string Required | Unique identifier of the card resource. Allowable Values: Existing card token |
| 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 |
Response body
| Fields | Description |
|---|---|
| jws object Returned | Object containing JSON Web Signature (JWS) data. Allowable Values: Existing JWS object |
| jws.header object Returned | Contains header data for the JWS object. Allowable Values: Existing kid string |
| jws.header.kid string Returned | Unique identifier of the JSON Web Signature (JWS) public key of the key pair used to generate the signature. Allowable Values: Any value |
| jws.protected string Returned | Contains header parameters that are integrity-protected by the JSON Web Signature (JWS). Allowable Values: Any value |
| jws.payload string Returned | JSON Web Signature (JWS) message payload. Allowable Values: Any value |
| jws.signature string Returned | The JSON Web Signature (JWS). Allowable Values: Any value |
| state string Returned | Unique state associated with the digital wallet token. The Marqeta platform returns a universally unique identifier (UUID) in this field. Allowable Values: 255 char |
Create request for Google Wallet web push provisioning
Action:POSTEndpoint:
/digitalwallets/wpp/googlePayPushProvisioningNotification
Use this endpoint to add a card to Google Wallet via a web application.
This endpoint does not return a payload in response to a request. Instead, a successful call will return a response code only.
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 For example: ‘123d837e-958a-4e9f-bc97-4843ec948123’ |
Request body
| Fields | Description |
|---|---|
| card_setting integer Required | Indicates if the Funding Primary Account Number (FPAN) will be attempted. - 1 - FPAN save will be attempted. - 0 - FPAN save will not be attempted. Allowable Values: 0, 1 |
| card_token string Required | Unique identifier of the card resource. Allowable Values: Any value |
| client_session_id string Required | String provided by Google Wallet that identifies the client session. Allowable Values: Any value |
| integrator_id string Required | Google-assigned string that uniquely identifies both the integrator that is initiating the session and the issuer of the card. Allowable Values: Any value |
| public_device_id string Required | String provided by Google Wallet that identifies the Android device that will receive the digital wallet token. Allowable Values: Any value |
| public_wallet_id string Required | String provided by Google Wallet that identifies the device-scoped wallet that receives the digital wallet token. Allowable Values: Any value |
| server_session_id string Required | String provided by Google Wallet that identifies the backend session. Allowable Values: Any value |
| token_setting integer Required | Indicates if tokenization will be attempted. - 1 - Tokenization will be attempted. - 0 - Tokenization will not be attempted. Allowable Values: 0, 1 |
Check eligibility for Click to Pay for Mastercard
Action:GETEndpoint:
/digitalwallets/clicktopay/mastercard/checkeligibility
Use this endpoint to check if a provided BIN prefix is eligible for Click to Pay for Mastercard.
For more information about this ecommerce checkout solution, see Click to Pay.
URL query parameters
| Fields | Description |
|---|---|
| bin_prefix string Required | Prefix of the bank identification number. Allowable Values: A six- to nine-digit number NOTE: It is preferable to use eight- or nine-digit BIN prefixes in production environments. Contact your Marqeta representative for the appropriate value to use. |
| include_asset boolean Optional | Returns a list of image assets for the Click to Pay logo if set to true.Allowable Values: true, false |
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 |
Response body
| Fields | Description |
|---|---|
| is_eligible boolean Conditionally returned | Indicates whether the bin_prefix is eligible for Click to Pay.- true: The bin_prefix is eligible for Click to Pay.- false: The bin_prefix is not eligible for Click to Pay.Allowable Values: true, false |
| image_assets array of objects Conditionally returned | List of image assets for the Click to Pay logo if include_asset is set to true in the request.Allowable Values: A valid array of image_asset objects |
| image_assets[].type string Conditionally returned | Type of media. Specified as Multipurpose Internet Mail Extension (MIME). Supported media types include: - application/pdf - image/png - image/svg+xml - text/plain - text/html Allowable Values: 32 char max |
| image_assets[].data string Conditionally returned | Media data content. Allowable Values: Base64-encoded media data |
| image_assets[].height string Conditionally returned | Height of non-SVG image asset. Specified in pixels. Allowable Values: 6 char max |
| image_assets[].width string Conditionally returned | Width of non-SVG image asset. Specified in pixels. Allowable Values: 6 char max |
Sample response body
JSON
Enroll a card to Click to Pay for Mastercard
Action:POSTEndpoint:
/digitalwallets/clicktopay/mastercard/enroll
Use this endpoint to enroll a card in Click to Pay for Mastercard.
For more information about this ecommerce checkout solution, see Click to Pay.
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 |
Request body
| Fields | Description |
|---|---|
| card_token string Required | Unique identifier of the card resource. Allowable Values: 1–36 chars Existing card token |
| user_token string Required | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
| user_details array of objects Required | User’s email address and mobile phone number with country code. Allowable Values: A valid array of user_details objects |
| user_details[].email_address string Required | User’s email address. Allowable Values: 255 char max |
| user_details[].mobile_number object Required | User’s mobile phone number and country code. Allowable Values: country_code, phone_number |
| user_details[].mobile_number.country_code string Required | User’s mobile phone number country code only. Allowable Values: 255 char max |
| user_details[].mobile_number.phone_number string Required | User’s mobile phone number without country code. Allowable Values: 255 char max |
| locale_country string Required | The user-provided country code. The ISO 3166 country code is a two-letter country code that represents a country. For example, the numeric code for the United States is US.The ISO maintains the ISO-3166 country codes. Allowable Values: 2 chars |
| locale_language string Required | The user-provided language choice. The ISO 639-2 language code is a two-letter country code that represents a language. The ISO maintains the ISO 639-2 language codes. Allowable Values: 2 chars |
| callback_url string Optional | The URL to which the Click to Pay request status is sent via webhooks. Allowable Values: A valid URL |
| callback_authentication_type string Optional | The type of authentication required for the callback URL. - OAUTH_BEARER_TOKEN: OAuth bearer token for the callback URL.- BASIC_AUTH: Basic auth username and password for the callback URL.Allowable Values: OAUTH_BEARER_TOKEN, BASIC_AUTH |
| oauth_bearer_token string Optional | OAuth bearer token to access your callback URL if the callback_authentication_type is OAUTH_BEARER_TOKEN.Allowable Values: A bearer token that can be used to authenticate the callback API on the receiving end |
| callback_secret_for_signature string Optional | Randomly chosen string used for implementing HMAC-SHA1. HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your callback endpoint verify the message signature. For information about implementing this functionality, see Signature Verification. Allowable Values: 20–50 chars - Must contain at least one numeral - Must contain at least one lowercase letter - Must contain at least one uppercase letter - Must contain at least one of these symbols: @``#``$``%``!``^``&``*``(``)\\``_``+``~``-``=``[``]``\{``},``;``:``'``"``.``/``<``>``?` |
| basic_auth_username string Optional | Basic auth username to access your callback URL if authentication type is basic. If authentication type is basic, both username and password are required. Allowable Values: 1–50 chars |
| basic_auth_password string Optional | Basic auth password to access your callback URL if authentication type is basic. If authentication type is basic, both username and password are required. Allowable Values: 20–50 chars - Must contain at least one numeral - Must contain at least one lowercase letter - Must contain at least one uppercase letter - Must contain at least one of these symbols: @``#``$``%``!``^``&``*``(``)\\``_``+``~``-``=``[``]``\{``},``;``:``'``"``.``/``<``>``?` |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| token string Conditionally returned | Unique identifier of the Click to Pay request. Allowable Values: 1–36 chars |
Sample response body
JSON
Retrieve Click to Pay for Mastercard enrollment status
Action:GETEndpoint:
/digitalwallets/clicktopay/mastercard/status/{token}
Use this endpoint to return the status of a specific Click to Pay for Mastercard request.
For more information about this ecommerce checkout solution, see Click to Pay.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the Click to Pay request. Allowable Values: Existing Click to Pay request token |
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 |
Response body
| Fields | Description |
|---|---|
| token string Conditionally returned | Unique identifier of the Click to Pay request, used to track the status of the request. Allowable Values: 36 char max |
| status string Conditionally returned | The status of the Click to Pay request. - SUCCESS: The Click to Pay request was successful.- FAILED: The Click to Pay request failed.- RECEIVED: The Click to Pay request was received.Allowable Values: SUCCESS, FAILED, RECEIVED |
| token_reference_id string Conditionally returned | Unique identifier of the digital wallet token within the card network. Allowable Values: 255 char max |
Sample response body
JSON
Enroll a cardholder to Click to Pay for Visa
Action:POSTEndpoint:
/digitalwallets/clicktopay/visa/enroll
Use this endpoint to enroll a new cardholder in Click to Pay for Visa.
For more information about this ecommerce checkout solution, see Click to Pay.
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 |
| external-consumer-id-owner-bid string Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs. Allowable Values: 1-8 chars |
Request body
| Fields | Description |
|---|---|
| card object Required | Card information for Visa Click to Pay. Allowable Values: cardToken, nameOnCard |
| card.cardToken string Required | Unique identifier of the card. Allowable Values: 1–36 chars |
| card.nameOnCard string Required | Name of the cardholder that appears on the card. Allowable Values: 1–120 chars |
| card.billingAddress object Required | Billing address for Visa Click to Pay. Allowable Values: address1, city, state, country, postalCode |
| card.billingAddress.address1 string Optional | First line of the billing address. Allowable Values: 64 chars max |
| card.billingAddress.address2 string Optional | Optional second line of the billing address. Allowable Values: 64 chars max |
| card.billingAddress.city string Optional | City of the billing address. Allowable Values: 32 chars max |
| card.billingAddress.state string Optional | State of the billing address. Allowable Values: 3 chars max |
| card.billingAddress.country string Required | Country of the billing address. Allowable Values: 3 chars |
| card.billingAddress.postalCode string Optional | Postal code of the billing address. Allowable Values: 9 chars max |
| user object Required | User’s email address, mobile phone number without country code, first name, last name, locale, and country. Allowable Values: userToken, email, phone, firstName, lastName, locale, country |
| user.userToken string Required | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
| user.email string Required | User’s email address. Allowable Values: 255 char max |
| user.phone string Required | User’s mobile phone number according to ITU-T E.164 (2010) number structure. NOTE: In the E.164 format, the ”+” sign is not included. Allowable Values: 1–16 chars |
| user.firstName string Required | User’s first name. Allowable Values: 1–35 chars |
| user.lastName string Required | User’s last name. Allowable Values: 1–35 chars |
| user.locale string Required | The user-provided language choice. The ISO 639-2 language code is a two-letter country code that represents a language. The ISO maintains the ISO 639-2 language codes. Allowable Values: 2–5 chars |
| user.country string Required | ISO 3166-1 alpha-3 country code. Allowable Values: 3 chars |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| requestTraceId string Returned | Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars |
Sample response body
JSON
Enroll a card to Click to Pay for Visa
Action:POSTEndpoint:
/digitalwallets/clicktopay/visa/enrollcards
Use this endpoint to enroll a new card for an existing cardholder in Click to Pay for Visa.
For more information about this ecommerce checkout solution, see Click to Pay.
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 |
| external-consumer-id-owner-bid string Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs. Allowable Values: 1-8 chars |
Request body
| Fields | Description |
|---|---|
| card object Required | Card information for Visa Click to Pay. Allowable Values: cardToken, nameOnCard |
| card.cardToken string Required | Unique identifier of the card. Allowable Values: 1–36 chars |
| card.nameOnCard string Required | Name of the cardholder that appears on the card. Allowable Values: 1–120 chars |
| card.billingAddress object Required | Billing address for Visa Click to Pay. Allowable Values: address1, city, state, country, postalCode |
| userToken string Required | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| requestTraceId string Returned | Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars |
Sample response body
JSON
Retrieve user data for Click to Pay for Visa
Action:GETEndpoint:
/digitalwallets/clicktopay/visa/getdata/{user_token}
Use this endpoint to get user data for Click to Pay for Visa.
For more information about this ecommerce checkout solution, see Click to Pay.
URL path parameters
| Fields | Description |
|---|---|
| user_token string Required | Unique identifier of the cardholder. Allowable Values: Existing Visa Click To Pay User Token |
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 For example: ‘123d837e-958a-4e9f-bc97-4843ec948123’ |
| external-consumer-id-owner-bid string Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs. Allowable Values: 1-8 chars |
Response body
| Fields | Description |
|---|---|
| data array of objects Returned | Array of objects containing information of a Visa Click to Pay cardholder Allowable Values: Valid array of data objects |
| data[].intent object Returned | Intent of the Visa Click to Pay operation. Allowable Values: type, value |
| data[].consumerInformation object Returned | Object containing cardholder details for Visa Click to Pay operation. Allowable Values: externalConsumerID, firstName, middleName, lastName, phones, emails, locale, countryCode, state |
| data[].paymentInstruments array of objects Returned | Array of objects containing details of payment instruments for Visa Click to Pay. Allowable Values: type, accountNumber, nameOnCard, expirationDate, tokenDetails, paymentAccountReference, billingAddress, status |
Sample response body
JSON
Update cardholder information for Click to Pay for Visa
Action:PUTEndpoint:
/digitalwallets/clicktopay/visa/users
Use this endpoint to update cardholder information for Click to Pay for Visa.
For more information about this ecommerce checkout solution, see Click to Pay.
Header parameters
| 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 For example: ‘123d837e-958a-4e9f-bc97-4843ec948123’ |
| external-consumer-id-owner-bid string Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs. Allowable Values: 1-8 chars |
Request body
| Fields | Description |
|---|---|
| user object Required | User’s email address, mobile phone number without country code, first name, last name, locale, and country. Allowable Values: userToken, email, phone, firstName, lastName, locale, country |
| user.userToken string Required | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
| user.email string Required | User’s email address. Allowable Values: 255 char max |
| user.phone string Required | User’s mobile phone number according to ITU-T E.164 (2010) number structure. NOTE: In the E.164 format, the ”+” sign is not included. Allowable Values: 1–16 chars |
| user.firstName string Required | User’s first name. Allowable Values: 1–35 chars |
| user.lastName string Required | User’s last name. Allowable Values: 1–35 chars |
| user.locale string Required | The user-provided language choice. The ISO 639-2 language code is a two-letter country code that represents a language. The ISO maintains the ISO 639-2 language codes. Allowable Values: 2–5 chars |
| user.country string Required | ISO 3166-1 alpha-3 country code. Allowable Values: 3 chars |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| requestTraceId string Returned | Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars |
Sample response body
JSON
Delete cardholder information for Click to Pay for Visa
Action:DELETEEndpoint:
/digitalwallets/clicktopay/visa/users
Use this endpoint to delete cardholder information for Click to Pay for Visa.
For more information about this ecommerce checkout solution, see Click to Pay.
Header parameters
| 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 For example: ‘123d837e-958a-4e9f-bc97-4843ec948123’ |
| external-consumer-id-owner-bid string Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs. Allowable Values: 1-8 chars |
Request body
| Fields | Description |
|---|---|
| userToken string Required | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| requestTraceId string Returned | Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars |
Sample response body
JSON
Update card information for Click to Pay for Visa
Action:PUTEndpoint:
/digitalwallets/clicktopay/visa/cards
Use this endpoint to update card information for Click to Pay for Visa.
For more information about this ecommerce checkout solution, see Click to Pay.
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 For example: ‘123d837e-958a-4e9f-bc97-4843ec948123’ |
| external-consumer-id-owner-bid string Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs. Allowable Values: 1-8 chars |
Request body
| Fields | Description |
|---|---|
| card object Required | Card information for Visa Click to Pay. Allowable Values: cardToken, nameOnCard |
| card.cardToken string Required | Unique identifier of the card. Allowable Values: 1–36 chars |
| card.nameOnCard string Required | Name of the cardholder that appears on the card. Allowable Values: 1–120 chars |
| card.billingAddress object Required | Billing address for Visa Click to Pay. Allowable Values: address1, city, state, country, postalCode |
| userToken string Required | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| requestTraceId string Returned | Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars |
Sample response body
JSON
Delete card information for Click to Pay for Visa
Action:DELETEEndpoint:
/digitalwallets/clicktopay/visa/cards/{card_token}
Use this endpoint to delete card information for Click to Pay for Visa.
For more information about this ecommerce checkout solution, see Click to Pay.
URL path parameters
| Fields | Description |
|---|---|
| card_token string Required | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
Header parameters
| 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 For example: ‘123d837e-958a-4e9f-bc97-4843ec948123’ |
| external-consumer-id-owner-bid string Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs. Allowable Values: 1-8 chars |
Response body
| Fields | Description |
|---|---|
| requestTraceId string Returned | Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars |
Sample response body
JSON
Retrieve Click to Pay for Visa request status
Action:GETEndpoint:
/digitalwallets/clicktopay/visa/status/{requestTraceId}
Use this endpoint to return the status of a Click to Pay for Visa request.
For more information about this ecommerce checkout solution, see Click to Pay.
URL path parameters
| Fields | Description |
|---|---|
| requestTraceId string Required | Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars |
Header parameters
| 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 For example: ‘123d837e-958a-4e9f-bc97-4843ec948123’ |
| external-consumer-id-owner-bid string Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs. Allowable Values: 1-8 chars |
Response body
| Fields | Description |
|---|---|
| status string Returned | Status of the operation. Allowable Values: IN_PROGRESS, COMPLETED |
| consumerInformation object Conditionally returned | Consumer information. Allowable Values: Existing consumerInformation object |
| consumerInformation.externalConsumerID string Conditionally returned | External consumer ID. Allowable Values: 1–100 chars |
| consumerInformation.externalConsumerIDOwnerBID string Conditionally returned | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs. Allowable Values: 1–8 chars |
| details array of undefineds Conditionally returned | Additional status details of the operation. Allowable Values: Array of details object |
| details[].status string Returned | Status of the operation. Allowable Values: SUCCESS, FAILED |
| details[].intent object Returned | Intent of the Visa Click to Pay operation. Allowable Values: type, value |
| details[].errorDetails array of objects Returned | Details of error occurred while executing the operation. Allowable Values: field, reason, message |
Sample response body
JSON
Create a Visa Alias
Action:POSTEndpoint:
/digitalwallets/aliasdirectory/visa/aliases
Use this endpoint to create a Visa Alias.
Header parameters
| 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 For example: ‘123d837e-958a-4e9f-bc97-4843ec948123’ |
| participant-id string Required | Visa Business Identifier (BID) that is assigned to the program. Allowable Values: Existing participant ID For example, “123456789001” |
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 |
| paymentCredentials array of objects Required | Visa Alias payment credentials. Allowable Values: cardToken, billingAddress, nameOnCard, cardType, issuerName, currencyCode, preferredFor |
| paymentCredentials.cardToken string Required | Unique identifier of the card. Allowable Values: Existing card token |
| paymentCredentials.billingAddress object Required | Billing address associated with 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 char max |
| 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: 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 object Required | Contact information in the Alias Directory Service (ADS) profile. Allowable Values: type, value |
| 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 date Optional | Date of birth in the Alias Directory Service (ADS) profile. Allowable Values: 10 chars |
| profile.firstNameLocal string Optional | First name in the Alias Directory Service (ADS) profile, expressed in the user’s local language. 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. Allowable Values: 1–35 chars |
| profile.middleName string Optional | Middle name in the Alias Directory Service (ADS) profile. 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. Allowable Values: 1–35 chars |
| profile.preferredName string Optional | Preferred name in the Alias Directory Service (ADS) profile, as provided by the user. Allowable Values: 1–35 chars |
| identification object Optional | Identification of the user associated with the Visa Alias. Allowable Values: type, value, verificationDetails |
Sample request body
JSON
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 |
Sample response body
JSON
Retrieve Visa Alias by Visa Alias ID
Action:GETEndpoint:
/digitalwallets/aliasdirectory/visa/aliases/{aliasId}
Use this endpoint to retrieve a Visa Alias by its Visa Alias ID.
URL path parameters
| Fields | Description |
|---|---|
| aliasId string Required | Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID |
Header parameters
| 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 For example, “123456789001” |
Response body
| Fields | Description |
|---|---|
| aliasValue string Conditionally returned | 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 |
| profile object Conditionally 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.dateOfBirth date 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 |
| aliasType string Conditionally returned | 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. This field is returned if it exists in the resource. Allowable Values: EMAIL, PHONE, DIRECTORY_ALIASID, PAYNAME |
| consent object Conditionally returned | Visa Alias Directory Service (ADS) consent information. Allowable Values: presenter, validFromDateTime, version, expiryDateTime, intermediaries |
| consent.presenter string Returned | Presenter of the Visa Alias Directory Service (ADS) consent. Allowable Values: 1–120 chars |
| consent.validFromDateTime datetime Returned | 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 Returned | Version of the Visa ADS consent. Allowable Values: 1–9 chars |
| consent.expiryDateTime datetime Conditionally returned | 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 Conditionally returned | Intermediaries of the Visa ADS consent. Allowable Values: 1–120 chars |
| createdOn datetime Conditionally returned | Date and time when the Visa Alias was created. Allowable Values: 24 chars Format: YYYY-MM-DDThh:mm:ss.000Z |
| 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 |
| lastModifiedOn datetime Conditionally returned | Date and time when the Visa Alias was last modified. Allowable Values: 24 chars Format: YYYY-MM-DDThh:mm:ss.000Z |
| status string Conditionally returned | Status of the Visa Alias. Allowable Values: ACTIVE, DISABLED, BLOCKED, EXPIRED |
Sample response body
JSON
Update Visa Alias by Visa Alias ID
Action:PUTEndpoint:
/digitalwallets/aliasdirectory/visa/aliases/{aliasId}
Use this endpoint to update a Visa Alias by its Visa Alias ID.
URL path parameters
| Fields | Description |
|---|---|
| aliasId string Required | Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID |
Header parameters
| 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 For example, “123456789001” |
Request body
| Fields | Description |
|---|---|
| consent object Required | Visa Alias Directory Service (ADS) consent information. Allowable Values: presenter, validFromDateTime, version, expiryDateTime, intermediaries |
| profile object Required | Alias Directory Service (ADS) profile information. Allowable Values: - firstName- lastName- contactInfo- dateOfBirth- firstNameLocal- lastNameLocal- middleName- middleNameLocal- preferredName |
| identification object Optional | Identification of the user associated with the Visa Alias. Allowable Values: type, value, verificationDetails |
Sample request body
JSON
Delete Visa Alias by Visa Alias ID
Action:DELETEEndpoint:
/digitalwallets/aliasdirectory/visa/aliases/{aliasId}
Use this endpoint to delete a Visa Alias by Visa Alias ID.
URL path parameters
| Fields | Description |
|---|---|
| aliasId string Required | Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID |
Header parameters
| 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 For example, “123456789001” |
Retrieve alias internal ID
Action:POSTEndpoint:
/digitalwallets/aliasdirectory/visa/aliases/aliasId
Use this endpoint to retrieve the internal ID associated with a Visa Alias.
Header parameters
| 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 For example, “123456789001” |
Request body
| Fields | Description |
|---|---|
| aliasValue string Optional | 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 |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| id string Conditionally returned | UUID generated by Alias Directory, which identifies the Visa Alias. Allowable Values: 1–128 chars |
Sample response body
JSON
Update alias status
Action:PUTEndpoint:
/digitalwallets/aliasdirectory/visa/aliases/{aliasId}/status
Use this endpoint to update the status of a Visa Alias.
URL path parameters
| Fields | Description |
|---|---|
| aliasId string Required | Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID |
Header parameters
| 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 For example, “123456789001” |
Request body
| Fields | Description |
|---|---|
| status string Optional | Status of the Visa Alias. Allowable Values: ACTIVE, DISABLED |
Sample request body
JSON
Create Visa Alias payment credential
Action:POSTEndpoint:
/digitalwallets/aliasdirectory/visa/aliases/{aliasId}/cards
Use this endpoint to create a payment credential associated with a Visa Alias.
URL path parameters
| Fields | Description |
|---|---|
| aliasId string Required | Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID |
Header parameters
| 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 For example, “123456789001” |
Request body
| Fields | Description |
|---|---|
| cardToken string Required | Unique identifier of the card token. Allowable Values: 1–36 chars Existing card token |
| billingAddress object Required | Billing address for the payment credential. Allowable Values: country, addressLine1, addressLine2, buildingNumber, city, minorSubdivision, postalCode, state, streetName |
| nameOnCard string Required | Name on the card for the payment credential. Allowable Values: 1–120 chars |
| cardType string Required | Type of card for the payment credential. Allowable Values: 1–70 chars |
| issuerName string Required | Card issuer’s name for the payment credential. Allowable Values: 1–150 chars |
| 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) |
| preferredFor array of strings Optional | Indicates if a payment credential is a preferred Receiving, Sending, or Paying account. Allowable Values: RECEIVE, SEND, PAYING |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| id string Returned | UUID generated by Alias Directory, a utility used to identify the payment credential. Allowable Values: 36 char max |
| type string Returned | Indicates the type of payment credential. Allowable Values: CARD, BANK |
| externalId string Conditionally returned | External ID of the payment credential, which corresponds to Marqeta’s card token. Allowable Values: 1–100 chars |
Sample response body
JSON
Retrieve a Visa Alias payment credentials
Action:GETEndpoint:
/digitalwallets/aliasdirectory/visa/aliases/{aliasId}/cards
Use this endpoint to retrieve a list of payment credentials associated with a Visa Alias.
URL path parameters
| Fields | Description |
|---|---|
| aliasId string Required | Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID |
Header parameters
| 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 For example, “123456789001” |
Response body
| Fields | Description |
|---|---|
| GetPaymentCredentialsResponse array of objects Conditionally returned | Response containing the payment credentials associated with a 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 |
| GetPaymentCredentialsResponse[].accountNumber string Returned | Account number of the payment credential. Allowable Values: 12–19 chars |
| GetPaymentCredentialsResponse[].billingAddress object Returned | Billing address for the payment credential. Allowable Values: country, addressLine1, addressLine2, buildingNumber, city, minorSubdivision, postalCode, state, streetName |
| GetPaymentCredentialsResponse[].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 |
| GetPaymentCredentialsResponse[].billingAddress.addressLine1 string Conditionally returned | Address line 1 of the billing address associated with the payment credential. Allowable Values: 99 char max |
| GetPaymentCredentialsResponse[].billingAddress.addressLine2 string Conditionally returned | Address line 2 of the billing address associated with the payment credential. Allowable Values: 99 char max |
| GetPaymentCredentialsResponse[].billingAddress.buildingNumber string Conditionally returned | Building number of the billing address associated with the payment credential. Allowable Values: 1–60 chars |
| GetPaymentCredentialsResponse[].billingAddress.city string Conditionally returned | City of the billing address associated with the payment credential. Allowable Values: 1–35 chars |
| GetPaymentCredentialsResponse[].billingAddress.minorSubdivision string Conditionally returned | Minor subdivision of the billing address associated with the payment credential. Allowable Values: 1–50 chars |
| GetPaymentCredentialsResponse[].billingAddress.postalCode string Conditionally returned | Postal code of the billing address associated with the payment credential. Allowable Values: 1–16 chars |
| GetPaymentCredentialsResponse[].billingAddress.state string Conditionally returned | State of the billing address associated with the payment credential. Allowable Values: 1–16 chars |
| GetPaymentCredentialsResponse[].billingAddress.streetName string Conditionally returned | Street name of the billing address associated with the payment credential. Allowable Values: 1–60 chars |
| GetPaymentCredentialsResponse[].type string Returned | Type of payment credential associated with the Visa Alias. Allowable Values: CARD |
| GetPaymentCredentialsResponse[].accountNumberType string Conditionally returned | Type of account number associated with the payment credential. Allowable Values: PAN, NIUBIZ, TOKEN |
| GetPaymentCredentialsResponse[].cardType string Conditionally returned | Type of card associated with the payment credential. Allowable Values: 1–70 chars |
| GetPaymentCredentialsResponse[].createdOn datetime Conditionally returned | Date and time when the payment credential was created. Allowable Values: 24 chars Format: YYYY-MM-DDTHH:MM:SS.000Z |
| GetPaymentCredentialsResponse[].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) |
| GetPaymentCredentialsResponse[].expirationDate string Conditionally returned | Expiration date of the card. Allowable Values: 7 chars Format: YYYY-MM |
| GetPaymentCredentialsResponse[].externalId string Conditionally returned | External ID of the payment credential, which corresponds to Marqeta’s card token. Allowable Values: 1–100 chars |
| GetPaymentCredentialsResponse[].id string Conditionally returned | Unique identifier of the payment credential generated by Alias Directory. Allowable Values: 1–36 chars |
| GetPaymentCredentialsResponse[].issuerName string Conditionally returned | Name of the issuer of the payment credential. Allowable Values: 1–150 chars |
| GetPaymentCredentialsResponse[].lastFourDigits string Conditionally returned | Last four digits of the card number. Allowable Values: 4 chars |
| GetPaymentCredentialsResponse[].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 |
| GetPaymentCredentialsResponse[].nameOnCard string Conditionally returned | Name on the card associated with the payment credential. Allowable Values: 1–120 chars |
| GetPaymentCredentialsResponse[].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 |
| GetPaymentCredentialsResponse[].preferredFor[].type string Returned | Type of operation associated with the payment credential. Allowable Values: RECEIVE, SEND, PAY |
| GetPaymentCredentialsResponse[].preferredFor[].date date Conditionally returned | Date of the Receiving, Sending, or Paying operation. Allowable Values: 10 chars Format: YYYY-MM-DD |
| GetPaymentCredentialsResponse[].status string Conditionally returned | Status of the payment credential associated with the Visa Alias. Allowable Values: ACTIVE, BLOCKED, DISABLED, EXPIRED |
Sample response body
JSON
Retrieve payment credential
Action:GETEndpoint:
/digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId}
Use this endpoint to retrieve an existing payment credential.
URL path parameters
| Fields | Description |
|---|---|
| paymentCredentialId string Required | Unique identifier of an existing payment credential. Allowable Values: Existing payment credential ID |
Header parameters
| 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 For example, “123456789001” |
Response body
| Fields | Description |
|---|---|
| GetPaymentCredentialsResponse array of objects Conditionally returned | Response containing the payment credentials associated with a 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 |
| GetPaymentCredentialsResponse[].accountNumber string Returned | Account number of the payment credential. Allowable Values: 12–19 chars |
| GetPaymentCredentialsResponse[].billingAddress object Returned | Billing address for the payment credential. Allowable Values: country, addressLine1, addressLine2, buildingNumber, city, minorSubdivision, postalCode, state, streetName |
| GetPaymentCredentialsResponse[].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 |
| GetPaymentCredentialsResponse[].billingAddress.addressLine1 string Conditionally returned | Address line 1 of the billing address associated with the payment credential. Allowable Values: 99 char max |
| GetPaymentCredentialsResponse[].billingAddress.addressLine2 string Conditionally returned | Address line 2 of the billing address associated with the payment credential. Allowable Values: 99 char max |
| GetPaymentCredentialsResponse[].billingAddress.buildingNumber string Conditionally returned | Building number of the billing address associated with the payment credential. Allowable Values: 1–60 chars |
| GetPaymentCredentialsResponse[].billingAddress.city string Conditionally returned | City of the billing address associated with the payment credential. Allowable Values: 1–35 chars |
| GetPaymentCredentialsResponse[].billingAddress.minorSubdivision string Conditionally returned | Minor subdivision of the billing address associated with the payment credential. Allowable Values: 1–50 chars |
| GetPaymentCredentialsResponse[].billingAddress.postalCode string Conditionally returned | Postal code of the billing address associated with the payment credential. Allowable Values: 1–16 chars |
| GetPaymentCredentialsResponse[].billingAddress.state string Conditionally returned | State of the billing address associated with the payment credential. Allowable Values: 1–16 chars |
| GetPaymentCredentialsResponse[].billingAddress.streetName string Conditionally returned | Street name of the billing address associated with the payment credential. Allowable Values: 1–60 chars |
| GetPaymentCredentialsResponse[].type string Returned | Type of payment credential associated with the Visa Alias. Allowable Values: CARD |
| GetPaymentCredentialsResponse[].accountNumberType string Conditionally returned | Type of account number associated with the payment credential. Allowable Values: PAN, NIUBIZ, TOKEN |
| GetPaymentCredentialsResponse[].cardType string Conditionally returned | Type of card associated with the payment credential. Allowable Values: 1–70 chars |
| GetPaymentCredentialsResponse[].createdOn datetime Conditionally returned | Date and time when the payment credential was created. Allowable Values: 24 chars Format: YYYY-MM-DDTHH:MM:SS.000Z |
| GetPaymentCredentialsResponse[].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) |
| GetPaymentCredentialsResponse[].expirationDate string Conditionally returned | Expiration date of the card. Allowable Values: 7 chars Format: YYYY-MM |
| GetPaymentCredentialsResponse[].externalId string Conditionally returned | External ID of the payment credential, which corresponds to Marqeta’s card token. Allowable Values: 1–100 chars |
| GetPaymentCredentialsResponse[].id string Conditionally returned | Unique identifier of the payment credential generated by Alias Directory. Allowable Values: 1–36 chars |
| GetPaymentCredentialsResponse[].issuerName string Conditionally returned | Name of the issuer of the payment credential. Allowable Values: 1–150 chars |
| GetPaymentCredentialsResponse[].lastFourDigits string Conditionally returned | Last four digits of the card number. Allowable Values: 4 chars |
| GetPaymentCredentialsResponse[].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 |
| GetPaymentCredentialsResponse[].nameOnCard string Conditionally returned | Name on the card associated with the payment credential. Allowable Values: 1–120 chars |
| GetPaymentCredentialsResponse[].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 |
| GetPaymentCredentialsResponse[].preferredFor[].type string Returned | Type of operation associated with the payment credential. Allowable Values: RECEIVE, SEND, PAY |
| GetPaymentCredentialsResponse[].preferredFor[].date date Conditionally returned | Date of the Receiving, Sending, or Paying operation. Allowable Values: 10 chars Format: YYYY-MM-DD |
| GetPaymentCredentialsResponse[].status string Conditionally returned | Status of the payment credential associated with the Visa Alias. Allowable Values: ACTIVE, BLOCKED, DISABLED, EXPIRED |
Sample response body
JSON
Update payment credential
Action:PUTEndpoint:
/digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId}
Use this endpoint to update an existing payment credential.
URL path parameters
| Fields | Description |
|---|---|
| paymentCredentialId string Required | Unique identifier of an existing payment credential. Allowable Values: Existing payment credential ID |
Header parameters
| 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 For example, “123456789001” |
Request body
| Fields | Description |
|---|---|
| cardToken string Required | Unique identifier of the card token. Allowable Values: 1–36 chars Existing card token |
| billingAddress object Required | Billing address for the payment credential. Allowable Values: country, addressLine1, addressLine2, buildingNumber, city, minorSubdivision, postalCode, state, streetName |
| nameOnCard string Required | Name on the card for the payment credential. Allowable Values: 1–120 chars |
| cardType string Required | Type of card for the payment credential. Allowable Values: 1–70 chars |
| issuerName string Required | Card issuer’s name for the payment credential. Allowable Values: 1–150 chars |
| 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) |
| preferredFor array of strings Optional | Indicates if a payment credential is a preferred Receiving, Sending, or Paying account. Allowable Values: RECEIVE, SEND, PAYING |
Sample request body
JSON
Delete an existing payment credential
Action:DELETEEndpoint:
/digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId}
Use this endpoint to delete an existing payment credential.
URL path parameters
| Fields | Description |
|---|---|
| paymentCredentialId string Required | Unique identifier of an existing payment credential. Allowable Values: Existing payment credential ID |
Header parameters
| 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 For example, “123456789001” |
Create an additional Visa Alias
Action:POSTEndpoint:
/digitalwallets/aliasdirectory/visa/aliases/{aliasId}/additionalAlias
Use this endpoint to create additional Visa Aliases associated with an existing main Visa Alias.
URL path parameters
| Fields | Description |
|---|---|
| aliasId string Required | Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID |
Header parameters
| 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 For example, “123456789001” |
Request body
| Fields | Description |
|---|---|
| type string Required | Type of the additional Visa Alias. Allowable Values: EMAIL, PHONE |
| value string Required | Unique identifier that represents the customer in the payment ecosystem. Allowable Values: 1–128 chars |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| id string Returned | UUID generated by Alias Directory, which identifies the Visa Alias. Allowable Values: 1–36 chars |
Sample response body
JSON
Delete an additional Visa Alias
Action:DELETEEndpoint:
/digitalwallets/aliasdirectory/visa/additionalAliases/{additionalAliasId}
Use this endpoint to delete an additional Visa Alias by its Visa Alias ID.
URL path parameters
| Fields | Description |
|---|---|
| additionalAliasId string Required | Unique identifier of the additional Visa Aliases. Allowable Values: Existing additional Visa Alias ID |
Header parameters
| 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 For example, “123456789001” |
Retrieve Visa Alias by external ID
Action:POSTEndpoint:
/digitalwallets/aliasdirectory/visa/aliases/getByExternalId
Use this endpoint to retrieve a Visa Alias by its external ID.
Header parameters
| 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 For example, “123456789001” |
Request body
| Fields | Description |
|---|---|
| externalId string Required | External ID of the Visa Alias. Allowable Values: 1–100 chars |
| type 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. Allowable Values: ALIAS, PAYMENT_CREDENTIAL |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| associatedIds array of objects Returned | List of associated Visa Alias IDs. Allowable Values: associatedIds |
| associatedIds[].id string Conditionally returned | ID of the payment credential associated with the Visa Alias. Allowable Values: 1–64 chars |
| associatedIds[].type string Conditionally returned | Type of payment credential associated with the Visa Alias. Allowable Values: ALIAS, PAYMENT_CREDENTIAL |
| id string Conditionally returned | UUID generated by Alias Directory, which identifies the Visa Alias. Allowable Values: 1–36 chars |
Sample response body
JSON
Create a report request
Action:POSTEndpoint:
/digitalwallets/aliasdirectory/visa/reports
Use this endpoint to create a new report request.
Header parameters
| 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 For example, “123456789001” |
Request body
| Fields | Description |
|---|---|
| filters object Required | Filters for the report. Allowable Values: aliasStatuses, aliasType, billingEventTypes, endDate, startDate |
| format string Required | The format of the report Allowable Values: 1–36 chars |
| reportType string Required | Indicates the type of report. Allowable Values: DIRECTORY_STATUS, PLATFORM_REQUESTS, RESOLUTION_RECONCILIATION, DIRECTORY_ACTIVITY, PAYMENT_CREDENTIAL_DETAILS |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| reportId string Conditionally returned | Unique identifier of the report. Allowable Values: 36 char max |
Sample response body
JSON
Retrieve report status by report ID
Action:GETEndpoint:
/digitalwallets/aliasdirectory/visa/reports/{reportId}
Use this endpoint to retrieve the status of a report by its report ID.
URL path parameters
| Fields | Description |
|---|---|
| reportId string Required | Unique identifier of the report. Allowable Values: Existing report ID |
Header parameters
| 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 For example, “123456789001” |
Response body
| Fields | Description |
|---|---|
| creationDateTime datetime Conditionally returned | The timestamp when the report was created in ISO UTC format YYYY-MM-DDThh:mm:ss.000Z Allowable Values: YYYY-MM-DDThh:mm:ss.000Z |
| dataClassification string Conditionally returned | Data classification of the report. Allowable Values: 1–36 chars |
| expirationDateTime datetime Conditionally returned | The timestamp after which the report won’t be available for download in ISO UTC format YYYY-MM-DDThh:mm:ss.000Z Allowable Values: YYYY-MM-DDThh:mm:ss.000Z |
| fileIds array of strings Conditionally returned | UUIDs of the files generated by the report. Allowable Values: |
| format string Conditionally returned | Format of the report. Allowable Values: 1–36 chars |
| id string Conditionally returned | UUID generated by Alias Directory, which identifies the report. Allowable Values: 1–36 chars |
| reportType string Conditionally returned | Indicates the type of report. Allowable Values: PLATFORM_REQUESTS, DIRECTORY_STATUS, PAYMENT_CREDENTIAL_DETAILS |
| status string Conditionally returned | Indicates the status of the report. Allowable Values: CREATED, IN_PROGRESS, COMPLETED |
Sample response body
JSON
Retrieve file by file ID and report ID
Action:GETEndpoint:
/digitalwallets/aliasdirectory/visa/reports/{reportId}/file/{fileId}
Use this endpoint to retrieve a file by its file ID and report ID.
URL path parameters
| Fields | Description |
|---|---|
| reportId string Required | Unique identifier of the report. Allowable Values: Existing report ID |
| fileId string Required | Unique identifier of the file. Allowable Values: Existing file ID |
Header parameters
| 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 For example, “123456789001” |
Response body
| Fields | Description |
|---|---|
| programId string Conditionally returned | ID associated with the program. Allowable Values: 255 char max |
| statusCode integer Conditionally returned | Status code of the operation. Allowable Values: Any integer |
| operationType string Conditionally returned | Indicates the type of operation. Allowable Values: 255 char max |
| operationsCount integer Conditionally returned | Number of operations in the report. Allowable Values: Any integer |
| originatorActorId string Conditionally returned | Indicates the Originator Actor ID. Allowable Values: 255 char max |
Sample response body
JSON
Check for Visa Alias
Action:POSTEndpoint:
/digitalwallets/aliasdirectory/visa/aliases/inquiry
Use this endpoint to check for available Visa Aliases for alias resolution. One or more Visa Aliases may be available.
Header parameters
| Fields | Description |
|---|---|
| participant-id string Required | Visa Business Identifier (BID) that is assigned to the program. Allowable Values: Existing participant ID For example, “123456789001” |
| 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 |
|---|---|
| aliases array of strings Required | List of Visa Aliases to check for availability. Allowable Values: 1–128 chars |
| filters array of objects Optional | List of filters to apply in the request to check Visa Alias availability. Allowable Values: 1-3 items |
| transactionDetails object Optional | Details of the transaction associated with the Alias. Allowable Values: currencyCode |
| userDetails object Optional | Details of the user requesting the Visa Alias information. The information must not contain personal identifiable information (PII). Allowable Values: userName |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| summary object Required | Summary of available Visa Aliases Allowable Values: aliasesFound, aliasesNotFound, aliasesRepeated, aliasesTotal |
| summary.aliasesFound integer Required | Number of available Visa Aliases found. Allowable Values: 0-900 |
| summary.aliasesNotFound integer Required | Number of Visa Aliases not found. Allowable Values: 0-900 |
| summary.aliasesRepeated integer Required | Number of duplicate Visa Aliases. Allowable Values: 0-900 |
| summary.aliasesTotal integer Required | Total number of available Visa Aliases. Allowable Values: 0-900 |
| details array of objects Optional | Information associated with available Visa Aliases. Allowable Values: aliasType, aliasValue, directories, directoriesNames |
| details.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 |
| details.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 char |
| details.directories array of objects Required | List of directories associated with the Visa Alias. Allowable Values: directoryName, entities |
| details.directories.directoryName string Required | The directory name for the Visa Alias. Allowable Values: 25 char |
| details.directories.entities array of objects Required | List of entities associated with the directory. Allowable Values: id, preferredFor |
| details.directories.entities.preferredFor array of objects Conditionally returned | List of preferred payment methods for the entity. Allowable Values: 0-10 items |
| details.directories.entities.preferredFor.type string Returned | Type of operation associated with the payment credential. Allowable Values: RECEIVE, SEND, PAY |
| details.directories.entities.preferredFor.date date Conditionally returned | Date of the Receiving, Sending, or Paying operation. Allowable Values: 10 chars |
| details.directoriesNames array Required | List of directory names associated with the Visa Alias. Allowable Values: Array of 0-10 directory names |
Sample response body
JSON
Resolve a Visa Alias
Action:POSTEndpoint:
/digitalwallets/aliasdirectory/visa/aliases/resolve
Retrieve information about a Visa Alias and all the associated payment credentials.
Header parameters
| Fields | Description |
|---|---|
| participant-id string Required | Visa Business Identifier (BID) that is assigned to the program. Allowable Values: Existing participant ID For example, “123456789001” |
| 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: |
| transactionDetails object Optional | Details of the transaction associated with the Alias. Allowable Values: currencyCode |
| userDetails object Optional | Details of the user requesting the Visa Alias information. The information must not contain personal identifiable information (PII). Allowable Values: userName |
Sample request body
JSON
Response body
| Fields | Description |
|---|---|
| directoryName string Required | The directory name of the Visa Alias. Allowable Values: 1-128 chars |
| identification object Optional | 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 | 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 | 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 Required | List of payment credentials associated with the Visa Alias. Allowable Values: 1-10 items |
| 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 date 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 |
| profile object Required | Alias Directory Service (ADS) profile information. Allowable Values: firstName, lastName, contactInfo, dateOfBirth, firstNameLocal, lastNameLocal, middleName, middleNameLocal, preferredName |
| 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.firstName string Required | First name in the Alias Directory Service (ADS) profile. Allowable Values: 1–35 chars |
| profile.middleName string Optional | Middle name in the Alias Directory Service (ADS) profile. Allowable Values: 1–35 chars |
| profile.contactInfo object Required | Contact information in the Alias Directory Service (ADS) profile. Allowable Values: type, value |
| 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 date Optional | Date of birth in the Alias Directory Service (ADS) profile. Allowable Values: 10 chars |
| profile.lastNameLocal string Optional | Last name in the Alias Directory Service (ADS) profile, expressed in the user’s local language. Allowable Values: 1–35 chars |
| profile.preferredName string Optional | Preferred name in the Alias Directory Service (ADS) profile, as provided by the user. Allowable Values: 1–35 chars |
| profile.firstNameLocal string Optional | First name in the Alias Directory Service (ADS) profile, expressed in the user’s local language. 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. Allowable Values: 1–35 chars |
Sample response body
JSON