Overview
Merchants must provide migration files using the CCG templates. CCG will process these files asynchronously, creating customers and linking payment methods. Success and error extracts are provided upon completion.
Integration Details
Merchants initiate migration by uploading migration files (see templates below). CCG processes these files asynchronously, creating customers and payment methods. Success and error extracts are generated for reconciliation. Supported payment methods: Card and Bank Account.
Merchant Migration Processing Flow
This section describes the internal architecture and sequence for customer and payment method migration.
Notes:
- All jobs are tracked via status polling endpoints.
- Stripe/Card flows require additional reconciliation and extract steps.
- ACH/Bank flows use a separate reconciliation process.
API Request
Migration is initiated by uploading a migration file to the designated Azure Blob Storage location. No direct API call is made by the merchant; CCG triggers processing upon file receipt.
File Upload Example: Upload your migration file using ECG QuickConnect or your assigned SFTP endpoint. File naming conventions and credentials are provided by your CCG integration manager.
API Response
Upon successful processing, CCG generates two extract files:
- Success Extract: Contains all successfully migrated records with assigned CCG Payment Method IDs.
- Error Extract: Contains records that failed migration, with error descriptions.
You will be notified via your preferred channel (email, SFTP, or dashboard) when extracts are available.
Status Handling
Migration jobs are processed asynchronously. Status can be tracked via the CCG dashboard or by polling the status endpoint (if enabled for your integration).
Statuses:
- STAGING_COMPLETED
- CUSTOMER_CREATION_COMPLETED
- STRIPE_EXTRACT_COMPLETED (for Card)
- SETUP_PAYMENT_METHOD_COMPLETED (for Bank Account)
- COMPLETED (Reconciliation)
Error Handling
Refer to the Merchant Extract for error extract details. Common errors include:
- Invalid or missing required fields
- Duplicate customer or payment method
- File format errors
FAQ
Q: What file formats are supported? A: CSV files using the provided migration templates.
Q: How do I know if my migration succeeded? A: Check the Success and Error Extracts provided after processing.
Q: Can I retry failed records? A: Yes, correct the errors in your file and re-upload.
Integration Checklist
- Migration file uses the latest CCG template
- All required fields are populated
- File delivered via ECG QuickConnect/SFTP
- Merchant notified of extract availability
- Success and Error Extracts reviewed
Related Documentation
Migration File Format
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 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
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.