Skip to main content

Token Migration Guide

Exact Payments allows merchants to securely migrate their customer data including the corresponding primary account numbers (PANs) and banking details, from an incumbent provider to the Exact Payments Payfac-as-a-Service platform. Exact facilitates a secure and seamless migration for stored payment data between platforms without the need for customers to re-enter their payment information.

Steps involved in the migration process:​

Integrate with Exact’s Payfac-as-a-Service product and have an active account in Production. If intending to migrate banking information, Dwolla's Terms and Conditions must have been accepted.

Once the integration with Exact is complete, inform one of our Implementations representatives that a migration is required ([email protected]).

Send the incumbent payments provider a request to export the PAN data.

Inform Exact once the migration file has been uploaded to the SFTP portal.

Using the confirmation file that Exact generates, the customer will map the new cardholder values to their former values in its back-office database.

Integration to Exact​

When an account has been configured with Exact in the Production environment, an Implementations representative will provide the accountId. Both this value, and the file requirements below, must be shared with the incumbent provider when requesting the token data export.

Notify Exact of Planned Migration from the Incumbent Provider​

Email one of Exact's Implementations representatives, or initiate a request via the Portal.

Requesting a Token Migration the Incumbent Provider​

Reach out to the incumbent payments provider with the instructions on how to format the token migration file. It can take anywhere from several days to several weeks for the incumbent to provide Exact with the file—please plan accordingly.

File format and required fields​

Payment and customer information should be exported into a single CSV file containing one payment method per row. In cases where customers have more than one payment method, multiple lines must be used.

Exact highly recommends that a unique identifier is provided for each customer in the Customer ID column, so that the merchant can easily map the generated tokens to the original records.

Each row of the CSV file should contain the following 18 fields:

● = required, ◐ = optional, ▢ = leave empty

token-csv-example.png

CSV Migration File Format​

The CSV migration file that the encumbent will deliver contains the following columns:

  1. Primary Account Number (PAN)
  2. Expiration Date (month, year)
  3. Bank Account Number
  4. Bank Routing Number
  5. Bank Account Type (Checking or Savings)
  6. Cardholder / Bank Account Holder Name
  7. Business Name
  8. Email address
  9. Phone number
  10. Customer ID / Customer #
  11. Address Line 1
  12. Address Line 2
  13. City
  14. State
  15. Country
  16. Postal Code
  17. Label (ex. Business, Personal)
  18. isDefault

See an example file with test data, here.

Encryption of the File​

The CSV migration file must be encrypted and sent using Exact Payment's PGP key, in the article below this.

Upon completion of the migration process​

Once the payment token migration process is complete, Exact generates a CSV made up of the following nine columns. There is one row per payment method submitted (either successfully tokenized or not):

Customer Name: the customer name provided in the original file;

Payment Type: the type of payment method that was identified for this record. It should be one of “ach”, “card” or “unknown”;

Last 4: the last 4 digits of the card or account number provided in the original file;

Original Customer Id: the original Customer Id value provided for the given record. This should be used to map the newly generated tokens to original records provided by the incumbent provider;

Payment Token: the payment token generated during the migration process;

Customer Id: the id used to reference the customer record created in Exact;

Linked: this field indicates if the payment method was successfully linked to a customer record. It should be either “True” or “False”;

Status: the final status of each record. It should be either “migrated” or “failed”;

Error: this field contains detailed error descriptions for all records that were not successfully migrated. It will be blank otherwise.

The CSV file can be accessed via SFTP using the credentials provided and the following URL:​

sftp://sftp-ptm.exactpaydev.com/{username}/migrated-tokens.csv

Example of the Token Migration response file​

The example at this link contains migration file response example (the ninth column is missing as there were no errors during the migration)

Final Steps​

Remap customer records using the new values in the Exact Migration Response file.

FAQ Section:​

How long does the Token Migration process take?​

The Token Migration process typically occurs within 5 business days of the correctly formatted file being received from the incumbent payments provider.

What if the response file contains rows with errors?​

The import report will identify the number of records with errors. Exact will require the incumbent to fix these failed records and either submit an incremental, or entire file again. The system will not duplicate or recreate customers in these circumstances.