Migration refers to the transfer of financial products and all of their related data from your legacy, external system to the Pismo platform. The term entity refers to a data object that can be represented on the Pismo platform, such as accounts, cards, and statements.

Entities that can be migrated

The following chart illustrates the types of migration entities.

Accounts and customers

Data for accounts includes customer data such as their name, document number, address, telephone number, account status, and account limits. Custom fields are also supported.

📘

You can migrate cancelled/inactive accounts.

• Fields can be updated at any time before the migration is fully finished.
• You can migrate multiple customers at a time for the same account.

Cards

A card must be associated with an account (except for noname cards, which are for special use cases like prepaid/gift cards). Card data includes the card name, status, type, issue date, expiration date, and so on.

📘

• You should migrate cards of every status, including canceled ones, to ensure the integrity of the PAN (primary account number).
• You can migrate both physical and virtual card types.
• You can migrate combo cards (debit and credit in the same card)

To migrate a combo card, you first need to migrate both of its associated accounts — credit and debit. For more information, see Create combination card with card modes . For example, to migrate the credit account first, follow these steps:

1. Migrate the credit account: document_number = 123 and migrationId = abc.
2. Migrate the debit account: document_number = 123 and migrationId = def.
3. Migrate the card:
   1. For a credit account:
      1. mode = COMBO
      2. migration.accountId = abc
      3. migration.cardId = XXX
      4. migration.combo_account_id = def
   2. For a debit account:
      1. mode = COMBO
      2. migration.accountId = def
      3. migration.cardId = YYY
      4. migration.combo_account_id = abc.

📘

Both accounts must be registered to the same document number, which identifies the account holder on the Pismo platform.

PCI data

PCI data includes the PAN, service code, and password (PinOffset or Pinblock format). Encryption ensures that PCI data remains secure as it is transmitted between the Pismo platform and the processor. Pismo migration APIs and workers are PCI compliant, and PCI is stored in a dedicated S3 bucket.

📘

• PCI file encryption can use either native AWS KMS key or PGP key.
• HSM key exchange (from the previous processor to Pismo) is required to keep the PCI data (such as the card PIN) transparent to the cardholder.

Tokens

A tokenized card is used for online purchases (using digital wallets like GooglePay, ApplePay, SamsungPay) or for saved payment information. Data for tokens includes token ID, expiration date, status, and wallet ID.

Authorizations

Network authorization are those generated by a third-party card network such as Visa, Mastercard, or Elo. A network authorization must have an associated account and card.

📘

• Authorization data conforms to the ISO 8583 standard message structure for electronic transactions.
• You can migrate up to six months of authorization history.
• PENDING status authorizations are required.

On-us authorizations

On-us authorizations are those that are processed internally, without involving a card network (such as Mastercard or Visa). Data for on-us authorization includes account, cards, authorization date/hour, amount, authorization code, and status.

Merchants

A merchant is an entity that represents a business that sells products or services in your marketplace. It can be anything from a gas station to an e-commerce seller inside a portal. For more information, see Seller management overview.

📘

• For each merchant, the platform maintains a marketplace entity. A marketplace contains multiple merchants. It must be preconfigured to migrate merchants.
• Merchant data includes marketplace ID, address, and creditor configurations.

Statements

Statement data includes account ID, cycle closing date, due date, initial and final balance. You can migrate up to six months of statement history. For more information, see Understanding statements.

📘

• A statement must have an associated account.
• Only closed statements are migrated; the Pismo platform generates current and future statements.

Recurring charge plans and links

A recurring charge plan sets up charges that automatically occur at a regular interval, such as monthly, quarterly, or annually. These usually are used to migrate annual fees. Recurring charge plan data include processing code, installment amount, description, and number of cycles.

A recurring charge link is an ID that links an account to a recurring charge plan. Recurring charge link data includes charge plan ID, account ID, and number of installment to start the charge.

Transactions

