Migration refers to the transfer of financial products and all of their related data from your legacy, external system to the Pismo platform.

Entities that can be migrated

The term entity refers to a data object that can be represented on the Pismo platform, such as accounts, cards, and statements. Migration involves the following entity types and should respect this sequence here:

• Accounts
• Customers
• Cards
• PCI
• Tokens
• Authorizations (off-us and on-us)
• Statements
• Transactions
• Recurring charges
• Marketplaces and merchants
• Disputes
• Accruals
• Balances
• Go-Live and Pre-Go-Live

Migration entities by line of business

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

The following diagram shows the relationships between accounts, customers and cards.

Accounts

An account on the Pismo platform represents a financial service provider's account. Each account is contained within a program, and the account’s type (such as credit, debit, or prepaid) is determined by the type of program that contains it. Accounts have balances and credit limits as attributes.

📘

Important points

• Accounts also contain customer information, including their addresses and phone numbers, and any cards issued for the account. Every account must be created with one customer, who serves as the account holder.
• Multiple customers can share one account.
• An account can have multiple customers, and a customer can belong to multiple accounts.
• An account may issue several cards to its customers, all of which draw from the same account balance.
• You can migrate canceled or inactive credit accounts, but only for the purpose of migrating canceled cards.
• All accounts using the same BIN must be migrated during the same migration phase. This means that they should all have the phase_ID.

Customers

Customer information includes their document number, addresses, and phone numbers. Accounts also include information about any cards issued for the account.

📘

Important points

• All customers for the same account must be migrated during the same migration phase. This means that they should all have the phase_ID.
• Customers are added only with the Accounts API.

Cards

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

📘

Important points

• You can migrate both physical and virtual card types.
• You should migrate cards of all statuses, including the canceled ones, to ensure the integrity of Primary Account Numbers (PANs).

Migrating combo cards

The term combo card refers to a card that can be used in either credit and debit mode. When migrating a combo card Both accounts must be registered to the same document_number, which identifies their owner on the Pismo platform. For more information, refer to Create a combination card with card modes.

1. Migrate the credit account (Account A): document number = 123 and migrationId = abc.
2. Migrate the debit account (Account B): document number = 123 and migrationId = def.
3. Migrate the card (id = 123 and mode = COMBO):
   1. For Account A (the credit account):
      1. mode = COMBO
      2. migration.accountId = abc
      3. migration.cardId = 123
      4. migration.combo_account_id = def
   2. For Account B (the debit account):
      1. mode = COMBO
      2. migration.accountId = def
      3. migration.cardId = 123
      4. migration.combo_account_id = abc.

To migrate a combo card that has only one mode activated, you can migrate either the debit or credit account first, together with the card (type COMBO).After Go-Live, it’s possible to activate the other mode separately, using the Add card mode endpoint.

PCI

PCI (Payment Card Industry) refers to sensitive information related to payment cards that require extra security measures to protect it. This includes data such as the Primary Account Number (PAN), Service code for Card Verification Value (CVV2), and security passcode (PIN using PinOffset or Pinblock format).

Pismo migration APIs and workers are PCI compliant. There is an exclusive bucket for PCI data. PCI file encryption by either native AWS KMS key or PGP key). During the migration of PCI-sensitive information, you can use our PCI specific migration API or send using files through SFTP.

📘

Important points

• PCI file encryption by either native AWS KMS key or PGP key. The PGP public key needs to be shared between Pismo and the issuer.
• For PCI data, the exchange of HSM keys between Pismo and the processor is important.

Tokens

In the context of card network transactions, a token is a substitute value used to replace sensitive card information. This is a unique identifier that can’t be reverse engineered to reveal the original card information. This process is known as tokenization.

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

Authorizations (off-us and on-us)

Authorization refers to the process of validating transactions based on a set of predefined rules. It is a record stating that a given amount was authorized for an account deposit or withdrawal. It contains information about its nature, such as the amount, local currency, date and time, and applicable fees.

Authorizations can be either:

