> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Token Migration

> Import tokens from other vault providers into Payrails securely while maintaining PCI DSS compliance. Export your payment data when needed.

## Token Migration Overview

Moving payment tokens between vault providers can be complex, but Payrails makes it straightforward while maintaining the highest security standards. Whether you're migrating **to** Payrails from another provider or **from** Payrails to elsewhere, we ensure PCI DSS compliance throughout the process.

### Why Migrate Tokens?

Token migration offers significant benefits for both merchants and customers:

* **Zero customer friction** - Customers can continue using their stored payment methods without re-entering card information
* **Seamless PSP transitions** - Existing payment service provider configurations remain functional during migration
* **Enhanced control** - Consolidate multiple tokens for the same payment instrument across providers
* **Improved conversion** - Leverage Payrails' routing capabilities to select the optimal token for each transaction

<Note>
  **How Payrails Handles Duplicates**

  When importing payment instruments, Payrails automatically performs uniqueness checks and groups different representations of the same card into a single instrument with multiple provider tokens. This enables intelligent routing to maximize payment success rates.
</Note>

***

### Import Tokens to Payrails

#### Before You Begin

Token migration requires coordination between three parties: **you** (the merchant), **Payrails**, and your **current vault provider**. We'll guide you through the entire process to ensure PCI DSS compliance.

#### Migration Process

<Accordion title="Step 1: Initiate Migration Request">
  Contact your current vault provider to begin the token export process. Requirements vary by provider:

  * **Dashboard-based providers**: Submit migration request through merchant portal
  * **Email-based providers**: Send formal migration request to support team
  * **Custom process**: Follow provider-specific procedures

  Your Payrails account representative will provide guidance for your specific provider and supply our **PCI Attestation of Compliance (AOC)** as required.
</Accordion>

<Accordion title="Step 2: Prepare Export Data">
  Work with your current provider to export token data in a Payrails-compatible format. The export typically includes:

  * **Token identifiers** from the current provider
  * **Associated payment card data** (encrypted/tokenized)
  * **Metadata** such as customer IDs, expiration dates, and card types

  You'll also need to provide a **customer mapping file** to ensure proper instrument-to-customer relationships. Your account representative will specify the exact format requirements.
</Accordion>

<Accordion title="Step 3: Secure Data Transfer">
  All data transfers use secure protocols and encryption:

  * **File Transfer Protocol**: Encrypted channels with provider-specific security keys
  * **Data Encryption**: Provider supplies encryption keys to Payrails for secure decryption
  * **Access Control**: Limited to authorized personnel only

  Your Payrails representative coordinates all security requirements with the source provider.
</Accordion>

<Accordion title="Step 4: Validation & Import">
  Once we receive your token data, Payrails performs comprehensive validation:

  1. **Data integrity checks** - Verify file completeness and format compliance
  2. **Token validation** - Confirm token validity and associated metadata
  3. **Instrument creation** - Generate Payrails payment instruments linked to imported tokens
  4. **Relationship mapping** - Connect instruments to your customers using provided mapping data

  See our [Instruments guide](/docs/resources/manage-instruments) for details on how payment instruments and tokens work together.
</Accordion>

<Accordion title="Step 5: Import Results & System Updates">
  After successful migration, you'll receive a **results file** containing:

  * **New Payrails instrument IDs** for each migrated payment method
  * **Token mappings** between old and new token identifiers
  * **Migration status** for each processed record

  Import this file into your systems to update customer payment method references and complete the migration process.
</Accordion>

<Check>
  **Migration Complete**

  Your payment tokens are now secured in Payrails' PCI DSS-certified vault. For questions or assistance, contact your account representative or Payrails support.
</Check>

***

### Export Data from Payrails

#### API-Based Exports

For programmatic access to your vault data, use these Payrails APIs:

**Individual Token Export**

```
GET /tokens
```

Use the [Search & List Tokens](/reference/listtokens) API with filtering and pagination to export specific token sets.

**Bulk Instrument Export**

```
GET /instruments
```

The [Search & List Instruments](/reference/listinstruments) API provides comprehensive instrument data with optional token inclusion.

**Combined Export**

```
GET /instruments?includeTokens=true&filter[holderReference]=customer-123
```

Add the `includeTokens=true` parameter to include token details in instrument responses. Use filtering to manage response size and improve performance.

<Warning>
  **Performance Considerations**

  Large exports can impact performance. Use filtering (`filter[holderReference]`, `filter[createdAt]`, etc.) and pagination (`page[size]`, `page[number]`) to optimize response times.
</Warning>

#### Bulk Migration Support

For large-scale migrations **from** Payrails to another provider:

1. **Contact Payrails Support** - We'll coordinate the migration process with your new provider
2. **PCI Compliance** - All transfers maintain PCI DSS compliance requirements
3. **Data Security** - Encrypted transfers using secure protocols
4. **Provider Coordination** - We work directly with your new vault provider for seamless migration

<Note>
  **PCI Compliance Note**

  By default, full PAN (Primary Account Number) data is not included in standard exports to maintain PCI compliance. If you require full PAN access, contact our team to discuss the specialized process we follow in accordance with PCI DSS requirements.
</Note>

***

### Need Help?

* **Account Questions**: Contact your dedicated Payrails account representative
* **Technical Support**: Reach out to [Payrails Support](mailto:support@payrails.com)
* **Implementation Guidance**: Check our [API Reference](/reference/) and [Instruments Documentation](/docs/resources/manage-instruments)


## Related topics

- [Frequently Asked Questions](/docs/token-vault/frequently-asked-questions.md)
- [Self-served migration of card data from PSPs](/docs/token-vault/token-migration/self-serve-migration.md)
- [Agent Runbook - v6 Migration](/docs/orchestration/checkout-sdks/web/v6-migration/agent-runbook-v6-migration.md)