Migration Manual

Here we describe how to facilitate the migration of your existing data into the Adyen Payment System.

Audience

This manual targets merchants who want to use the Adyen payment services to efficiently and safely process their business transactions.

Feedback

We strive to provide you with clear, concise, and complete documentation. We are committed to improving it continuously to make it accessible and easy to understand.

We appreciate your comments, and we'd love to hear your voice: drop us a line and share your thoughts with us!

  Adyen Support Team

Migration last update

Version

Date

Changes

4.1 2016-21-03

Changes in Import Payment Details For Recurring Payments.

Version

Date

Changes

4.1 2016-21-03

Changes in Import Payment Details For Recurring Payments.

4.0.1 2015-27-10

Fixes

4.0. 2015-22-10
  • Documentation migration from PDF to web-based online deliverable as main distributable asset.
  • Versioning: version reset and adoption of semantic versioning as per v. 4.0.0.
  • Manual redesign to improve readability, navigation, content search.

1.0.4

2015-03-10

  • Modifying reference to correct external manual.

1.0.3

2014-08-28

  • Added support for importing PayPal payment details for recurring payments.
  • Added support for importing SEPA Direct Debits details for recurring payments.

1.0.2

2011-06-21

Added support for importing direct debit payment details for recurring payments.

1.0.1

2010-07-26

Added General File Format section.

1.0

2010-07-19

Initial version.

General File Format

You can import existing payment details for recurring payments and referral data for fraud checks into the Adyen payment system. The files containing the import data should be delivered in CSV (Comma Separated Values) format as per RFC 4180 with the exception that no multi-line fields are allowed and that a variable number of fields per line are used.

Also, note that no header record is used and each line is prefixed by the payment method or type of referral list. An import file can only contain one type of data, recurring, or referral data.

If both types of data need to be imported into the Adyen payment system two separate files need to be created. To support non-western characters make sure the files are in UTF-8 format.

For security purposes, encrypt the files using PGP. If the file size permits, maximum amount of lines per file is 100.000. You can send the encrypted files through email.

Import payment details for recurring payments

You can import existing payment details into the Adyen payment system to be used for subsequent recurring payments. The payment details can be listed in a CSV file where each line is prefixed by the payment method. The file should be encrypted and signed by you with one of the keys provided by support.

You need to request access from support to provide this file, contact the Adyen Support Team to know more.

The columns required per payment method are:

Field Required Description
MerchantAccount (tick) The merchant account you want to process this payment with.
ShopperEmail (tick) The email address of the shopper.
ShopperReference (tick) An Id that refers uniquely to the shopper (e.g. a customer Id in a shopping cart system).
RecurringContract (tick)

This parameter defines what type of recurring contract is used. For the normal recurring initial payments, the RECURRING/ONECLICK value should be used.

For payout, the value should be PAYOUT.

recurringContract should be enclosed in double quotes. Eg."RECURRING,ONECLICK"

EchoData (error) This is a pretext. It can be used for providing data, for example, previous tokens for credit card data.

Card

The below fields are mandatory if the payment method is Card.

ExpiryMonth/ ExpiryYYMM/ExpiryMMYY/ExpiryMMYYYY/ExpiryYYYYMM

(error)

The expiration date's month written as a 2-digit string.

You can choose the format you want to enter the date in.

ExpiryYear (error)

Enter the year separately in this field if you choose to enter the month using ExpiryMonth.

The expiration date's year is written in full (e.g. 2008).

CardNumber (error) The card number.
OwnerName (tick) Name of the account holder.

SEPA

The below fields are mandatory if the payment method is SEPA.


BankLocation (error) Bank location of the shopper.
BankName (error) Bank name of the shopper.
BankLocationId (error) ID of the bank location of the shopper.
BankAccountNumber (error) Account number of the bank.
CountryCode (error) The two letter county code in which the bank (branch) is located.
Iban (error) IBAN of the bank account.
OwnerName (tick) Name of the account holder.

Paypal

The below fields are mandatory if the payment method is Paypal.


BillingAgreementId (error)

ID of the billing agreement. Required for recurring payments, it must start with 'B-'.

Type of identifier. This is a possible value depending on the type of recurring contract, if not being used should be identified as null.

PayerId (error)

ID of Paypal account. Required for payout payments.

Type of identifier. This is a possible value depending on the type of recurring contract, if not being used should be identified as null.

The order of columns is not mandatory and these columns can be skipped according to the payment method. You should mention the header for the system to identify the field.

The following is an example file with two payment details:

MerchantAccount,ShopperEmail,ShopperReference,RecurringContract,EchoData,OwnerName,ExpiryMonth,ExpiryYear,ExpiryYYMM,ExpiryMMYY,ExpiryMMYYYY,ExpiryYYYYMM,CardNumber,Iban,CountryCode,BankLocation,BankName,BankLocationId,BankAccountNumber,BillingAgreementId,PayerId
TestMerchant,mark1test@adyen.com,mark1,RECURRING,MasterCard Bijenkorf NL,D.N. Mater,8,2018,,,,,5100081112223332,,,,,,,,
TestMerchant,mark30test@adyen.com,mark30,"RECURRING,ONECLICK,PAYOUT",,P.Pal,,,,,,,,,,,,,,,B2308952346426
TestMerchant,mark75test@adyen.com,mark78,RECURRING,,B.Dalby,,,,,,,,,NO6012341234561,NO,,,,,

