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:

  1. Agree with the other acquirer on the migration availability and conditions.
  2. 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.

  3. 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.
  4. 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.
  5. 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.
  6. 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