Merchant-Customer-Migration
Merchant Customer Migration
Introduction
Merchants can make use of CCG capabilities to facilitate Customer and Payment Method migrations. To initiate the migration process, the merchant will provide migration files, utilizing the CCG Migration templates. Once the files are shared, CCG will take charge of creating customers and linking payment methods, which will subsequently be available in CCG upon completion of the process.
Additionally, CCG will generate error and success extracts. The error extract will enable the merchant to identify any potential issues in the original file, while the success extract will provide the CCG Payment Method Ids that resulted from the migration process.
There are two types of migrations, depending on the Payment Method: Bank Account or Card.
Migration File:
The migration files contain essential information required for successful customer migration. Depending on the Payment Method type, the files contain optional and compulsory fields. Below, we will provide a description of each field.
- Card file: Customer Information + Card Information
- Bank Account file: Customer Information + Bank Account Information
Customer Information:
| field | type | Compulsory | description |
|---|---|---|---|
| customer[merchant_customer_key] | Map<String, String> | Merchant Customer Identifier. Multiple merchant customer identifiers can be provided. | |
| firstName | String | first name | |
| lastName | String | last name | |
| String | email address | ||
| ssnLastFour | Digits (4) | SSN last four digits, e.g 1234 | |
| phoneCountryCode | Digits (3) | Phone country code, e.g. 001 | |
| phoneNumber | Digits (20) | Phone number, e.g. 0123456789 | |
| dateOfBirth | Date (YYYY-MM-DD) | Date of Birth, e.g. 1975-11-14 | |
| zip5 | Digits (5) | ZIP Code, e.g. 10001 | |
| hsid | UUID | HealthSafe Identifier of the customer | |
| enterpriseId | String | Enterprise Identifier of the customer |
Card Information:
| field | type | Compulsory | description |
|---|---|---|---|
| vaultCardId | String | Merchant Payment Method Identifier | |
| nameOnCard | String | Name on card | |
| zipOnCard | Digits (5) | ZIP Code on card, e.g. 10001 | |
| cardLast4 | Digits (4) | Card number last four digits, e.g. 1234 | |
| expirationYear | Date (YYYY) | Expiration Year, e.g. 2032 | |
| expirationMonth | Date (MM) | Expiration Month, e.g. 12 | |
| cardNickName | String | Card nickname | |
| isDefault | Boolean | Default card flag | |
| isManufacturer | Boolean | Manufacturer card flag |
Sample Card Migration template:
card_test_migration_file_20240625-153549.csv
Bank Account Information:
| field | type | Compulsory | description |
|---|---|---|---|
| accountHolderType | individual/business | Type of account holder | |
| accountType | checking/savings | Type of account | |
| bankName | String | Name of the bank | |
| accountLast4 | Digits (4) | Last four digits of the bank account | |
| accountNumber | String | Account number | |
| routingNumber | String | Routing number | |
| nameOnAccount | String | Name on bank account | |
| accountNickName | String | Bank account nickname | |
| isDefault | Boolean | Default bank account flag |
Sample Bank Account Migration template:
bank_account_test_migration_file_20240701-095200.csv
Merchant Extract:
Merchant extracts will include migration results, encompassing any potential issues encountered during the migration process. These extracts can be categorized into two distinct types:
- Error Extract: This extract contains the original file with an additional column called errorDescription. It is used to capture any errors that occurred during the migration.
- Success Extract: This extract also includes the original file but with a new column called ccgPaymentMethodId. It is used to indicate a successful migration.
By utilizing these Merchant Extracts, merchants can effectively analyze and address any migration-related concerns, ensuring a smooth transition to CCG.
Error Extract:
Error Extract will contain any record that was not successfully processed. For instance, due to wrong formatting, invalid input fields or missing compulsory information. Description of the issue will be added at the end of each line.
Card example:
card_test_migration_file_20240625-153549_error_20240625.csv
Bank Account example:
bank_account_test_migration_file_20240701-095200_error_20240701.csv
Success Extract:
Success Extract will contain all records, those that were successfully migrated will also contain the CCG Payment Method Id at the end of the line.
Card example:
card_test_migration_file_20240625-153549_completed_20240625.csv
Bank Account example:
bank_account_test_migration_file_20240701-095200_completed_20240701.csv
File Delivery
ECG QuickConnect will be used for transferring migration files between Merchant and CCG.
Migration Performance
The Merchant Customer Migration process involves creating customer records followed by the creation of payment methods. The performance of this process can vary depending on the environment in which it is executed. Below, we provide rough estimates of the maximum number of records processed per second in a production environment:
- Customer Creation: up to 65 records per second
- Payment Method Creation: up to 30 records per second
As CCG handles the above processes asynchronously, it may take some time to receive event responses via webhooks for these requests.
Based on previous migrations, we have been able to process approximately 1 million records over a 24-hour period.