Tools-2 icon

Import payment details for recurring payments

Learn how to migrate your payment data.

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 -x- 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 -x- The email address of the shopper.
ShopperReference -white_check_mark- 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 -x-

The type of recurring contract. Possible values:

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 -x- Name of the account holder.
OwnerNamePostfix -x- The surname of the account holder. Use this if you want to pass the First Name and Surname in two separate fields.
IsPreferredPaymentMethod -x- In this field you can specify if a payment method represents the preferred payment method for a shopper.
EchoData -x- 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 -x- 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:

The order of fields is not mandatory and fields can be skipped depending on the payment method. Use the first line of your CSV file to define the field names and their order on other lines.

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 -white_check_mark- The card number.
Expiry date -white_check_mark- 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)
-white_check_mark- 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)
-white_check_mark- 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)
-x- 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 -x- The number or name of the house. You can omit this and include the data in BillingStreet.
BillingStreet -x- The street name.
BillingCity -x- The city name.
BillingStateOrProvince -x- 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 -x- The postal code with a maximum of 5 characters for USA and a maximum of 10 characters for any other country/region.
BillingCountry -x- 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 -white_check_mark- The IBAN of the bank account.
OwnerName -white_check_mark- The name of the account holder.
BankLocation -x- The location of the shopper's bank.
BankName -x- The name of the shopper's bank.
BankLocationId -x- The ID of the bank location of the shopper.
BankAccountNumber -x- The account number of the bank.
CountryCode -x- The two-letter country code for the country/region where the bank (branch) is located.
ShopperReference -x- An ID that refers uniquely to the shopper. For example, a customer ID in a shopping cart system.
SepaMandateId -x- 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 -white_check_mark- The ABA routing transit number of the account.
BankAccountNumber -white_check_mark- The US bank account number from which the payment will be debited.
OwnerName -white_check_mark- Name on the bank account.
CountryCode -white_check_mark- US
BillingHouseNumberOrName -white_check_mark- The number or name of the house. You can omit this and include the data in BillingStreet.
BillingStreet -white_check_mark- The street name.
BillingCity -white_check_mark- The city name.
BillingStateOrProvince -white_check_mark- A valid 2-character abbreviation for the state.
BillingPostalCode -white_check_mark- The postal code.
BillingCountry -white_check_mark- 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 -white_check_mark- 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 -x- The email address of the Paypal account that set up the billing agreement ID with Paypal.
PayerId -x- 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

Not all Klarna payment methods or countries/regions support recurring payments. For information about recurring payments and tokenization at Klarna, refer to Klarna's documentation.

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 -white_check_mark- ID of the shopper's Klarna customer token. For more information, see Klarna's documentation.
KlarnaVariant -white_check_mark- 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 -white_check_mark- 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 -white_check_mark- The old or existing shopper reference which is present in the CSV file, from your other payments vendor.
newShopperReference -white_check_mark- 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.

To provide more information about the migration, we will start adding new fields to the output file. Make sure that your parsing logic can handle changes such as new headers.

The output file has the following fields:

Field Description

status

The status of the migration. Possible values:

  • Success No issues. Line is imported correctly.
  • Skipped This typically happens if there is essential data missing in the line. For example CardNumber or ExpiryYear is missing.

paymentMethodVariant

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

shopperReference

An ID that refers uniquely to the shopper. For example, a customer ID in a shopping cart system.

recurringDetailReference

The reference that uniquely identifies the recurring detail.

alias

The Adyen alias of the card.

Example: H167852639363479

expiryMonth

The card expiry month.
Format: 1 or 2 digits.
For example:

  • 3 = March
  • 11 = November

expiryYear

The card expiry year.
Format: 4 digits. For example: 2018.

bin

The Bank Identification Number (BIN) of a card, which is the first six digits of a card number.
Example: 521234

cardSummary

The last four digits of a card number.

issuerCountryCode

The country/region of the issuer. Format: 2-letter ISO code.

echodata

Data that you specified in the EchoData field of your CSV file, such as previous tokens for credit card data.

statusMessage

If the card could not be imported, the reason why the import failed.

fundingSource

The funding source of the card. Example: DEBIT, CREDIT, or PREPAID.

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

Field Description

auxEchodata

Data that you specified in the AuxEchoData field of your CSV file.

isPreferredPaymentDetail

Based on the field IsPreferredPaymentDetail of your CSV file.

networkTxReferenceStatus

Import status of the networkTxReference specified in your CSV file. Possible values: NOT_PROVIDED, IMPORTED, NOT_VALID

billingAddressStatus

Import status of the Address fields specified in your CSV file. Possible values: NOT_PROVIDED, IMPORTED, NOT_VALID

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,,,,,