Migrations overview

Pismo enables you to migrate accounts from an external system to the Pismo platform. Migration transfers new accounts on the Pismo platform, along with all the migrated data from the legacy resource — including account details, customer information, card data, balances, and transaction history.

There are two ways to migrate data:

  • Use Pismo's Migrations API.
  • Upload files directly to an Amazon S3 cloud storage bucket provided by Pismo. The data in these files must be formatted according to templates provided by Pismo.

📘

Accounts cannot be migrated through file upload. You must contact your Pismo representative to request access to the Migrations API.

Types of data that can be migrated

Accounts and customers

  • Includes name, document number, address, telephone, account status, and account limit. Other custom fields can be specified.
  • You can migrate canceled/inactive accounts.
  • Fields can be updated at any time before the migration is fully finished.

Cards

  • A card must be associated with an account.
  • Data for cards includes card name, status, type, issue date, expiration date, PAN, service code, and password.
  • There is an exclusive bucket for PCI data (encrypted file with AWS KMS keys).
  • Migration API and workers are PCI compliant.

Authorizations

  • Information about authorizations is ISO 8583 based.
  • An authorization must have an associated account and card.
  • You can migrate up to six months of authorization history.

Balances/Statements

  • A statement must have an associated account.
  • Information about statements includes closing date, due date, current and previous balance.
  • You can migrate up to six months of history for statements.
  • You can migrate pre-calculated accruals (and then continue accruals calculation on the Pismo platform after migration).

Transactions

  • A transaction must have an associated account and statement. If it is a network transaction, it must also have an associated card and authorization.
  • Information about transactions includes date, amount, authorization code, transaction type, merchant data, interest rate.
  • You can migrate up to six months of transaction history.
  • You can migrate different transaction types, including purchases (with or without installments), adjustments, and payments.

Migration process

Go live is a process that happens at the end of a migration timeline. After migrating accounts, the client must call the go live endpoint to tell the Pismo platform to make the migrated accounts accessible. The Pismo platform responds by changing the migration status of each account to MIGRATED.

In the migration process, entry refers to a data object that you are migrating to the Pismo platform. Every entry generates an event that is processed asynchronously. You need to send a unique migration ID and migration date with every entry. This guarantees no duplicate entries. If you want to update an entry, you must send the same migration ID plus a migration date that is later the current migration date.

Migration events

There are three types of migration events:

  • File events – If a line fails, a file_unparseable_line event is generated that specifies which line had a problem. After a file processes, the Pismo platform generates a file_summary event. This event includes the file name, status, number of processed lines, and number of failed lines.
  • Incoming events – Sent for every entry. Includes all the data sent to migration endpoints or files.
  • Outgoing events – Sent for every entry. Includes the migration ID and Pismo IDs. For example, when you migrate an account, the generated event includes the account migration ID, the Pismo account ID, and the Pismo customer ID. It also indicates whether or not the migration was successful. If the migration fails, the event includes an error code and message.

Go live events

There are two types of go live events:

  • After migrating accounts, you must call the Migrate accounts Go Live endpoint to let the Pismo platform know that the accounts are migrated and ready to use. Pismo responds by changing the migration status of the accounts to MIGRATED.
  • After an account goes live, the platform might still need to update some card data. For instance, a cardholder might have changed their password at an ATM machine soon after their account is marked as MIGRATED. The platform allows cards to be updated until you call the Migrate PCI cards Go Live endpoint. After that, no more changes are allowed. So, you can choose how much time you want to provide for such changes.

📘

Calling the Migrate PCI cards Go Live endpoint blocks further changes to cards.

Migration using file upload

You can migrate the following types of products using the file upload method:

  • Authorizations
  • Cards
  • Statements
  • Transactions

📘

Accounts cannot be migrated using file upload.

To migrate a product using a file:

  1. Contact your Pismo representative to obtain template files for the product types that you want to migrate. For example:

    • To migrate authorizations, use template_authorizations (en).xlsx.
    • To migrate card data, use template_cards (en).xlsx. This spreadsheet contains two worksheets:
      • non-pci data for non-PCI card data
      • pci data for PCI card data.
    • To migrate statements or transactions, use template_statements_and_transactions (en).xlsx.
  2. Add the information specified in the template and save the result as a CSV file. Note the following:

    • The first line in the CSV file corresponds to the header section of the template (lines 5 - 9).
    • The next lines correspond to the card information that you want to migrate, formatted as specified in lines 13 - 36. (Only part of each line is shown in the image.)
    • The last line in the file should be in following format:
      99, [number of records]
      For example:
      99,00000000000000021
      This is specified in the trailer section of the template (lines 40 - 41).
      The following figure shows a snippet from a typical migration file:
  1. When your CSV files are done, contact your Pismo representative to request an S3 bucket to contain your CSV files.

  2. Upload your CSV files to the bucket provided by your Pismo representative. This bucket must contain a subfolder for each product type to be migrated. For example:

    • /cards
    • /pciCards
    • /statements