Migrating information about COF purchases and payment card tokens

General information

In some instances, it may be relevant for the merchant to process payments via ecommpay by using the payment details previously saved in the services of other acquirers. For such situations, ecommpay offers the capability of migrating and using the information about COF purchases (both regular and unscheduled) and payment card tokens.

While ecommpay charges no fees for such migration, certain fees may be charged by the acquirer providing the target information. Besides, migration is only possible if the acquirer supports such a capability and if other conditions are met (described further). If you have any questions about the organisation of data migration to ecommpay from other acquirers or in reverse, contact the ecommpay account manager.

After all the necessary information has been migrated to the ecommpay payment platform and its correctness has been confirmed by the merchant, the target COF purchases and tokens can be used for making various actions supported in the platform: performing series of debits within COF purchases (details), managing these debits (details), processing purchases and payouts with the help of tokens (details), performing payment cards verification (details), and so on. Along with that, all information about payments processed by using the migrated details can be obtained via the Dashboard interface (in the Payments section, with the information about all payments, and the Subscriptions section, with the information about regular purchases), the Data API, and the Gate API.

Note: Note that for performing any actions with the use of the migrated information, it is required to use new identifiers registered in the ecommpay payment platform:

card tokens specified in the token parameter
identifiers of payments specified in the payment_id parameter
identifiers of series of debits specified in the id parameter of the recurring object

These identifiers are included in the verification file sent to the merchant's specialists to confirm the correctness of the migrated information and can only be used with the identifier of the project (project_id), to which they are initially assigned.

Conditions and limitations

When using the capability of information migration, the merchant should consider the conditions and limitations from both the acquirer providing the information and ecommpay receiving the information. ecommpay applies the following restrictions:

The information migration is only available for the following card networks: American Express, Mastercard, and Visa.
For working with cards of other card networks, the generation of tokens and registration of COF purchases should be carried out directly in the platform, with the use of the corresponding options supported.
The information can only be migrated directly from other acquirers.
When working via third parties, the merchant should discuss with them whether it is possible to interact directly with the acquirers.
The information migration is only possible within the production projects in the ecommpay payment platform.
If not yet an ecommpay client, the merchant should submit an application to connect and proceed with the onboarding process.
The merchant is responsible for keeping the migrated information up-to-date and correct.
After the migration, a verification file is sent to the merchant's specialists. If they confirm the correctness of the information in this file, the information is considered valid and the responsibility for any consequences (for example, the occurrence of a chargeback due to an erroneous withdrawal of funds from a customer) is placed on the merchant.
The merchant is responsible for double debits.
Prior to the information migration, the ecommpay specialists and the merchant's specialists agree on the date for payment processing with the use of the migrated information to start. In order to avoid double debits (via the two acquirers), the merchant should ensure that the processing of payments via the other acquirer will be terminated by the agreed date.

Migration workflow

The migration of the information is carried out through an encrypted communication channel and usually takes a maximum of one week for tokens and a maximum of two weeks for COF purchases. The timelines depend on various factors and can vary if it is required to set up additional parameters, they also can be discussed by the involved parties.

The information about COF purchases and tokens is migrated through an encrypted communication channel established between ecommpay and the acquirer that provides the information. Migration timelines usually make up a maximum of one week for tokens and a maximum of two weeks for COF purchases. These timelines depend on various factors and can vary if it is required to set up additional parameters, they also can be discussed by the involved parties. If migration of the token information is completed and necessary for payment processing prior to the migration of the COF purchases information, its early usage can be arranged with the ecommpay specialists.

To have the information migrated, the merchant should:

Agree with the other acquirer on the migration availability and conditions.
Inform the ecommpay account manager that information migration is needed and agree on the migration timelines and the date to start payment processing.
If you are not an ecommpay client, submit an application to connect and proceed with the onboarding process.
Agree with the ecommpay specialists on the following:
- The projects that require information migration.
  If it is necessary to migrate information for several projects in the platform, the migration is carried out for each project individually.
- The set of parameters that should be migrated to the ecommpay platform.
  The set can include either only basic parameters described further and required for use or, if relevant, the basic parameters alongside additional ones supported in the platform.
- If you need to migrate information about COF purchases—the identifiers that should be assigned to these purchases (as the values for the parameter scheduled_payment_id) and the series of debits within these purchases (as the values for the parameter register_payment_id).
  These values can be in the format used by default (ecommpay–yyyymmddnnn) or in the formats specified by the merchant (with regards to the 255-character limit).
- The set of parameters that should be used by the merchant's specialists to verify that the target information has been migrated to the platform correctly and can be used for payment processing.
  This set must include the new identifiers (token and recurring_id), particular parameters from the basic set that are marked as ‘required for verification’ and, if relevant, can include additional parameters from the migrated ones.
- The email addresses of the specialists accountable for migration on the side of the merchant and on the side of the acquirer, from which the information should be obtained—for organising the interaction and addressing arising questions, including questions related to the information correctness.
Upon the receipt of a verification file sent to the provided email address, check whether the information in the file is complete and correct.
Note: The verification file contains all parameters that were previously agreed on and is sent in the CSV format, with the password to access the file provided separately. Besides, if decided on step 2, separate verification files for tokens and COF purchases can be created and provided.
Send an email to the ecommpay specialists either confirming information correctness or reporting inconsistencies.
If the information in the file is correct, the merchant can start using the migrated information after the confirmation. If inconsistencies or mistakes have been detected, the ecommpay specialists compare the details in the file with those received from the third-party acquirer and, depending on the outcome, proceed with the following:
- If the information does not match, they correct the details upon the coordination with the merchant.
- If the information matches, they recommend that the merchant contact the third-party acquirer for updating the information and then provide the ecommpay specialists with the updated details.
Note: Processing of payments with the use of the migrated information via the ecommpay platform is only possible after the confirmation of the information correctness is received from the merchant.
Set up the usage of relevant information in the web service.
Thus, for working with tokens, update their values (replacing them by the ones generated in the payment platform), and for working with COF purchases, set up the usage of new identifiers of payments and debits. After that, you are all set to work with the migrated information

