If you have credit cards already vaulted within another third party vault and would like to use them with Spreedly there are two migration options:

• One Time Imports
  If you’d like to do a mass one-time migration where we import credit card data into the Spreedly vault, see section on one-time imports. If your one-time import involves integrating with an existing Spreedly customer that is a payment platform review our merchant of a platform migration section below for some answers to commonly asked questions.
• Self Managed Gradual Migrations
  If you’d like to do a self-managed gradual migration using the API for one of our gateways that accept Third Party Vaulting, this guide is for you.

📘

Alternative payment methods have different technical restrictions that may make them ineligible for migrations between service providers. If you’re considering migrating alternative payment method tokens (Apple Pay, Google Pay, etc.) to the Spreedly vault, contact our support team to find out more.

One Time Imports

This guide describes how to import credit card data into your organization’s Spreedly environment. If you are integrating with an existing Spreedly customer that is a payment platform for this import, see our merchant of a platform migration guide.

Migration scenarios

Importing cards from an existing gateway account (common)

Steps to import cards to Spreedly:

1. Contact the existing third-party vault/gateway to request an export of the payment method data. Please also point them to our PCI compliance information. Here’s a good template to send to the gateway:

Hello [Gateway] Support, I’d like to export all of my payment methods to Spreedly’s Level-1 PCI compliant payment vault. You can find their latest compliance documentation here: https://spreedly.com/pci

When the export is ready, please send the export to [email protected] and reference my organization and merchant’s name. If you have any questions I’m happy to loop you in with Spreedly’s Support team and they will help move the process along. Here’s Spreedly’s public key, which you will use to encrypt the export.

2. Review the gateway’s export documentation prior to migration to confirm the following:

• The data will be a GPG-encrypted JSON or CSV file.
• The data is similar to our suggested data format.

3. Submit a request to Spreedly with the environment key where data will be imported.
4. Data transfer depends on the gateway’s process and how they respond to the export.

• If they prefer to setup the SFTP for the transfer, then they will need our PGP key to provide us credentials. (S/MIME encryption uses an RSA key of at least 2048 bits)
• If a Spreedly SFTP is requested, we’ll need you to provide us the public PGP key of the third-party vault/gateway. The Gateway’s PGP key will be used to encrypt credentials to a Spreedly-created SFTP server where they will drop the exported payment methods for us to retrieve. Ideally, this key would be hosted on a public page.

If necessary, we will work directly with the third-party vault to manage the import process. Spreedly customers are responsible for managing communication with their merchant(s).

Information about customer subscriptions (amount, dates, etc.) should be obtained directly from the exporting entity. Spreedly will not extract this data from an encrypted data file.

Customer Database Migration (less common)

When bringing cards from your own database follow the same steps listed in the gateway migration above. The data should be PGP encrypted and transferred securely.

If the import source is a merchant of the Spreedly customer, we would treat the merchant like any other 3rd party importing to us and work with them to move the data. Afterwards, they should continue to go to their provider (the Spreedly customer) for support.

Spreedly to Spreedly migrations

Moving from one Spreedly organization to another

The original payment methods will still be retained in the source environment and the payment method details will be copied onto a newly assigned token in the destination environment. We’ll provide a mapping file which includes the “old” Spreedly token and the corresponding “new” token.

In order to migrate payment methods from one Spreedly organization to another, we need the following information:

• Source Spreedly Organization
  • Confirmation of request to export payment methods
  • Environment key where the payment methods are currently stored
  • A list of Spreedly Payment Method tokens to be exported (CSV)
    
    
• Destination Spreedly Organization
  • Confirmation of request to import payment methods
  • Environment key where the payment methods are to be imported
    
    

Moving payment methods to a new environment within the same organization

The original payment methods will be selected from the source environment and moved to the destination environment. The payment method token identifier will remain the same.

In order to migrate payment methods from one Spreedly environment to another, we need the following information:

• Source Spreedly Environment
  • Environment key where the payment methods are currently stored
  • A list of Spreedly Payment Method tokens to be exported (CSV)
    
    
• Destination Spreedly Environment
  • Environment key where the payment methods are to be imported
    
    

Managing communications

