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.
- 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, 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 |
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.
Organization Enabled (default:false) | Environment Enabled (default:false) | Payment Method managed state (default:true) | Payment Method Enrollment Status |
---|---|---|---|
No | Yes or No | True/False | Not Enrolled - The organization is not enabled, and the state of any Environments or Payment Methods are ignored. |
Yes | No | True/False | Not Enrolled - While the Organization is enabled, the environment is not, therefore the payment method is considered as not enrolled. |
Yes | Yes | True | Enrolled - All states of Organization, Environment and managed are true, therefore this payment method will be considered enrolled. |
Yes | Yes | False | Not Enrolled - The managed property at the payment method level is false , therefore this payment method is not enrolled |
Enrolling your organizations and environments
Your Organization will be enabled by you via UI in the your Spreedly account once your Spreedly account representative has allowed you for enablement. Once this step is complete 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.
Step 1, Enable Your Organization:
Step 2: Enable your Environment(s):
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 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.
- Call
update_gratis
at any time after tokenization to setmanaged
totrue
PUT /v1/payment_methods/56wyNnSmuA6CWYP7w0MiYCVIbW6/update_gratis.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"payment_method": {
"managed": true
}
}
-
Set the
managed
property totrue
when tokenizing via Direct API.POST /v1/payment_methods.<format> HTTPS/1.1 Host: core.spreedly.com Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Content-Type: application/<format> { "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": "[email protected]", "managed": true, "metadata": { "key": "string value", "another_key": 123, "final_key": true } } }
-
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
: Ifmanaged:
andeligible_for_card_updater
arefalse
, then updatingeligible_for_card_updater
totrue
will also updatemanaged
totrue
- Network Tokenization: If
managed
isfalse
, when requesting and successfully provisioning a network token for a payment method will automatically update managed totrue
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.
PUT /v1/payment_methods/56wyNnSmuA6CWYP7w0MiYCVIbW6/update_gratis.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"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.
Bin Metadata: If a card is removed from Advanced Vault, then BIN Metadata will no longer be present in any future API call responses is which BIN Metadata is provided. Because metadata is fetched in real time on all responses, it will no longer be available if you use show
to display the details of a past transaction even if it was displayed in the response when the original transaction took place.
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
.
Updated 5 months ago
Review the specific feature guides for understanding how to utilize the features under Advanced Vault.