Credit Card Imports

Overview

What is an import?

A credit card import is a process managed by Recurly and your current payment provider to manage a secure transfer of credit card data, minimizing a merchant’s scope of PCI-compliance that might otherwise be incurred by handling the data themselves. Because of the strict regulations around credit card data storage, most providers will only migrate data between two PCI compliant vendors.

This process involves collecting the credit card data from the existing payment provider, and importing into Recurly. The end result is a series of accounts with stored billing information, allowing the merchant to then proceed with adding subscriptions or other details to the account.

Two sources of data:

Card numbers (typically provided by gateway):

• Typically will include all credit cards ever processed by the gateway, including expired cards and cards that have no active subscription
• Needs to be encrypted
• Sent directly from Recurly to your payment provider
• Has a reference number that is matched to your account info

Account and billing info (provided by the merchant)

• Map following our supported file format (see example file)

How long will I be down?

• For new signups, no downtime
• For account modifications, minimal - contact support to learn how to keep to a 3-day timeframe.

Pricing

Credit card imports are managed by Recurly for a professional services fee. Please contact your sales representative for a quote.

Technical Information

Encryption

All data related to a credit card migration should be encrypted using industry standards. Recurly’s PGP key can be found here. For security reasons, please note that Recurly cannot accept any data that is not encrypted.

File Format

Recurly prefers the credit card data to be provided in a column-separated document with a header line identifying each column. If alternate arrangements need to be made, this must be approved by Recurly. UTF-8 encoding preferred.

Contact Information

Your technical coordinator for all imports is Rachel Quick, Senior Director of Customer Support. For ease of communication, please use support@recurly.com for all import-related discussions

Data Storage

Credit card data will only be stored for short time periods in an encrypted format. Recurly will delete the records once the import is complete.

Test Imports (billing information)

Recurly manages imports from providers like Authorize.net, Stripe, Braintree and Zuora on a frequent basis. A test import of data should not be required unless working with a different payment processor.

Test Imports (subscription information)

Merchants should test the process of importing their subscriptions to validate their scripts. These tests can be done on a sandbox site using test gateway credentials and card numbers. Recurly strongly encourages this test before moving into production mode import of data.

Account Code Mapping

One of the most critical pieces of the credit card import is account code mapping. This is necessary since the only identifying information Recurly will receive from your gateway provider is their internal UUID. If you wish for accounts to be created inside of Recurly with a specific account code, please supply Recurly with a two-column CSV - one column identifying the payment provider’s UUID, the other column your ID, to be used as the Recurly account code. Please note that once created, a Recurly account code cannot be modified.

Timeline

Key Dates

• DX Prep Work - as early as possible.
• D0 File delivery
• D0 File validation
• D1-3 Import
• D3+ Post-Import - pause all billing in current provider, start duplicating information inside of Recurly.

Details of each step

Prep Work (gateway into, account mapping, merchant checklist)

This includes:

• Approximate number of card records to receive (used for validation purposes)
• Account code mapping
• Approximate date of import
• Even if dates are still flexible, please start communicating with Recurly Support as soon as possible so time may be reserved.

File delivery (PGP key, security, data validation)

• Must be received by 12pm Pacific Time to be considered d1. Otherwise the import will occur the next business day.
• Will not run on weekends or nights under normal circumstances.

File validation

• Recurly will run a quick “sanity” check on data provided to make sure file formatting is workable, and will notify the merchant if there are issues.

Import (account creation, billing info, skip-auth)

• When Recurly has confirmed the data validation, the merchant’s account will be charged for the import, and work will begin when payment clears.
• Due to the sensitivity of this information, Recurly works with our senior and executive engineering teams to review code, QA, and deploy and work done around raw credit card data.

Post-Import (Sub, Coupon, Credit Create)

• Once completed, Recurly will notify the merchant with a final result of the import including any errors. The merchant may now begin post import work on the accounts.

Reproducing Billing Behavior

Turn off emails - why and when

• Customer Impact: Customers being imported into Recurly may be confused by the “New Subscription” emails that are normally sent by our platform. This is why Recurly recommends creating all subscriptions to start at once using the trial period parameter, rather than future start date subscriptions (which would then prevent legitimate new subscribers from receiving their emails).
• Merchant Impact: none.
• Work to Do: Disable “new subscription” email template during the short window in which subscriptions are being created. Re-enable when done.

Aligning Original Bill Cycle Date

