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.

📘

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.

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.

1. Call update_gratisat any time after tokenization to set managed to true

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
  }
}

2. Set the managed property to true when tokenizing via Direct API.

   JSON

   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
       }
     }
   }
   

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 truewill also update managed to true
• 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 Falsevia 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_updaterfrom true to false.

If desired, the card may be re-enrolled in Lifecycle Management by setting its eligible_for_card_updater flag back to truevia 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.