Import payment details for recurring payments

To migrate recurring payment contracts from another payment service provider to the Adyen payments platform, you need to provide us with a CSV file containing the recurring payment details. We will then import this file. After importing, we will send you an output file with the migration results.

Input file format

The files containing the data to be imported should be formatted as follows:

1. Create a file in CSV (Comma Separated Values) format as per RFC 4180, in accordance with the following requirements:

   • The first line contains the names of the fields. You do not have to use all field names and you do not have to use them in the same order as listed on this page.
   • Each subsequent line contains the fields for a single recurring contract. In other words: Each recurring contract is on a separate line.
   • If a field doesn't apply to the recurring contract that the line describes, specifying a value is skipped.
   • Field names and values are case-sensitive.
   • Multi-line fields are not allowed.
   • The maximum file length is 1,000,000 lines.
   • The maximum file size is 1 GB.

2. Save the file in UTF-8 format (to support non-western characters).

3. Encrypt the file using the PGP public key provided to you by either our Support Team, or your Adyen contact.

   For more information, see our PGP encryption documentation.

4. Send the file to Adyen.

The following is an example input file with four recurring contracts:

MerchantAccount,ShopperEmail,ShopperReference,RecurringContract,EchoData,OwnerName,ExpiryMonth,ExpiryYear,ExpiryYYMM,ExpiryMMYY,ExpiryMMYYYY,ExpiryYYYYMM,CardNumber,Iban,CountryCode,BankLocation,BankName,BankLocationId,BankAccountNumber,BillingAgreementId,PayerId,BillingStreet,BillingCity,BillingStateOrProvince,BillingPostalCode,BillingCountry
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,,,,,,,,,,,,,,B-2308952346426,AK5HCWWRUV2KL,,,,,
TestMerchant,mark75test@adyen.com,mark78,RECURRING,,B.Dalby,,,,,,,,NO6012341234561,NO,,,,,,,,,,,
TestMerchant,mark2test@adyen.com,mark2,RECURRING,,B.Dalby,,,,,,,,,US,,,121000358,123456789,,,123 Test Street,San Francisco,CA,94000,US

Input file fields

The fields for recurring contracts are:

Field	Required	Description
MerchantAccount		The merchant account you want to process payments with. If you are unable to provide this information in your CSV file, contact our Support Team.
ShopperEmail		The email address of the shopper.
ShopperReference		An ID that refers uniquely to the shopper. For example, a customer ID in a shopping cart system. Minimum length: three characters. Note that the value is case-sensitive. Do not include personally identifiable information (PII), such as name or email address.
RecurringContract		The type of recurring contract. Possible values: ONECLICK – Payment details can be used to initiate a one-click payment, where the shopper enters the card security code (CVC/CVV). RECURRING – Payment details can be used without the card security code to initiate card-not-present transactions. PAYOUT – Payment details can be used to make a payout. Values can also be concatenated with a comma. But when doing so, the combined value needs to be enclosed in double quotes, for example "RECURRING,ONECLICK". If you are unable to provide this information in your CSV file, contact the Support Team.
OwnerName		Name of the account holder.
OwnerNamePostfix		The surname of the account holder. Use this if you want to pass the First Name and Surname in two separate fields.
IsPreferredPaymentMethod		In this field you can specify if a payment method represents the preferred payment method for a shopper.
EchoData		In this field you can specify data you want to be echoed back in the output file, such as previous tokens for credit card data. The Adyen payments platform does not use this data.
AuxEchoData		Same as EchoData , for use when you need more than one data field to be echoed back in the output file. You can ask our Support Team to configure and enable this for the import result file.

Apart from the above fields, the CSV file can have fields for:

• Card data
• Address data
• SEPA recurring payments
• ACH recurring payments
• PayPal recurring payments
• Klarna recurring payments
• Shopper reference re-mapping (optional auxiliary file)

Card fields

When specifying card data, you need to provide:

• Card number.
• Expiry date: month and year of expiry.
  You can use either a combination of fields (ExpiryMonth and ExpiryYear), or a single field to specify both month and year: ExpiryMMYY, ExpiryMMYYYY, ExpiryYYMM or ExpiryYYYYMM.

Data	Required	Description
CardNumber		The card number.
Expiry date		Either a single field or a combination of fields is required. Choose from the following fields. ExpiryMMYY: The month and year of expiry, written as a 4-digit string. For example, 0618 for June 2018. ExpiryMMYYYY:The month and year of expiry, written as a 6-digit string. For example, 062018 for June 2018. ExpiryYYMM: The year and month of expiry, written as a 4-digit string. For example, 1806 for June 2018. ExpiryYYYYMMThe year and month of expiry, written as a 6-digit string. For example, 201806 for June 2018. ExpiryMonthThe month of expiry, written as a 1 or 2-digit string. For example, 6 or 06 for June. Use in combination with ExpiryYear. ExpiryYearThe year of expiry, written as a 4-digit string. For example, 2018. Use this in combination with ExpiryMonth.
networkTxReference (for Visa)		The Visa Transaction ID from the initial transaction where the shopper signed up for a series of Subscription or UnscheduledCardOnFile payments. Visa won't support the static value (Interim Transaction ID) after 31 October 2022. Not providing the Visa Transaction ID might result in soft declines and non-compliance assessment fees.
networkTxReference (for Mastercard)		The Mastercard Trace ID from the initial transaction where the shopper signed up for a series of Subscription or UnscheduledCardOnFile payments. Mastercard won't support the static value (dummy Trace ID) after 19 October 2024. Not providing the Mastercard Trace ID might result in soft declines and non-compliance assessment fees.
networkTxReference (for other card schemes)		For other card schemes besides Visa and Mastercard, we recommend that you send the networkTxReference from the initial transaction where the shopper signed up for a series of Subscription or UnscheduledCardOnFile payments. However, if you do not have the networkTxReference, we will insert a card scheme-compliant static value on your behalf. We will do that until the schemes no longer allow static values.

