Migration to PAYMILL Made Easy

Our goal is enable you to migrate to PAYMILL as easy and fast as possible. Therefore we offer you a convenient and secure data transfer - for free.

1. Process description

This describes in which format the credit card information is transferred from a third PAYMENT SERVICE PROVIDER (PSP) to PAYMILL. The reason why data is moved is because a merchant is switching from his old PSP to the PAYMILL platform.

Credit card data from a third party PSP shall be imported to the PAYMILL platform. Reason is the switch of a merchant from one PSP to the PAYMILL platform. In order to enable the merchant to use the stored card information from the old PSP, the card data need to be imported to PAYMILL. The card data shall be used for a later reference of payment transactions.

General Requirements

File format

  • .csv file with naming convention for the filename
  • PGP encrypted

Data transfer

  • via SFTP to and from PAYMILL
  • Access to the SFTP requires whitelisting of IP addresses and login data which will be secure submitted

Data type

  • The data import include credit/debit card data, such as card number, card expiry date, account holder (optional), etc ...
  • From this data PAYMILL generates a token (=Registration) and a payment object which will be used for later reference by the merchant.
  • The import won't include transactions histories, such as previous debits.

Limitation for number of transaction per file

  • There's no limitation per file.

Clarification of terms

Transaction types generated from the imported data

  • From the imported data PAYMILL will generate Tokens and payment objects for credit card / debit card


  • Refers to the generated payment object and the Token

Payment object

  • The Unique payment object is automatically created by PAYMILL for each imported data.
  • The payment object on PAYMILL side will be assigned to a automatic created client object during the migration. The merchant uses the Paymill client or payment object ID for future debits which reference on the client/ payment object. That means the shopper doesn't need to enter the card details anymore, but the system will use the stored card data from the payment object
  • Each newly generated payment object from the imported data will contain the old Creditcard information of the old PSP token.


PAYMILL (www.paymill.com) and or his TPSP is PCI certified.

2. Data import process

Process description

The following steps should be followed for the import of the Migration data into the PAYMILL system.

Step Description By Whom When
1 Merchant orders data migration with PAYMILL Merchant to PAYMILL Support Clarification phase
2 Clarification with merchant/old PSP if standard data requirements can be met (see table below) PAYMILL Support with merchant/old PSP
3 [OPTIONAL if not default workflow - price on request] Request sample file or sample row of data format and submit to PAYMILL PAYMILL Support from old PSP/merchant
4 Request and submit IP addresses from old PSP for whitelisting and submit to PAYMILL and submit contact details from old PSP PAYMILL Support from old PSP/merchant
5 OPTIONAL if not default workflow - price on request] Clarify the number of card data records per file and the number of required file imports and submit information to PAYMILL.
DEFAULT workflow is: Default is one csv File with the following naming convention [Channel_ID]_[Special_Merchant_ID]_[Number of file].csv. This File is encrypted with a submitted PGP key.
PAYMILL Support with old PSP/merchant
6 Request to initiate data migration to PAYMILL by mail to support@paymill.com Merchant to PAYMILL Support Preparation phase
7 Setup SFTP and designated folder for import and Whitelist IP addresses of third party PSP PAYMILL
8 Provide SFTP access data used for the data migration and the "SpecialChannelID" is the Public Live API Key from the Live mode of the merchant (Can be seen in the My Account Area of the Merchant). Special Merchant_ID is a created and submitted ID. Submit the PGP Public Key to encrypt the CSV File. PAMILL Support to merchant
9 Schedule a migration date and time Merchant to PAYMILL Support
10 Create the csv file with the naming conventions. Encrypt it with the Public PGP Key and move .csv file to designated SFTP folder on the agreed date and time old PSP Data migration phase
11 Fetch the .csv file decrypt it and make the migration (see the csv file definition below). Create the Payment object and Client Object. PAYMILL
12 Generate a new csv file to match the old token to the new created payment object id and to the new created client object id. PAYMILL Response phase
13 Send this .csv file to the merchant PAYMILL Support to merchant

Minimum data and format required for import

The third PSP should provide the data in a csv file including the following minimal values and format.

The filename should look like this format [Channel_ID]_[Special_Merchant_ID]_[Number of file].csv.

The Channel_ID is the Public LiveKey from the Merchant and can be found in the Settings of the Account in the Merchant Centre. The Special_Merchant_ID is an ID which is send via Mail to the PSP.

  • Format expiry: mmyy
  • Header: "cc_number", "holder", "year", "month", "ppan-Token", ... (please be sure that the fieldnumber is in increasing value!!)
  • Example row: "4111111111111111", "Max Muster", "2017", "02", "f81ec685b368c55c6cfb8e9f69107916", ...
Field No. Old PSP field values Field type Field format description Mandatory / Optional
1 <CC_number> Data type: Alphanumeric
Length: 3..64
Card number in plain text Mandatory
2 <holder> Data ty pe: Alpha
Length: 4..128
Card holder Optional
3 <year> Data type: Numeric
Length: 4
The expire year of the credit card (YYYY). The year of 2011 is formatted as "2011". Mandatory
4 <month> Data type: Numeric
Length: 2
The expire month of the credit card (MM) minimum two characters. E.g. the value "1" must be formatted as "01". Mandatory
5 <PPAN-Token> or any other value that includes old PSP token Data type: Alphanumeric
Length: 0..256
Token from old PSP which will be mapped to the payment Object ID as the new "token" Mandatory
6 <brand> Data type: Alpha
Length: 3..10
Name of the credit or debit card brand. The complete list of supported brands Optional
7 <customer_country> Data type: Alpha
Length: 2
Country code according to the ISO 3166-1 specification
Country of the Shopper Optional
8 <identifier> Data type: Alphanumeric
Length: 3..64
Date or name of the file with which the transactions can be identified per file Optional
9 <currency> Data type: alpha
Length: 3
Currency of the transaction Currency code according to the ISO 4217
Please be sure you support these currencies in the contract and they are working in live mode
10 <client_object> Data type: Alphanumeric
Length: 0..256
Identifier for a client . Right now not used because clients will be created automatically in PAYMILL. Optional

Data mapping for exported data

Is made through the old token which matches with a new Payment object id and a client object id. All Data is linked to the PAYMILL Client Object which was automatically created through the migration script and is entered in the Export csv file.

PAYMILL creates the following .csv for you to map the new payment object ID and the client object ID with the old "token". This file will be delivered to you from our PAYMILL support.

Old PSP field values Field type Field format description
<PPAN-Token> or any other value that includes old PSP token Data type: Alpha
Length: 0..256
Token from old PSP which will be mapped to the payment Object ID as the new token
<PAYMILL Payment object ID> Data type: Alpha
Length: 0..256
New Payment object ID which was created in our system for an imported token/ CC Data from the old PSP
<PAYMILL Client object ID> Data type: Alphanumeric
Length: 0..256
Identifier for the Client Object ID for a customer which will be created at the migration for every new payment object.
The PGP key is to encrypt your csv file which is sent to the sftp server (see table 1 row 8).
Version: GnuPG v1.4.12 (GNU/Linux)