Transaction data includes the date, amount, authorization code, transaction type, merchant data, and interest rate. You can migrate up to six months of transaction history, but it’s recommended to migrate all the installments history. For more information, see Transactions overview.

You can migrate the following types of transactions.

• Billing type
  • BILLED – For credit accounts, this refers to transactions that belong to a closed statement. For debit accounts, you can always use the BILLED type.
  • TO_BE_BILLED – Credit accounts refer to transactions that belong to the current/open statement. For Debit accounts, this does not apply.
  • INSTALLMENTS – For credit accounts, this refers to transactions/installments that belong to future statements. For debit accounts, this does not apply.
• Authorization type
  • NETWORK – (credit accounts only) — Transactions authorized by the network like Visa, Mastercard, Elo. Example: purchase, installments with or without interest.
  • ON_US – (private label cards/accounts) — Transactions authorized by an issuer’s internal network. Example: purchase, installments (with or without interest).Payment agreement
• • For credit card refinancing products:
    • Statement agreement
    • Installment agreement

📘

• A transaction must be linked to an account.
• A network transaction must have an associated card and an authorization.
• A statement ID is required for credit accounts.
• Transaction types include: network (Visa, Master, Elo purchases, canceled and chargebacks) transactions and platform transactions (adjustments, fees, interests).
• On-us transactions (purchases, for example). In addition, for credit accounts, the transaction’s migration is differentiated by BILLED, TO-BE-BILLED, and future INSTALLMENTS.
• Payment agreements such as credit card refinancing agreements are migrated together with the transaction.
• You do not need to migrate transaction history for canceled accounts.

Accruals

Data for accruals includes accrual type and accrual amount. You can migrate accruals that have already been calculated by another processor (this happens when the original system has daily accruals processing).

Balance migration

Balance migration is necessary to initialize the balances of a migrated transaction’s current balance on the Pismo platform. To perform balance migration, migrate the balance control data, which includes the account ID, accruals cut-off date, balance type, and balance amount. Optionally, you can split the closed balances to indicate which ones are accruable (or not) and fineable (or not).

📘

• The platform can calculate accruals retroactively if the legacy platform does not supply them.
• Optionally, the platform can generate balance controls for you, but in this case, a unique balance type ACCRUABLE_FINEABLE is generated for the due date of the entire statement (M-1 or M-2) due balance.

Migration entities by line of business

The following table lists which entities to migrate depending on your line of business.

Timeline and steps

You can migrate data on any schedule you prefer. Typically, the migration process is divided into steps. As an example, you can schedule your migration project to occur over 15 days and divide the work into three steps, as follows:

When using the Go-live endpoint, every migrated account that has been assigned the specified phase ID has its status changed to MIGRATED.

Prerequisites

You must complete the following tasks before you can migrate data to the Pismo platform:

• Create your Org and programs on the Pismo platform.
• Configure processing codes and transaction types.
• Configure transaction categories.
• Key ceremony (for migration keys).
• Configure SFTP and Amazon S3 cloud storage bucket for file migration.

Migration methods

There are two methods for migrating your data to the Pismo platform:

• Use Pismo's Migrations API.
• Upload files using SFTP to a dedicated Amazon S3 cloud storage bucket (provided by your Pismo representative).

Migration using the API

📘

You must consult your Pismo representative to receive access to the Migrations API and for your S3 bucket information.

For information about authentication to the Migrations API, see Authentication with OpenID Connect.

Migration using file upload

Files must be formatted according to templates provided by your Pismo representative. The template files are provided in XLSX format for ease of use. But you must save the results in CSV format. An SFTP configuration is required to upload the CSV files to the S3 bucket.

The following example shows a snippet of data from a typical migration file.