• Off-us (also known as network authorizations): Authorizations generated by a third-party issuer, usually a card network such as Visa, Mastercard, or Elo. A network authorization must specify the associated account and card.
• On-us: Authorizations generated for you by Pismo acting as the issuer, as for private label cards.

Data for Off-us authorizations includes, for example, account, card, authorization date/hour, amount, authorization code, and status.

📘

Important points

• You can migrate up to six months of Off-us authorization history.
• PENDING status authorizations are required.

Statements

A statement is a collection of charge and fee balances that results from credit card transactions. Statement data includes account ID, cycle closing date, due date, initial and final balances after any accrued balances are applied. You can migrate up to six months of statement history.

Statements are ordered through their cycle number, and every new account has a moving window of 42 cycles. The platform updates the debits, credits, and resulting balances in real time for each new transaction as it occurs.

The minimum amount due (MAD) is calculated at the cycle closing date, and the platform assigns an open due date to the account, marking the first day of debt in cases of default. Balances are calculated according to transaction balances and are managed at either the program or account level.

📘

Important points

• A statement must specify its associated account ID.
• Only closed statements are migrated—current statements (as of the migration date) and future statements are generated by the Pismo platform.
• A statement ID is required for credit accounts.

Transactions

Transaction data includes 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. It is not necessary to migrate transaction history for canceled accounts.