Basic parameters for migration are covered below. Contact your ecommpay account manager for additional parameters setup.

Set of parameters for COF purchases

The following table presents the basic set of parameters used to migrate COF purchases information.

Project and customer identifiers

Parameter Description

project_id

Identifier of the project in the ecommpay payment platform, to which the migrated information is related.

Example: 42

customer_id
required for verification

Identifier of the customer in the web service. Must be a string of 255 or fewer characters.

Example: customer_17008

Payment card details

Parameter	Description
`pan` required for verification	Number of the payment card. During migration, the number is used in its full form, while in the verification file, the number is masked and specified in the `card_number` parameter. Example: `4314220000000056`
`card_holder`	Cardholder's first and last names, provided as they are specified on the card and with regards to the applied restrictions. Example: `ARTHUR EDDINGTON`
`card_expiration_month`	Sequence number of the payment card expiration month as an integer from 1 to 12. Example: `5`
`card_expiration_year`	Sequence number of the payment card expiration year in the format of `YYYY`. Example: `2025`
`card_type`	Indicator of the card brand that can be one of the following: `amex`—American Express `maestro`—Maestro `mastercard`—Mastercard `visa`—Visa

Basic details about a COF purchase

Parameter	Description
`description`	COF purchase description, specified as a string of 255 or fewer characters. Example: `Subscription for Cosmoshop mini games pack`
`status`	Status of the record of a series of recurring debits (details): `active`—further debits are awaited. `canceled`—further debits are canceled. If this parameter is not provided, the `active` status is assigned to the series of debits.
`register_payment_id`	Identifier of the record of a series of recurring debits in the merchant's web service specified as a string of 255 or fewer characters. If this parameter is not provided, the identifier is set in the payment platform automatically in the format of `ecommpay–yyyymmddnnn` and sent to the merchant in the verification file. Example: `ecommpay-20230515001`
`recurring_type`	Indicator of the COF purchase type (details): `U`—autopurchase `R`—regular purchase

Parameters of recurring debits

Parameter	Description
`amount` required for verification	Amount of a single debit. Specified in minor currency units (if applicable). In the verification file, the amount is specified in the `recurring_amount` parameter. Example: `999`
`currency` required for verification	Code of the debits currency in the ISO 4217 alpha-3 format. In the verification file, the amount is specified in the `recurring_currency` parameter. Example: `USD`
`start_date` required for verification	Date on which debits should begin after the migration, specified in the `dd-mm-yyyy` format. Example: `01-06-2023`
`start_time` required for verification	Time at which debits should be performed, specified in the `hh–mm–ss` format. Example: `15-00-00`
`period` required for verification	Period used for calculating the interval of debits (to set up recurring debits to be performed each nth number of days, weeks, or other periods), with the following values allowed: `D`—day `W`—week `M`—month `Q`—quarter `Y`—year In case if alongside the `period` parameter, the `period_interval` parameter is not specified, the debits are respectively performed daily, weekly, monthly, quarterly, and yearly.
`period_interval`	Multiplier used in relation to the `period` parameter for defining the interval of regular debits (to set up recurring debits to be performed each nth number of days, weeks, or other periods, where the nth number is the interval), with the allowed integer values from 1 to 100. For example, if the value `3` of the `period_interval` parameter and the value `W` of the `period` parameter are used, the debits should occur every 3 weeks.
`scheduled_payment_id`	Identifier of the next debit as part of a COF purchase, specified as a string of 255 or fewer characters. If this parameter is not provided, the identifier is specified in the payment platform automatically in the format of `ecommpay–yyyymmddnnn` and sent to the merchant in the verification file. Example: `ecommpay-20230515001`

Set of parameters for tokens

The following table presents the basic set of parameters used to migrate tokens information.

Parameter	Description
`project_id`	Identifier of the project in the ecommpay payment platform, to which the migrated information is related. Example: `42`
`customer_id` required for verification	Identifier of the customer in the web service. Must be a string of 255 or fewer characters. Example: `customer_17008`
`pan`	Number of the payment card. During migration, the number is used in its full form, while in the verification file, the number is masked and specified in the `card_number` parameter. Example: `4314220000000056`
`card_holder`	Cardholder's first and last names, provided as they are specified on the card and with regards to the applied restrictions. Example: `ARTHUR EDDINGTON`
`card_expiration_month`	Sequence number of the payment card expiration month as an integer from 1 to 12. Example: `5`
`card_expiration_year`	Sequence number of the payment card expiration year in the format of `YYYY`. Example: `2025`
`card_type`	Indicator of the card brand that can be one of the following: `amex`—American Express `maestro`—Maestro `mastercard`—Mastercard `visa`—Visa

Useful links

When using the capability of migrating information about COF purchases and payment card tokens, you can refer to the following sources that can come in handy:

Interaction concepts—the article with general information about the interaction with the payment platform via Gate.
Credential-on-file (COF) purchases—the group of articles with information about working with COF purchases.
Using tokens—the article with information about working with card tokens.
Monitoring and performing payments—the article with information about processing and monitoring payments and operations via Dashboard.
API Reference—the Gate API interface specification.