01,PCI,2022-12-15,22:38:28,000032184
02,PCI,0W431L4PUEGTJJ5DW4C,2022-12-15T22:38:28.00000Z,,000,4642950127683540,0,0
02,PCI,IV12Y7KQ0GJSO3V5JZA,2022-12-15T22:38:28.00000Z,,000,4642957650184234,0,0
02,PCI,TL7CEJ9DTRT6ZK3CWD4,2022-12-15T22:38:28.00000Z,,000,4642958421673505,0,0
02,PCI,WGUZZKBT00PT04NXTBR,2022-12-15T22:38:28.00000Z,,000,4642957281560349,0,0
02,PCI,6VNUMLRXHIY33S4B47U,2022-12-15T22:38:28.00000Z,,000,4642951732054861,0,0
02,PCI,509V934V9NVQE2L5X2W,2022-12-15T22:38:28.00000Z,,000,4642951327640587,0,0						
								 . . .
02,PCI,FGESA33KJ47ZRY6CS1E,2022-12-15T22:38:28.00000Z,,000,4642952750416834,0,0
99,000000250

Note the following:

• The first line represents the header section of the template.
• Each subsequent line corresponds to an entity that you want to migrate.
• The last line is a trailer containing the total number of records.

To migrate a product using a file:

1. Open the template for each product type you want to migrate. For example:
   1. For authorizations, use template_authorizations (en).xlsx.
   2. To migrate card data, use template_cards (en).xlsx.
2. Add the information specified in the template and save the result as a CSV file.
3. When you finish with your CSV files, contact your customer representative to request an Amazon S3 cloud storage bucket to hold them. This bucket should contain a subfolder for each product type (for example: /cards and /pciCards).
4. Upload your CSV files to the appropriate Amazon S3 cloud storage bucket or SFTP.

Migration data events

Every migrated entity generates a data event that is processed asynchronously.

📘

Idempotency

You must set a unique migration ID and migration date for every entity to be migrated. For accounts, you also must specify the phase_ID. These factors help ensure idempotency (no duplication of entities). To update an entity, you must send the same migration ID plus a migration date that is later the current migration date.

There are three types of migration events:

• File events – Used to indicate failures when migrating a specific entity (represented by a line in the CSV file). If an entity fails, the platform generates a file_unparseable_line event, which identifies 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 entity. Includes all the data sent to migration endpoints or files.
• Outgoing events – Sent for every entity. 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.

Pre-go live and Go-Live

The Migrations API provides a two-step process that can handle situations before running the go-live itself.

Pre-go live endpoint

📘

Pre-go live is a required step for credit account types, but it is otherwise optional.

Calling this endpoint triggers the following actions for every account to which you assign a specific phase ID:

• Update of transaction balances (for non-due transactions).
• Discharge of transactions (following the payment hierarchy).
• Calculate the accruals retroactively (sent on balance control migration).
• Update the account’s DueDate field.

However, unlike go-live, pre-go live does not change the status of an account. It only generates a Pre-Go live migration completed data event for each account as either SUCCESS or FAIL.

Go-live endpoint

Go-live changes the migration status of the accounts to MIGRATED after all details have been confirmed, and starts the accounting generation for credit accounts only. Calling this endpoint blocks further account changes.

Go-live triggers the following actions for every account to which you assigned to a specific phase ID:

• Changes the account_status field from its original value (usually STAND-BY) to NORMAL, which is the status sent on the go_live_account_status field upon an account’s migration).
• Changes the migration_status toMIGRATED, which indicates that the account has become active on the Pismo platform. (The pre-go live endpoint omits this step.)

📘

Go-live for accounts should be performed together with the go-live for networks.

Rollback

After go-live, rollback is possible only for the following entities:

• Transactions (soft-delete rollback)
• Statements (soft-delete rollback)
• Network/off-us authorizations (soft-delete rollback)
• On-us authorizations (soft-delete rollback)

📘

In a validation/test environment, rollback can be used freely, but use caution in a production environment. Rollback cannot be done for accounts after go-live. This is because active accounts generate new data, including authorizations and accruals. Go-live also enables the accounting and regulatory processes to be started on the Pismo platform).