It’s important to remember that you support your customer and we support you. While, for PCI reasons, we have to manage the actual transfer with your customer’s existing vault, it’s important to remember that they are still your customer. We need the initial request to come from you versus the merchant/end-user account. We need you to communicate the process to your customer and determine how you might want to handle any fees or other issues. We can never be sure what the current status of the customer’s account is with you so it’s important that you always lead.

Pricing

Spreedly will complete one import per merchant account, per third party vault. Should the merchant require any additional transfers from the same third party vault, a fee will apply. Please contact Support with any questions.

📘

Merchants should discuss a migration approach early. We recommend making sure new payment methods are being added to your Spreedly vault before requesting the import. This will help ensure you are fully migrated after one import, rather than having new cards added after the first import is complete, resulting in additional fees.

As part of our standard migration practice, in addition to payment account numbers and expiration dates, Spreedly will import any data provided by the gateway/third party vault that corresponds with non-sensitive payment method fields exposed by our API (excluding metadata). This includes the following:

• Name
• Billing Address
• Shipping Address
• Phone number
• Email
• Network Transaction IDs

Any additional data fields will be omitted by default. Any request to include additional data fields in the import will be considered a custom migration and may incur a fee.

Data format

Spreedly requires incoming data to be in CSV or JSON format. Any other data format, such as Microsoft Excel (.xlsx), may be assessed an additional fee.

The absolute minimum data required to import credit cards is an external ID and card number. However, we recommend the following information at a minimum. For data supplied as a CSV, the order in which the headers appear is flexible.

• External ID
• Full name
• Card number
• Expiration month
• Expiration year

You can include optional fields such as email, address1, address2, city, state, etc. For a full list of acceptable data types, see our API reference. Spreedly will omit additional data from an encrypted data file that falls outside of these standard payment method fields.

Please note that due to PCI regulations, Spreedly cannot import or store CVV.

If you are importing ACH payment methods, be sure to include all fields marked as required in our API reference:

• First name
• Last name
• Bank routing number
• Bank account number

Data should be GPG-encrypted and transferred securely, such as via SFTP.

📘

Spreedly will send a mapping file after the import has been completed. The external id provided in the encrypted migration file will be mapped to the Spreedly payment method token that has been newly created in our vault.

Data Validation

When communicating with Support, please provide the following information if possible to help prevent delays in processing:

• Name of the external identifier to use
• How many payment methods are expected to be included in the import (a ballpark figure is okay)
• Known gaps in data, i.e. that names or expiration dates will not be included

📘

We do not validate expiration dates when importing credit cards. Imported cards will be marked as eligible_for_card_updater by default, but your organization must be enabled for Advanced Vault and Lifecycle Management for cards to be updated.

Advance Vaulting

If you are enrolled in Advance Vault, we kindly request the following information to make sure that your new records also enjoy these benefits:

• Should these cards be set to Managed?
• Should these cards be eligible for Card Updater?
• Should we backfill your Network Tokens?

Timing

Spreedly generally processes imports within 2 weeks of receiving the required materials. In the case that an importer for the specific third-party vault/gateway has not yet been created, this timeline may be extended to account for the creation of the importer.

This process is a coordinated effort between you as the Spreedly customer, your merchant(s), and the third-party vault/gateway that is performing the export.

Results

Once we complete the import, we will then notify all parties and provide the Spreedly customer with a JSON file of the mappings. It will look like this:

> [  
>   {  
>     "external_id":"3397a8kI2ervRYgo2ExEhQc7r",  
>     "spreedly_token":"7I4Pe91tKQA1paBLd8Lm5YmYKcU",  
>     "fingerprint":"2cdbab63d3ff0dbde4a147db17361d05ed37"  
>   },  
>   {  
>     "external_id":"a127a9kI2eZvKYlo2CxBhQc7J",  
>     "spreedly_token":"ErHJlkd1GvJXOzYrEAIrDZwdv9r",  
>     "fingerprint":"669409b02e2c37f4720130bc81916dab88f1"  
>   }  
> ]

external_id is the unique ID of the payment method in the third party system we’re importing from, and spreedly_token is the token of the payment method in the Spreedly vault.

