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.

Due to the data sensitivity, the data should be encrypted before migration. When it comes to migrating data to the ecommpay platform, this data is usually encrypted via the PGP (Pretty Good Privacy) algorithm; however, in certain cases, other methods can be used upon the coordination with the ecommpay specialists (for example, when the acquirer that provides the data does not support the PGP encryption).

For migrating data, the file with this data must be encrypted by your current acquirer providing the data with the use of the public key from ecommpay (in case of the PGP encryption) and sent to the ecommpay specialists. Contact your ecommpay account manager to set up a communication channel with the dedicated ecommpay specialists responsible for the data migration.

After all the necessary data 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 data, 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 data 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 data migration, the merchant should consider the conditions and limitations from both the acquirer providing the information and ecommpay receiving the data. 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 data 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 data 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 previous 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 your current 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 data migrated, the merchant should:

  1. Agree with the other acquirer on the migration availability and conditions.
  2. Inform the ecommpay account manager that data 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 contact information of the specialists in charge of migration on the side of the merchant, the acquirer, from which the information should be obtained, and ecommpay—for organising the interaction and addressing arising questions, including questions related to the information correctness.
  4. If the direct interaction between the specialists of your current acquirer and ecommpay is not organised, receive the encrypted file with data from the acquirer and submit it to the specialists responsible for migration on the ecommpay side. Contact your ecommpay account manager to set up a communication channel with the dedicated ecommpay specialists responsible for the data migration.

    When it comes to migrating data to the ecommpay platform, this data is usually encrypted via the PGP (Pretty Good Privacy) algorithm; however, in certain cases, other methods can be used upon the coordination with the ecommpay specialists.

    Figure 1. Public key from ecommpay for PGP encryption
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    
    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
    =jMHf
    -----END PGP PUBLIC KEY BLOCK-----
    
  5. After a verification file is received from the ecommpay specialists is received at 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.
  6. 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 previous 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 previous 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.
  7. 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

scheme_id

Identifier of the initial operation of COF registration. This identifier is assigned by the global card network (Mastercard or Visa) and can be used when a COF purchase is registered in the European Economic Area.

Examples: MDS60JXCH0209 (for Mastercard) and 482269429345022 (for Visa)

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

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.

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 assigned to the payment within which scheduled debits are performed, 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