Output

You receive an output file from Adyen support after the import. 

Field Description

Status

Status of the migration.

PaymentMethodVariant

Type of payment method. See more info about this field here.

ShopperReference

An Id that refers uniquely to the shopper (e.g. a customer Id in a shopping cart system).

RecurringDetailReference

The reference that uniquely identifies the recurring detail.

Alias

Card alias.

ExpiryMonth

The expiration date's month written as a 2-digit string, padded with 0 if required (e.g. 03 or 12).

ExpiryYear

The expiration date's year is written in full (e.g. 2008).

Bin

Bank Identification number.

CardSummary

Card summary

Echodata

This is a pretext. It can be used for providing data, for example, previous tokens for credit card data.

StatusMessage

The reason is returned in case of a failure.
status,paymentMethodVariant,shopperReference,recurringDetailReference,alias,expiryMonth,expiryYear,bin,cardSummary,echodata,statusMessage
Success,amex,HENSHAP,2914485358484074,H116006232956221,2,2017,374291,1002,,
Success,amex,LOCKL1,2914546007913217,E167970689307238,2,2020,374293,1006,,
Success,amex,HICKMAGP,2714583830042296,M212359999703856,8,2017,374290,1009,,
Success,amex,SUTHM1,2714583830042304,A129651585108480,7,2016,374297,1005,,

Import Data Into Referral Lists

You can import referral data into the Adyen Payment System to be placed on several referral lists used for fraud checks. The details can be listed in a CSV file where each line is prefixed by the type of referral data. Below you can find the different columns required per referral list:

Card

For card data the following columns are required:

Field Required Description
Fixed value: card (tick) Record type identifier.

merchantAccountCode

(tick)

The merchant account name.

cardNumber (tick) The card number.
description (tick)

 A description of the item, e.g. transaction ID of the original fraudulent transaction.

flag (tick)

You can perform the following actions:

  • trust
  • block
  • delete

Shopper Name

For shopper data the following columns are required:

Field Required Description
Fixed value: shopperName (tick) Record type identifier.

merchantAccountCode

(tick)

The merchant account name.

shopperName (tick)

Name of the shopper.

description (tick)

 A description of the item, e.g. transaction ID of the original fraudulent transaction.

flag (tick)

You can perform the following actions:

  • trust
  • block
  • delete

Shopper Email

For shopper email data the following columns are required:

Field Required Description
Fixed value: shopperEmail (tick) Record type identifier.

merchantAccountCode

(tick)

The merchant account name.
shopperEmail (tick)

A shopper's email address.

description (tick)

 A description of the item, e.g. transaction ID of the original fraudulent transaction.

flag (tick)

You can perform the following actions:

  • trust
  • block
  • delete

Shopper IP

For shopper IP the following columns are required:

Field Required Description
Fixed value: shopperIP (tick) Record type identifier.

merchantAccountCode

(tick)

The merchant account name.

shopperIP (tick)

The IP address the shopper used to carry out the transaction.

description (tick)

 A description of the item, e.g. transaction ID of the original fraudulent transaction.

flag (tick)

You can perform the following actions:

  • trust
  • block
  • delete

Shopper Reference

For shopper reference the following columns are required:

Field Required Description
Fixed value: shopperReference (tick) Record type identifier.

merchantAccountCode

(tick)

The merchant account name.

shopperReference (tick)

A shopper's reference, which is the unique identifier for a shopper.

description (tick)

 A description of the item, e.g. transaction ID oforiginalfraudulent transaction.

flag (tick)

You can perform the following actions:

  • trust
  • block
  • delete

Shopper Address

For shopper address the following columns are required:

Field Required Description
Fixed value: shopperAddress (tick)   Record type identifier.

merchantAccountCode

(tick)

The merchant account name.

street (tick)

Street name.

houseNumberOrName (tick)

House number or name.

city (tick) Name of the city
postalCode (tick) Postal code.
stateOrProvince (tick) State or province name.
countryCode (tick) Country code
flag (tick)

You can perform the following actions:

  • trust
  • block
  • delete

Example File

The following is an example file with three lines of referral data:

card,YourMerchantAccount,4111111111111111,"Initial load, 2010-01-01",block
shopperName,YourMerchantAccount,"S. Hopper","Initial load, 2010-01-01",trust
shopperEmail,YourMerchantAccount,s.hopper@test.com,"Initial load, 2010-01-01",trust
shopperIP,YourMerchantAccount,201.44.22.11,"Initial load, 2010-01-01",block
shopperReference,YourMerchantAccount,YourMerchantReference,"Initial load, 2010-01-01",delete
shopperAddress,YourMerchantAccount,StreetName,58,Amsterdam, 2116 E,AMS,NL,trust