# Advanced Vault Advanced Vault is the evolution of our vault and lifecycle services to a managed vault that combines core vaulting, lifecycle functionality, and data enrichment of payment methods with rules and best practices. Under Advanced Vault, Spreedly will offer and continue to invest in best in practice technologies which will be extended to our customers under a single product. Services include: - Lifecycle management solutions for vaulted payment methods that include coverage for Visa, Mastercard, and Discover brands. Real time Mastercard updates will be enabled or same-day notifications (push) when updates occur with the network. Visa JIT offers real time pull updates via the `inquiry`API. - Network Tokenization for eligible payment methods to improve security and authorization rates. - Configurable settings for Spreedly, and in future states by the customer, to adjust the rules and configurations in tailoring their vault with minimal effort. - Fluid enrollment of credentials on/off Lifecycle Management lists. Stale credentials that were regularly costing customers an β€œevent” fee without an actual update will be actively identified and unenrolled from Account Updater lists. - Data Enrichment - Enriching Payment Methods with BIN Metadata and Payment Account Reference (future) for advanced decision making, fraud prevention and customer loyalty tracking. ## Advanced Vault Onboarding The first step of onboarding to Advanced Vault is to complete the [Advanced Vault Onboarding Form](https://developer.spreedly.com/docs/advanced-vault-feature-onboarding-form), as certain features under Advanced Vault require Spreedly to gather information to register you and enable you. Completing this form triggers the registration and enablement with Spreedly Support. | Feature | Registration | Enablement Time | | :--------------------------------------------- | :----------- | :------------------------------------------------ | | Batch Lifecycle Management(VISA, MC, DISCOVER) | Not Required | Available for use immediately after AV enrollment | | Mastercard Real Time Updater | Required | ~3 Weeks | | Visa Just In Time | Required | ~3 Weeks | | Mastercard Network Tokenization | Required | ~1-2 Weeks | | Visa Network Tokenization | Required | ~1-2 Weeks | | BIN Metadata | Not Required | Available for use immediately after AV enrollment | > πŸ“˜ It is not required to have purchased Advanced Vault to initiate the registration process. If you are getting ready to sign up for the service, you can submit the registration form prior to that decision, however, you will need to have your production environment(s) created for Spreedly to fully complete enablement. ## Advanced Vault enrollment To gain access to the features of Advanced Vault, a payment method must be enrolled in the Advanced Vault service. A payment method is only enrolled when the Organization _and_ Environment it resides in are enabled, and the payment method itself is enabled(`managed:true`) for Advanced Vault. [block:parameters] { "data": { "h-0": "Organization Enabled \n_(default:false)_", "h-1": "Environment Enabled _(default:false)_", "h-2": "Payment Method `managed`state _(default:true)_", "h-3": "Payment Method Enrollment Status", "0-0": "No", "0-1": "Yes or No", "0-2": "True/False", "0-3": "Not Enrolled - The organization is not enabled, and the state of any Environments or Payment Methods are ignored.", "1-0": "Yes", "1-1": "No", "1-2": "True/False", "1-3": "Not Enrolled - While the Organization is enabled, the environment is not, therefore the payment method is considered as not enrolled.", "2-0": "Yes", "2-1": "Yes", "2-2": "True", "2-3": "Enrolled - All states of Organization, Environment and `managed`are true, therefore this payment method will be considered enrolled.", "3-0": "Yes", "3-1": "Yes", "3-2": "False", "3-3": "Not Enrolled - The `managed`property at the payment method level is `false`, therefore this payment method is not enrolled" }, "cols": 4, "rows": 4, "align": [ "left", "left", "left", "left" ] } [/block] > πŸ“˜ It should also be noted that the enrollment matrix holds true specifically for `retained` payment methods. If a payment method is redacted, it will not be considered enrolled in the service. ### Enrolling your organizations and environments Once your Spreedly account representative has allowed you for enablement, you will in turn be able to enable AV both on Organization and Environment levels in your Spreedly UI. Once your Organization has been enabled, you may then select which Environments under your Organization you choose to enable. All of your environments will be defaulted to `false`, and can be enabled either via the Spreedly UI or via API. > πŸ‘ Managing Advanced Vault at the environment level allows Merchants to scale and selectively enable/disable AV for different areas of their organization, or for Merchant Aggregators to offer AV on a per merchant basis. For more information on sub-feature management for Merchant Aggregators, see this guide **[here](https://developer.spreedly.com/docs/advanced-vault-for-merchant-aggregators)**. Step 1, Enable Your Organization under Organization Settings: [block:image] { "images": [ { "image": [ "https://files.readme.io/5bf93c46d828fbdbf8288646627b9a6224892ff928f5488b848a4c6410d2173a-Screenshot_2025-09-01_at_2.53.38_PM.png", "", "" ], "align": "center", "sizing": "200px" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/bc3ef58bfff09c13b888810eb5401edfb9c756458d1212e2ceaa085351bb0a84-Screenshot_2025-08-14_at_12.00.47_PM.png", "", "" ], "align": "center" } ] } [/block] Step 2: Enable your Environment(s) via the Vault Tab: [block:image] { "images": [ { "image": [ "https://files.readme.io/9d52ce6adb67c7453f5089c0708855d26b7a5ce4537fabfeb1e7be9f182b078a-Screenshot_2025-09-01_at_2.57.04_PM.png", "", "" ], "align": "center", "sizing": "200px" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/9d95d991edb44f806e03273f08ba9d7a3d54a9c7588e0d1162dca831160e3bf7-Screenshot_2025-08-14_at_12.02.03_PM.png", "", "" ], "align": "center" } ] } [/block] ## Enrolling/Unenrolling payment methods You can optionally exclude individual cards from Advanced Vault via our API. For example, you may want to exclude a card if your customer is not longer active but you would like to retain their Payment Method for reactivation. ### Updating after Tokenization using Update_Gratis While functionally similar to the update API, the [update_gratis](https://developer.spreedly.com/reference/update-gratis-payment-method) API endpoint allows customers to modify only Advanced Vaulting specific payment method parameters(`managed` , `eligible_for_account_updater`) while not incurring a billable API call. This API endpoint is accessible only when the Organization is enrolled in Advanced Vault. ### Enrolling new payment methods Spreedly allows customers to choose a default state of payment methods `managed` property to be either `true` or `false` for a given environment. This configuration is set to default `true` unless it has been specifically requested to be set to `false`. This can be helpful if you prefer an opt in path for AV as opposed to an opt out path. > πŸ“˜ Please reach out to your account contact to modify a different configuration of the default value on new payment methods. **If your environment default** is configured to `true` and you would like to have a new payment method enrolled in the service, then no additional actions are required as the default state will automatically enroll the payment method. **If your environment default** is configured to `false` , then enrolling a new payment method in Advanced Vault can be done several ways. 1. Call `update_gratis`at any time after tokenization to set `managed` to `true` ```json PUT /v1/payment_methods/56wyNnSmuA6CWYP7w0MiYCVIbW6/update_gratis. HTTPS/1.1 Host: core.spreedly.com Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Content-Type: application/ { "payment_method": { "managed": true } } ``` 2. Set the `managed` property to `true` when tokenizing via Direct API. ```json POST /v1/payment_methods. HTTPS/1.1 Host: core.spreedly.com Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Content-Type: application/ { "payment_method": { "credit_card": { "first_name": "Joe", "last_name": "Jones", "number": "5555555555554444", "verification_value": "423", "month": "3", "year": "2029", "company": "Acme Inc.", "address1": "33 Lane Road", "address2": "Apartment 4", "city": "Wanaque", "state": "NJ", "zip": "31331", "country": "US", "phone_number": "919.331.3313", "shipping_address1": "33 Lane Road", "shipping_address2": "Apartment 4", "shipping_city": "Wanaque", "shipping_state": "NJ", "shipping_zip": "31331", "shipping_country": "US", "shipping_phone_number": "919.331.3313" }, "email": "joey@example.com", "managed": true, "metadata": { "key": "string value", "another_key": 123, "final_key": true } } } ``` 3. Use feature automations, outlined below, to enroll a payment method in Advanced Vault. ### Feature Automations If the `managed` property on payment method is `false`, then certain actions of enrolling those payment methods in AV subfeatures will automatically enroll the payment method in Advanced Vault, as AV enrollment is by rule required to access those subfeatures. - `eligible_for_card_updater`: If `managed:` and `eligible_for_card_updater` are `false` , then updating `eligible_for_card_updater` to `true`will also update `managed` to `true` - When using Visa Just in Time if a card is not managed at the PM level and an inquiry is requested, the request is not rejected, but the payment method will be changed to`managed:true`automatically and proceed. - Network Tokenization: If `managed` is `false`, when requesting and successfully provisioning a network token for a payment method will automatically update managed to `true` > πŸ“˜ Enrolling a Payment Method in Advanced Vault is a first step of the process, but does not automatically enroll it in all features for Advanced Vault. See specific feature guides for any applicable enablement steps. ### Unenrolling Payment Methods To unenroll a payment method, you will update the state of a payment methods `managed` property from `True` to `False`via the `update_gratis` endpoint or `update` endpoint. ```json PUT /v1/payment_methods/56wyNnSmuA6CWYP7w0MiYCVIbW6/update_gratis. HTTPS/1.1 Host: core.spreedly.com Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Content-Type: application/ { "payment_method": { "managed": false } } ``` ### Unenrolling a Payment Method from AV and sub-feature ramifications Network Tokenization: If you choose to unenroll a payment method from Advanced Vault, and that payment method has a provisioned network token, we will not remove the provisioned network token. However, requests to use the network token while the payment method is unenrolled will result in a fall back to PAN. Reactivating the card for NT will only require a re-enrollment in AV, not a re-enrollment and re-provisioning. Lifecycle Management: If you unenroll a payment method from Advanced Vault that is currently enrolled in LCM, then we will no longer attempt to update that payment method until it is re-enrolled in Advanced Vault. Unenrolling from Advanced Vault, however, will not modify the existing `eligible_for_card_updater` value. ### Contact Card Holder Management In our experience, cards that receive a an update result of `ContactCardHolder` rarely see a `ReplacePaymentMethod` update after repeated attempts. When they continue to be sent, customers incur unnecessary costs as the card continues to receive billable updates for `ContactCardHolder`. Given this, when a payment method is enrolled in Advanced Vault and receives two consecutive `ContactCardHolder` responses from the Lifecycle Management service, it will automatically be excluded from future updates by automatically updating `eligible_for_card_updater`from `true` to `false`. If desired, the card may be re-enrolled in Lifecycle Management by setting its `eligible_for_card_updater` flag back to `true`via `update_gratis`. If there two more consecutive `ContactCardHolder` results, then the AU un-enrollment automation will activate again. > πŸ“˜ Automation to unenroll a payment method from Lifecycle Management _does not_ unenroll a payment method from Advanced Vault, and will continue to have access to BIN MetaData and Network tokenization. To unenroll the card from Advanced Vault follow the same unenrollment steps outlined above using `update_gratis`.