You can migrate the following different 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 send with this type.
  • TO_BE_BILLED: Credit accounts refer to transactions that belong to the currently 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: For credit accounts only, refers to transactions authorized by the network like Visa, Mastercard, Elo. Example: purchase, installments with/without interest.
  • ON US: For private label cards/accounts, refers to transactions authorized by an issuer’s internal network. Example: purchase, installments (with or without interest).
  • PLATFORM: For credit accounts, refers to transactions generated by an internal system, like payments, credit or debit adjustments, fine/overdue transactions. For debit accounts, refers to banking transactions, like payments, adjustments, P2P transfers, cashin/cashouts transfers.
  • BANKING: For debit accounts, refers to Pix instant payments transactions, where information related to Pix is needed.
  • PAYMENT AGREEMENT: For credit card refinancing products. Refers to:
    • Statement agreement: Customer renegotiates all pending pending debt for all their statements.
    • Installment agreement: Customer agrees to settle the amount over the next few bills (the outstanding amount is added to the statement for the following month.

📘

Important points

• During the migration process you cannot add transactions to an account.
• A transaction must be linked to an account.
• A network transaction also must include the associated card and an authorization.
• Examples of transaction types include on-us and network transactions (purchases, cancellations, and chargebacks), and platform transactions (adjustments, fees, and interest.
• Payment agreements (such as credit card refinancing agreements) are migrated together with the transaction.
• For installments with interest, additional data in transactions migration might be required.

Recurring charge plans

Recurring charge plans define charges that automatically occur at a regular interval, such as monthly or annually. Examples include subscriptions for services like streaming platforms, gym memberships, or software subscriptions. Attributes of a recurring charge plan include processing code, installment amount, description, and number of cycles.

To use a recurring charge a plan, you must first create it (or reuse one that already exists on the platform) and then link it to an account. A recurring charge link is an ID that links an account to a recurring charge plan. Recurring charge link data includes plan ID, account ID, and number of installments. Once linked, the plan is automatically activated, and the account can begin incurring charges based on the plan settings.

📘

Important points

• One plan can be linked to multiple accounts, and one account can be linked to multiple plans.
• An account can even be linked to the same plan multiple times, as long as each link has a different tracking_id.
• You can deactivate a plan for a specific account by removing the link between them or disable the plan altogether.

Marketplaces and merchants

A marketplace is a grouping of merchants who sell their products in the same online forum or physical point of sale. The marketplace deducts a fee from each sale. It is the top entity in the hierarchy of objects that make up your digital marketplace. You can create a Marketplace object and customize it to suit your business needs. It can represent a single merchant or a group of merchants that share the same tax structure and setup. Additionally, it enables you to set up a schedule to handle settlements for all the merchants that belong to the marketplace.

Merchants

Merchants are individuals or businesses that sell products or services within a marketplace. Each merchant has a schedule and a register of transactions in the Marketplace object. Merchants can be linked to one or more marketplaces, and their accounts receive funds from sales during the settlement process. The Merchant object includes marketplace ID, address, and creditor configurations. For more information, refer to Seller management overview.

Merchant transactions

Merchant transactions are records of purchases, transfers, payments, or manual adjustments. These transactions are triggered by approved authorizations and are the end result of a financial operation. A financial operation can include activities such as withdrawals, purchases, payments, cash-ins, or transfers. The authorization step performs several validations, including checking if the account or card is valid, if the operation is allowed based on configured transaction flex controls, if the account limits are within the allowable range, and if there is any fraudulent activity. If the authorization succeeds, the platform updates the customer timeline and may affect the credit limit or account balance depending on the type of program (credit, debit, or prepaid).

Merchant transactions can be of different types, either debit or credit, and may affect bank or credit card statements. Some transaction types also have accounting implications. The Pismo platform supports various types of financial operations, including peer-to-peer transfers, card network operations, and purchases. The platform uses configured processing codes and their mappings to transaction types to generate transactions.

Disputes

A dispute occurs when a cardholder requests a cancellation or refund for an unrecognized or suspicious transaction. The process involves the cardholder notifying the card issuer, who then makes dispute API calls to the Pismo platform. Pismo opens the dispute with the card network and informs the issuer and cardholder about the dispute status once there is a response from the network. If the issuer loses the dispute, they can either accept the loss or file a case with the card network.

Accruals

Accrual refers to the fees and charges that an account can accumulate over the course of a credit cycle. These charges can include refinancing charges, overdue charges, interest on withdrawals, bill payment interest, overdraft interest, financial taxes, fines, and late payment fees. The amount of these charges is determined by an accrual rate, which is usually a percentage.

Accrual types

The Pismo platform uses accrual types to to apply these rates. For example, refinancing is a daily charge applied to an unpaid balance if the total amount due has not been paid, while overdue is a daily charge applied if the minimum amount due has not been paid. Fees and charges apply to things like revolving interest, late payments, withdrawals or bill payments using a credit card, for example. After the monthly payment due date, there may be daily accrual calculations. In this case, charges are projected from the cycle closing date to the due date. Accruals are posted as transactions and added to the total amount due.

Migrating accruals

Pending accruals migration is necessary only for accounts between due date and cycle closing date. For accounts migrated between the cycle closing and due date it’s also possible to migrate projected accruals until the due date, so in case of an anticipated payment we can refund the accruals.

For example, suppose an account’s cycle closing is 28 June due date is 10 July. If the account migration occurs on 15 June, Pismo calculates accrued charges from the 10th to the 15th. Otherwise, Pismo calculates accrued charges from the 15th to the 10th (retroactively on Balance control migration) and then, from the 16th onwards, the account enters the normal daily accrual process on the Pismo platform).

Basically, if you have daily interest accruals calculated on your legacy system when an account has not paid the minimum amount due on a statement, you need to send the sum of the accruals already calculated, summarized by account, in the Migrate accruals endpoint. This information tells Pismo which accruals amount you want to be posted on the next invoice, to avoid lost revenue.

Example 1

Suppose you have a customer being migrated with cycles 1, 2, and 3

Calculations occur according to the configuration parameterized for each transaction category. For NOTACCRUABLE_NOTFINEABLE balances, you need to configure the balance transaction along with all other types of transactions that should not be accrued on the platform. For more information, see Setting transaction types to block accrual charges.

The sum of the balance amounts in a balance control migration should match the current balance on the latest due statement at the time of the account Go-Live. Since the balance control migration and the Go-Live process may happen at different times, this go_live_date field is necessary to determine which account statement should be used to validate the balances match.

Example 2

Consider an account whose due_date = 16 and w ith two statements:

• Statement 1: cycle_closing_date = 2024-04-06, due_date = 2024-04-16
• Statement 2: cycle_closing_date = 2024-05-06, due_date = 2024-05-16

In this case:

• A balance control migration with go_live_date = 2024-05-15 should have the sum of its balance amounts equal to the balance of Statement 1 (because statement 2 is not due yet).
• A balance control migration with go_live_date: 2024-05-17 should have the sum of its balance amounts to be equal to the balance of Statement 2 (because it will become the latest due statement at that point).

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 due balance (M−1 or M−2).
Accrued charges are projected and collected until the due date. When the statement cycle closes, the platform can make projections of daily accruals up to the due date.

For example, suppose that the cycle closing occurs on the 28th and due date on the 10th. If migration occurs on the 15th, the platform calculates projected charges to accrue from the 10th to the 15th. Otherwise, the calculation will be retroactive from the 15th to the 10th (retroactively on Balance control migration); from the 16th onwards, the regular daily accrual process occurs on the platform.

Balances

Migrating statements involves migrating due balances. Current balances are calculated, determined by each of the transactions in a statement. Balance migration is necessary to set the initial balances of a migrated transaction’s current balance on the Pismo platform. Optionally, you can split closed balances to indicate which ones are accruable (or not) and fineable (or not).

Balance attributes include account ID, accrual cut-off date, balance type, and balance amount.

Each monthly statement (M) corresponds to a billing cycle, and when a cycle ends, another begins.

• M: Current billing cycle
• M − 1: Previous billing cycle
• M − 2: Two billing cycles prior

Balance control transaction types

You must provide these values to Pismo. We do not migrate balances per transaction, so we need to initialize balance for the account. Then, we create control transactions. The initial balances you provide become the first amount in the hierarchy to be evaluated. Payment, purchase, fine, accrual. Valid accrual types are:

• ACCRUABLE_FINEABLE
• ACCRUABLE_NOTFINEABLE
• NOTACCRUABLE_FINEABLE
• NOTACCRUABLE_NOTFINEABLE
• CREDIT (for credit balances)

📘

The NOTACCRUABLE_FINEABLE and ACCRUABLE_FINEABLE types shouldn’t apply to accounts that are migrated between their cycle closing and due date.

• Accruable means that interest or earnings have accumulated over a specific period but have not yet been posted to the account. This is defined according to the business rules of each issuer and configured by transaction category. The issuer may determine that for some types of transactions, there will be no charges.
• Fineable means that a balance is subject to a late payment penalty. This is also configured by transaction category. The fine can be applied only once on the same balance, so if the balance has already been fined, it cannot be fined again in another cycle. Only a new balance (posted for the first time on the invoice that will be the basis for calculating the fine) is fineable.

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

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.

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 container (container details are provided by your Pismo representative).

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 an event that is processed asynchronously. Event data includes the migration ID and the various entity type IDs. For example, when you migrate an account, the generated event includes the account migration ID, the account ID, and the customer ID.

📘

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.

Migration events are sent for every entity. There are three types:

• Incoming events: Includes all the data sent to migration endpoints or files. Example: Account migration started.
• Outgoing events: These events also report whether or not the migration was successful. If the migration fails, the event includes an error code and message. Example: Account migration completed.
• File events: Used to indicate failures when migrating a specific entity (represented by a line in the CSV file). If an entity migration fails, the platform generates a file_unparseable_line event item, 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.

Go-Live and Pre-Go-Live

In the context of the Pismo platform, Go-Live refers to the point at which your migrated entities become fully operational and available for use by customers. The Migrations API provides a two-step process that can handle situations before running the Go-Live itself. As an extra precaution, there is also a Pre-Go-Live step that you can use to simulate Go-Live. Pre-Go-Live is required for credit account types, but it is otherwise optional.

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 field value 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.

Pre-Go-Live endpoint

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.

📘

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.

Rollback

After Go-Live, rollback is possible only for certain entities:

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

However, rollback cannot be done for accounts after Go-Live. This is because activated accounts generate new data, including authorizations and accruals. Go-Live also enables the accounting and regulatory processes to be started on the Pismo platform).

📘

In a validation/test environment, rollback can be used freely, but use caution in a production environment.