Address fields

Using the following fields, you can specify a physical address. If one field below is provided, then all other fields from this section are also required.

Field	Required	Description
BillingHouseNumberOrName		The number or name of the house. You can omit this and include the data in BillingStreet.
BillingStreet		The street name.
BillingCity		The city name.
BillingStateOrProvince		For USA or Canada, a valid 2-character abbreviation for the state or province respectively. For other countries/regions any abbreviation with maximum 3 characters for the state or province.
BillingPostalCode		The postal code with a maximum of 5 characters for USA and a maximum of 10 characters for any other country/region.
BillingCountry		A valid value is an 2-character ISO country/region code.

Recurring SEPA payment fields

When specifying SEPA payment details, you always need to provide the IBAN of the bank account and the account holder name.

For third-party payouts, you need to provide all fields listed below, except for the fields SepaMandateId and SepaMandateDateOfSignature. For more information, refer to Payouts to a bank account.

To optionally import SEPA Direct Debit mandates, include the mandate identifier, and the date of the mandate signature.

Field	Required	Description
Iban		The IBAN of the bank account.
OwnerName		The name of the account holder.
BankLocation		The location of the shopper's bank.
BankName		The name of the shopper's bank.
BankLocationId		The ID of the bank location of the shopper.
BankAccountNumber		The account number of the bank.
CountryCode		The code for the country/region where the bank (branch) is located. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
ShopperReference		An ID that refers uniquely to the shopper. For example, a customer ID in a shopping cart system.
SepaMandateId		The SEPA Direct Debit mandate identifier.
SepaMandateDateOfSignature	Required if SepaMandateId is included	The date of the SEPA Direct Debit mandate signature. Format: YYYY-MM-DD. For example: 2019-02-22

Recurring ACH payment fields

When specifying ACH payment details, you need to provide all of the following fields:

Field	Required	Description
BankLocationId		The ABA routing transit number of the account.
BankAccountNumber		The US bank account number from which the payment will be debited.
OwnerName		Name on the bank account.
CountryCode		US
BillingHouseNumberOrName		The number or name of the house. You can omit this and include the data in BillingStreet.
BillingStreet		The street name.
BillingCity		The city name.
BillingStateOrProvince		A valid 2-character abbreviation for the state.
BillingPostalCode		The postal code.
BillingCountry		US

Recurring PayPal payment fields

For third-party payouts, you need to provide all of the following fields. For more information, refer to Payouts to a PayPal account.

Field	Required	Description
BillingAgreementId		ID of the billing agreement. Required for recurring payments and must start with 'B-'. The value depends on the type of recurring contract. If not used, should be identified as null.
PayPalBuyerEmailId		The email address of the Paypal account that set up the billing agreement ID with Paypal.
PayerId		ID of PayPal account. The value depends on the type of recurring contract. If not used, should be identified as null.

Recurring Klarna payment fields

When specifying Klarna payment details, provide all of the following fields. Make sure that you enter a supported combination in the fields KlarnaVariant and KlarnaCountry.

Field	Required	Description
KlarnaTokenId		ID of the shopper's Klarna customer token. For more information, see Klarna's documentation.
KlarnaVariant		The Klarna payment method variant. Possible values: klarna_paynow (for Klarna - Pay Now) klarna (for Klarna - Pay later) klarna_account (for Klarna - Pay over time)
KlarnaCountry		A valid 2-character ISO country code.

Shopper reference re-mapping (optional auxiliary file)

If you want to change the shopper references upon importing, you can send an auxiliary shopper reference re-mapping file, in addition to the payment detail file.
The format of the re-mapping file should include both of the following columns.

Field	Required	Description
oldShopperReference		The old or existing shopper reference which is present in the CSV file, from your other payments vendor.
newShopperReference		The shopper reference under which the tokens will be stored, after they are imported into the Adyen payments platform.

For example, the file might look like this:

oldShopperReference,newShopperReference
ref_1,new_ref_1
ref_2,new_ref_2
...

Output file

When we have imported your CSV file, we'll send you an output file with the migration results. If you need an encrypted output file, provide your public key to our Support Team.

The output file has the following fields:

You can also include the following fields in the output file. To receive these fields, contact our Support Team.

The following is an example output file, without additional fields, with four payment details successfully migrated:

   status,paymentMethodVariant,shopperReference,recurringDetailReference,alias,expiryMonth,expiryYear,bin,cardSummary,issuerCountryCode,echodata,statusMessage,fundingSource
    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,,,,,