This guide covers the initial migration of Adyen Shopper References and Shopper Token data into Microsoft Dynamics 365 Business Central using the TAPP Adyen extension. Migration is handled through the Adyen Shopper Data Migration page and follows a reconciliation workflow before data goes live in BC.
Overview
Migration covers two distinct data types:
| Data Type | Description |
| Shopper References | Links an Adyen shopper identity to a BC Customer record. |
| Shopper Tokens | Payment method tokens (cards, SEPA mandates, etc.) associated with a shopper. |
There are three options available for importing this data:
| Option | What It Does | Standalone? |
| Option 1 | Imports both Shopper References and Shopper Tokens in one step using the Adyen CSV export. | Yes |
| Option 2 | Imports Shopper References and/or Tokens directly via a BC Configuration Package. | Yes |
| Option 3 | Fetches Shopper Token data from the Adyen API. | Requires shopper references to already be in BC (via Option 1 or Option 2). |
| 📝 Note: Option 1 and Option 2 are fully self-contained. Option 3 is the only option that has a prerequisite — shopper references must already exist in BC before token data can be fetched from the API. |
Prerequisites
- The TAPP Adyen extension must be installed and configured.
- At least one Adyen Merchant must be set up in BC (searchable via the BC search bar as Adyen Merchants).
- API credentials must be configured in Adyen Parameters if using the API-based token fetch method (Option 3).
- The user must have read permissions on the Adyen Merchant table.
Option 1 — Migrating Shopper References and Shopper Tokens via CSV
This is the recommended approach for a full initial migration. The Adyen CSV export contains both Shopper Reference data and Shopper Token data, and both are imported in a single file upload. This option is fully self-contained — after completing it you do not need to run Option 3 unless you want to refresh token data from the API at a later point.
Step 1 — Open the Adyen Shopper Data Migration Page
Search for Adyen Shopper Data Migration in the BC search bar (Alt + Q) and open the page.
Step 2 — Select the Adyen Merchant
Use the Adyen Merchant filter at the top of the page to select the merchant account you are migrating data for. The merchant description will populate automatically.
| 📝 Note: Only records for the selected merchant will be shown in the list. |
Step 3 — Create a New Migration Record
Click Create New Shopper Data Migration in the process action bar.
This creates the following records in a single action:
- A Shopper Sync Reconciliation header — for shopper reference matching.
- A Shopper Token Sync Reconciliation header — for token data.
- A Migration Line linking both reconciliation records.
The new migration line will appear in the list with both Adyen Shopper Sync Reconciliation No. and Adyen Shopper Token Sync Reconciliation No. populated.
Step 4 — Upload the Adyen CSV File
- Select the migration line you just created and click Upload Records from CSV.
- A file picker dialog will open. Select the CSV file provided by Adyen containing the shopper and token data.
The system will parse the CSV and populate:
- Shopper Sync Lines (one per CSV row) with: Shopper Reference, Email, Full Name, Post Code.
- Shopper Token Sync Lines (one per CSV row) with: Card Alias, Expiry Month/Year, Mandate ID/Provider/Status/Currency, Payment Method type, Shopper Reference.
The Migration Line will be updated with the following totals:
- Total No. of Records
- Total No. of Shopper Sync Records
- Total No. of Shopper Token Records
| 📝 Note: The CSV parser skips the first two rows (treated as headers). Rows are expected to follow the standard Adyen shopper data export format. |
The key columns used from the CSV are:
| Column | Field Name | Description |
| 2 | Shopper Reference | The unique Adyen shopper identifier. |
| 3 | Shopper Email | Used for customer matching during reconciliation. |
| 5 | Payment Method Sub-Type | The payment method type (e.g. card scheme, SEPA). |
| 7 | Card Expiry Month | Expiry month of the stored card. |
| 8 | Card Expiry Year | Expiry year of the stored card. |
| 9 | Shopper Full Name | Used for customer matching during reconciliation. |
| 23 | Post Code | Used for customer matching during reconciliation. |
| 27 | Card Alias | The token alias for the stored card. |
| 41 | Mandate Provider ID | The provider identifier for SEPA mandates. |
| 42 | Mandate ID | The unique identifier for the SEPA mandate. |
| 43 | Mandate Status | Current status of the SEPA mandate. |
| 49 | Mandate Currency | Currency associated with the SEPA mandate. |
Step 5 — Process the Shopper Sync Reconciliation
Click the drill-down link on Adyen Shopper Sync Reconciliation No. to open the reconciliation record. From the Shopper Sync Lines sub-page, run the following actions in order:
1. Suggest Actions
The system attempts to match each Adyen shopper to a BC Customer by comparing email address, post code, and name. A match percentage and suggested action are set on each line:
- A 100% match by email sets a Match suggested action automatically.
- Lines where the shopper reference already exists in BC are marked as Synced with no action needed.
- You can run Suggest Actions for the Current Record (selected lines) or All Records (runs as a background session).
2. Review Lines
Inspect unmatched or ambiguous lines. Where the automatic suggestion is incorrect, manually set the Manual Match BC Customer No. field on the line to override the suggestion.
3. Accept Suggest Actions
Accept the suggested or manually set matches. This can be done per record or for all records.
4. Process Suggest Actions
Executes the accepted matches, creating or updating Adyen BC Shopper records linked to the matched BC Customers.
| 💡 Tip: Once all lines show Synced = Yes, the shopper reference reconciliation is complete and you can proceed to Step 6. |
Step 6 — Process the Shopper Token Sync Reconciliation
Click the drill-down link on Adyen Shopper Token Sync Reconciliation No. to open the token reconciliation record.
Follow the same Suggest → Accept → Process workflow on the token sync lines to import the token data into the Adyen BC Shopper Token table in BC.
Option 2 — Migrating Shopper References and/or Tokens via Configuration Package
Shopper Reference records (and optionally Token records) can be imported directly into BC using a Configuration Package. This is a fully standalone option suitable when you already have the data in a structured format and want to load it without going through the reconciliation workflow.
The relevant tables to include in the configuration package are:
| Table ID | Table Name | Description |
| 71082896 | BFTAdyenBCShopperV2 | Adyen BC Shopper — links an Adyen Shopper Reference to a BC Customer and Merchant. |
| 71082895 | BFTAdyenBCShopperTokenV2 | Adyen BC Shopper Token — stores the payment method tokens associated with a shopper. |
You can import either table or both depending on your data availability:
- Import table 71082896 only when you have shopper reference data but intend to fetch token data later via the API (Option 3).
- Import both tables when you have both shopper reference and token data available — this makes the option fully self-contained with no need to run Option 3.
| 📝 Note: When importing token records into table 71082895, ensure the ShopperReference field on each token record matches an existing record in table 71082896. |
Option 3 — Fetching Token Data via API
This option retrieves token data directly from the Adyen API using the Get Adyen Shopper Tokens action. It is useful for fetching tokens after shopper references have been imported via Option 2, or for refreshing and supplementing token data after any initial migration.
| ⚠️ Prerequisite: This is the only option that is not fully standalone. The Adyen Shopper References for the relevant customers must already exist in BC, imported via either Option 1 (CSV migration workflow) or Option 2 (Configuration Package import into table 71082896). |
Option 3a — From the Customer List (Bulk)
- Navigate to the Customers list.
- Select one or more customer records using the checkbox column to multi-select, or apply a filter to scope the list.
- Open the Adyen action group in the action bar.
- Click Get Adyen Shopper Tokens.
- A report request page will open with the customer filter pre-populated. Click OK to run.
The report iterates over each selected customer, finds their linked Adyen Shopper records, and calls the Adyen API (GET /storedPaymentMethods) for each shopper reference. Retrieved tokens are upserted into the Adyen BC Shopper Token table in BC.
Option 3b — From the Customer Card (Single Customer)
- Open a Customer Card.
- Open the Adyen action group in the action bar.
- Click Get Adyen Shopper Tokens.
This performs the same API call as Option 3a but scoped to the single customer.
| 💡 Tip: Use View Adyen Shopper Tokens from the Customer Card to verify which tokens have been imported for a given customer after running this action. |
Summary — Which Method to Use?
| Scenario | Recommended Option |
| Full initial migration from a previous Adyen integration | Option 1 — imports both shopper references and tokens in one step. |
| Shopper reference and token data available in structured format | Option 2 — Config Package into tables 71082896 and 71082895. |
| Shopper reference data available in structured format, tokens to be fetched later | Option 2 (table 71082896 only), then Option 3. |
| Shopper references already in BC, tokens not yet imported | Option 3 — API fetch via Customer List or Customer Card. |
| Partial re-sync or refresh of tokens post-migration | Option 3 — API fetch, filter to specific customers. |
| Single customer token refresh | Option 3b — Customer Card. |
Troubleshooting
| Issue | Resolution |
| Migration line shows 0 records after CSV upload | Ensure the CSV uses commas as delimiters and has at least 3 rows (2 header rows + 1 data row). |
| Shopper Sync lines have no suggested action | Check that the Adyen shopper email in the CSV matches the email on the BC Customer record. |
| Get Adyen Shopper Tokens returns no tokens | Verify that the Adyen Shopper Reference exists in the Adyen BC Shopper table for that customer and that API credentials are configured correctly in Adyen Parameters. |
| Lines remain unsynced after processing | Check the Error Text column on the sync line for a specific error message. |
| Merchant not selectable | Ensure at least one Adyen Merchant record exists and the user has read permission on the Adyen Merchant table. |
Related Articles
- Generate an Adyen Payment Request
- Adyen Auto Rescue and Retrying Failed Payments
- Issue a Refund for an Adyen Payment
- Parameters