Skip to content

ActiveMerchant migration

The ActiveMerchant Migration feature allows a Business Admin user to import merchants and acquirers from GPayments ActiveMerchant (3DS1 MPI) to assist with the transition from 3DS1 to 3DS2. It can be accessed from the Administration interface > Settings > ActiveMerchant Migration tab.

am_migration

Supported ActiveMerchant versions

ActiveMerchant v5.1.12 or above is supported.

Migrate Merchants

All merchants will be assigned an Import status which shows if the merchant can be imported or not. They will also have a Status to indicate if they were Enabled or Disabled in the ActiveMerchant database. Both of these options can be used to filter the search results.

Import status

Import status can be one of the following values:

  • Already imported - The merchant is already imported. Merchant name and Merchant ID pair already exist in the system. A merchant with this status will have a disabled checkbox.
  • Unavailable - The merchant cannot be imported automatically and needs to be imported manually, see the manual import section. A merchant with this status will have a disabled checkbox.
  • Warning - The merchant is missing a Country and/or Default Currency value and can be imported with default values. Default values can be assigned in the popup dialog when initialising the import. The Country and/or Default Currency value will be overwritten for this merchant during the import process.
  • Available - The merchant can be imported automatically with its normal values.

Import merchants manually

When you click on a merchant row you can import the merchant manually by assigning the missing or incorrect fields, or edit any other fields. For merchants with an Unavailable status, this is the only option for importing.

Migrate Acquirers

All acquirers are assigned an Import status which shows if the acquirer can be imported or not.

Import status

Import status can be one of the following values:

  • Already imported - The acquirer is already imported. Acquirer name already exists in the system. Acquirers with this status will have a disabled checkbox.
  • Available - The acquirer can be imported automatically with its normal values.

Step-by-step migration (On-premise)

The following outlines the step-by-step migration process from ActiveMerchant to an ActiveServer (On-premise) instance. For the SaaS migration process please refer below for the relevant different steps.

The migration process of merchants and acquirers is very similar. The following steps outline the migration process for merchants.

  1. Make sure you have configured the application-prod.properties file with your ActiveMerchant database details:

    1
    2
    3
    4
    as.migration.db.vendor=<ActiveMerchant database vendor> e.g. mysql, oracle, mssql, db2 or postgres
    as.migration.db.url=<ActiveMerchant database JDBC url> e.g. jdbc:mysql://<Your My SQL DB Host>:3306/<Your DB Name>
    as.migration.db.username=<ActiveMerchant database username>
    as.migration.db.password=<ActiveMerchant database password>
    
  2. If changes were made to the application-prod.properties file, restart your ActiveServer instance.

  3. Go to the Administration interface > Settings > ActiveMerchant Migration tab and select Connect to establish a connection between ActiveServer and the ActiveMerchant database. If connection is unable to be made an error will be shown.

  4. Start importing the merchants and acquirers by following import merchants and acquirers.

Step-by-step migration (SaaS)

To migrate ActiveMerchant merchants and acquirers to ActiveServer SaaS, we provide an offline utility tool to export the merchants and acquirers in the ActiveMerchant database as a data file. The data file can then be uploaded to ActiveServer hosted service and be imported using the UI provided.

  1. To get the offline utility tool, please contact GPayments.

  2. Once you have the utility tool, unzip it and locate the jar file am.migrator.jar. Move am.migrator.jar into an environment where it can access your ActiveMerchant database.

    The following Java commands are required for the offline utility tool to export the merchants/acquirers from ActiveMerchant:

    • dbUrl - ActiveMerchant database JDBC url. For example, jdbc:mysql://<Your My SQL DB Host>:3306/<Your DB Name>
    • dbPassword - ActiveMerchant database password.
    • dbUsername - ActiveMerchant database username.
    • outputDir - The absolute filepath to the directory in which you want to output the exported data files.
    • dgnId - This is an optional parameter you can specify if you would like to automatically assign threeDSRequestorID for Discover/Diners Club merchants. DGN Client ID is the creator of Merchant Enrollment Request and is static for each entity providing the enrollment.

    This is an example of a command to run the jar file:

    1
    java -jar am.migrator.jar -dbPassword <DB_PASSWORD> -dbUrl <DB_URL> -dbUsername <DB_USERNAME> -outputDir <OUTPUT_DIR>
    

    The offline tool includes functionality to automatically assign the threeDSRequestorName and threeDSRequestorID for each of the card schemes, using GPayments required identifiers where applicable, with the following rules:

    1
    2
    3DS Requestor ID = BID(DS Defined prefix for 3DS server) + * + Merchant Acquirer ID
    3DS Requestor Name = Merchant Name
    
    1
    2
    3DS Requestor ID = DS defined prefix for 3DS server + _ + Merchant Acquirer ID
    3DS Requestor Name = Merchant Name
    
    1
    2
    3DS Requestor ID = MER
    3DS Requestor Name = Merchant Name
    
    1
    2
    3DS Requestor ID = DGN ID (Provided) + _ + Merchant Acquirer ID
    3DS Requestor Name = Merchant Name
    
    1
    2
    3DS Requestor ID = BIN + "MCT" + Merchant Acquirer ID
    3DS Requestor Name = Merchant Name
    
  3. merchants_export_<yyyyMMddHHmmss>_<i>.data will be created under the outputDir you have specified, which is the file that needs to be uploaded via the ActiveServer Admin UI. Navigate to Admin UI > Settings > ActiveMerchant Migration and select the Upload button to upload the data file. The upload process may take a while depending on the size of the merchants and acquirers database. Depending on your ActiveMerchant numbers of merchants and acquirers there may be more than one export file generated, please upload one file at a time and finish the import process to upload another file.

  4. Once upload is complete, start importing the merchants and acquirers by following import merchants and acquirers.

Import merchants and acquirers

  1. Make sure you have a list of merchants or/and acquirers showing up by either following Step-by-step migration (On-premise) or Step-by-step migration (SaaS) depending on your ActiveServer instance.

  2. Check the checkbox of the merchants/acquirers you would like to import. Check the checkbox in the table header if you want to import all merchants, this will select all entries in the table.

    Unavailable merchants

    Any merchants that have an import status of Unavailable cannot be imported automatically as one of the required fields is either missing or not valid. To import these merchants see the manual import section.

  3. Select the import button which will popup a dialog similar to below:

    am_migration

    If you have selected merchants with a Warning import status, the dialog will ask you to pick default values to be used for importing. This feature is useful if you have several merchants with missing fields and requires the same default currency or country.

  4. Select the Import button to start the import process. Wait until the process is finished, and the confirmation dialogue is shown before leaving the page. However, if the process is interrupted, all merchants already imported will be saved and have a Import Status of Already imported the next time import is run again.

FAQ

Should ActiveMerchant be running?

During migration, ActiveMerchant does not need to be running, simply make sure that ActiveServer can access the ActiveMerchant database.

Does migration affect my ActiveMerchant database?

No, the migration process will only read from the ActiveMerchant database you have configured and will not alter the current ActiveMerchant installation.

Do all the merchants or acquirers need to be imported in one session?

No, the migration process can be done multiple times. Each time ActiveServer connects to the ** ActiveMerchant** database it will automatically set the Import Status to Already imported if existing merchant or acquirer information is detected.