• Customer Impact: During a transition between billing providers, customers want to remain informed, and want no overall impact to their billing. One of the major areas is in their bill cycle date, so work should be done by the merchant to ensure their bill date remains the same across providers.
• Merchant Impact: During a transition between billing providers, merchants should maintain the bill cycle date to help with revenue recognition while allowing changes to immediately take place in the new platform. Creating subscriptions in a “trial” period allows them to activate immediately without recognizing any revenue since that was already processed in another platform. Customizing the trial end date also means a customer’s original bill cycle date will be respected.
• Work to Do: Merchant will create a subscription on the account using the Subscription Create API call and customizing the trial_ends_at date to match the customer’s original bill cycle date.

Addresses Pending Account Adjustments

• Customer Impact: Customers who have pending credits or charges in a legacy system will want those adjustments replicated on their Recurly site.
• Merchant Impact: n/a
• Work to Do: Merchant will use the Create an Adjustment API call to apply adjustments to an account.

Replicating Cancellations

• Customer Impact: A customer may have a canceled subscription, but it is still active through the end of their current bill cycle.
• Merchant Impact: Merchant needs to replicate a subscription on the account.
• Work to Do: Merchant will add a subscription per the instructions in “Aligning Original Bill Cycle Date”. Once the subscription has been added with a custom bill cycle end date, the merchant then issues a subscription cancellation call. This will terminate the customer’s subscription at the end of their bill cycle.

Replicating Subscription Changes

• Customer Impact: A customer may have a pending subscription in the legacy system set to take effect at the end of their current bill cycle.
• Merchant Impact: Merchant needs to replicate this change on the customer’s account.
• Work to Do: Merchant should add a subscription per the instructions in “Aligning Original Bill Cycle Date”. Once the subscription has been added with a custom bill cycle end date, the merchant should then issue a subscription change API call with a timeframe of “at renewal”. The customer’s new terms will apply once the subscription renews.

Custom Pricing Terms

• Customer Impact: A customer may have custom or grandfathered pricing that needs to be recognized in Recurly.
• Merchant Impact: Merchant needs to account for custom pricing without creating a burden on reporting.
• Work to Do: When a merchant creates a subscription per the instructions in “Aligning Original Bill Cycle Date”, they can supply a custom unit_amount_in_cents variable that will override pricing for that user. Alternatively, if the merchant wants to track contra-revenue, they can create and redeem before adding the subscription to the account at default pricing.

Customers who want to update billing info during migration

• Customer Impact: After legacy payment processor has exported data, a customer may want to update billing information.
• Merchant Impact: Merchant will not want the customer to update in their legacy platform since Recurly will not receive that data.
• Work to Do: The merchant should send the user to Recurly to update billing information, which will also create the account for the user. Recurly will not override any data in their system.

Customers who want to change subscription during migration

• Merchant Impact: Merchant should allow subscription changes until the final pull of data for creating subscriptions in Recurly. At that point, merchant should put up a system maintenance window, until the customer can then update the subscription in Recurly.
• Work to Do: n/a

Customer who want to cancel subscription during migration

• Merchant Impact: Merchant should allow subscription cancellations up until the final pull of data for creating subscription in Recurly. At that point, merchant should put up a system maintenance window, until the customer can then cancel the subscription within Recurly.
• Work to Do: n/a

Best Practices

Historical data

For auditing and technical reasons, Recurly cannot import historical data or backdate subscriptions. A CRM can be used to merge data from multiple systems for a full accounting profile.

Account Code Mapping

• Show table of common unique IDs from known vendors (e.g. Stripe, Braintree, Authorize.net, Zuora).
• Recurly will only import credit card data with an associated account code record, provided in the merchant mapping file. This is because many gateways have old, expired, or duplicate card records so Recurly will only import what we are specifically pointed towards importing.

Account billing level data

• Since this process only manages sensitive billing information, only billing level data (e.g. card number, expiration date, card name, card address) will be populated. All other, less sensitive data, can be populated using the Recurly API without worry of PCI scope.

Timing and cutovers

• Recurly strongly encourages a graduated import experience - start funneling new subscribers into Recurly while your legacy customers renew in your legacy platform - rather than a quick cutover.

Testing

• After moving into production mode, all data is kept for historical auditing and accounting purposes, and Recurly fees are applicable. Recurly recommends keeping production test transactions to a minimum, and maintaining a second sandbox site for ongoing testing.