fingerprint is the fingerprint associated with the imported payment method (only applicable to credit cards).

Any non-sensitive data or that was imported on a payment method can be looked up with our APIs. Information about customer subscriptions (amount, dates, etc.) should be obtained directly from the exporting entity. Spreedly will not extract this data from an encrypted data file.

File Transfer

Spreedly accepts migration file transfer via SFTP with the following options:

• Spreedly will create an SFTP for one time use. Spreedly will require the PGP key from the third party sending the file to encrypt the credentials for the SFTP.
• The third party sending the import file prefers to create their own SFTP. If this is the case, it must be configured to the standard SFTP port (22). Credentials should be encrypted to Spreedly’s PGP public key. If the third party prefers for Spreedly to authenticate via SSH-RSA key instead of sending encrypted credentials, please use the key listed below.

Spreedly SSH-RSA Public Key

ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAABAQDKX5MrQBLsthC2qSMhwOut1VGWkkr5EqxLNkZmMwpkNKQTZDXS6zD/7W9nI9xeoSXovZhpbgdRxVZs1gWTW9e5uGA5FQffDm12cmnvtnzheSCak830C3c0dZskcJnybhMbOxdIJkN9GpliuKUUA/uQxj8m+E5GcyYNQEb21dKqKzj7UO3qnfF1KlAJJHx4aiyc7gDQJ4uulVbKATyxKqY525WffqZFAASTUoTiskU/i30iXZk8MC6EQQuxY+hsRGv4ugqt0W2PlVGKi1uOCgPjc7V3MU7HzOpBP60ppI4EH/4M154bKD6BnZGtQflSedhYNnwdQshF5mMehVzB7/bB

PGP

To migrate sensitive data to Spreedly, such as credit card information, it needs to be encrypted using our public key.

If you’re not familiar with PGP, visit GnuPG and start by importing a public key.

Spreedly Public Key

• Key ID: D60BA557
• Type: Public Key
• Length: 4096
• Algorithm: RSA
• Fingerprint: 5813 E64C 851F 114D 1ABC 2FA9 8EF9 8493 D60B A557
• User ID: Spreedly Support [[email protected]](mailto:[email protected])

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v2.0.14 (GNU/Linux)

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
ID0E/Ab9
=0eWU
-----END PGP PUBLIC KEY BLOCK-----

Merchant of a Platform Migration Guide

If you’re a merchant who is migrating payment data into Spreedly’s vault through a payment platform or marketplace, this short guide is for you. We’ve prepared a few questions you should ask your new platform before embarking on a migration. If you’re through the questions and ready to migrate check out our one-time import guide for step by step instructions, including a template to send to the gateway where your current payment methods reside, and encryption details.

📘

Please note, because of the legal agreements we have with our platform customers we cannot provide direct support to your merchant account. Instead, your payment platform should be prepared to manage the conversation with Spreedly throughout the entire migration process.

Common Merchant Questions

I’ve sent Spreedly my exported data file and they said it could take two weeks for the migration to complete. My previous gateway has closed my account. How do I keep receiving orders in the meantime?
a. We highly recommend your new platform gateway is set up for any new incoming orders, and you direct customer traffic there before requesting an export. This should prevent any customer payment methods (e.g., credit cards) from being missed in the migration.

b. If your new platform can’t start receiving orders before the migration finishes, ask your previous gateway if they can offer an extension so you can continue taking orders.

🚧

Be aware - If you find yourself facing scenario “b”, this most likely means you will have to request a second export once your new platform is ready. Spreedly performs one complimentary import per customer per gateway/source. Any additional imports will be assessed a fee. This cost may be passed on to you. Talk to your new platform about their migration costs.

Can I get my migration done earlier than two weeks?
We ask for approximately two weeks to complete a migration. Factor in at least 14 days to your migration plans.

How do I recover subscription information?
Information about customer subscriptions (amount, dates, etc.) should be obtained directly from the exporting entity. Spreedly will not extract this data from an encrypted data file.

I was just notified the migration is complete, what do I do now?
Your new platform knows what to do. We’ll send them a summary of the import, including credit card mapping files, and they’ll take it from there.

📘

If you have additional questions have your platform reach out to Spreedly support.