Token Migration - Yuno API Documentation

Overview

Token migration transfers card numbers from your existing payment processor to Yuno’s secure vault, generating new vaulted_token values for each card. This ensures continuity for your customers. They can keep using their saved cards without re-entering payment information. The process involves three main steps:

You request the data export from your current payment processor.
Yuno collaborates with your provider to securely import card data.
You use Yuno’s API to map provider tokens to Yuno vaulted_tokens.

What Can Be Migrated

Data Type	Migratable	Process
Vaulted card tokens	Yes	PGP-encrypted transfer via SFTP
Customer records	Yes	API batch import
Subscription data	Yes	Manual or API-assisted recreation
Transaction history	Partial	Reference data only (not re-processable)
Dispute records	No	Historical records remain with previous processor

Card token migration is the most critical component. It allows existing customers to continue using their saved cards without re-entering card details or going through a new enrollment flow.

Alternative payment methods such as Mercado Pago Wallet Connect or Bancolombia Tokenbox may have technical limitations that restrict migration. Contact Yuno support to assess eligibility before starting.

Step 1 & 2: Importing Cards from Your Gateway

Merchant Responsibilities

You are responsible for:

Contacting your current gateway and requesting a payment method data export.
Following your provider’s specified export protocols.
Managing all communication with the exporting gateway throughout the migration.
Obtaining customer subscription information directly from the exporting entity.

Secure Transfer Protocol

All migration data is encrypted using PGP keys and transferred via SFTP (Secure File Transfer Protocol).

Requirements You Must Provide

Requirement	Details
Public SSH key	4096-bit RSA key for SFTP access
Outbound IPs	Your server IPs that will connect to the SFTP endpoint
Template file	A file showing your data structure with mandatory fields

Generate your SSH key with:

ssh-keygen -t rsa -b 4096 -C "your-email@company.com"

Mandatory Fields in the Migration File

The data export file from your current provider must include these fields for each card:

Field	Description
Cardholder name	Full name as it appears on the card
Expiration date	Card expiry (MM/YY or MM/YYYY)
Card number (PAN)	Full primary account number
Card ID	The provider’s unique identifier for the card

Yuno does not validate expiration dates during credit card import. Ensure your exported data includes accurate expiry dates to avoid issues with future transactions.

PGP Encryption Key

All sensitive migration data must be encrypted with Yuno’s PGP public key before transfer.

Property	Value
Email	security-migrations@y.uno
Purpose	Encrypting sensitive data (production environment)
Created	22 Nov 2024
Expires	22 Nov 2026
Key ID	`73D3D88A`
Key length	4096 bits
Algorithm	RSA
Fingerprint	`5160 7134 4C00 D270 93FB C450 19ED AACD 73D3 D88A`
Download	yuno-pgp-production.asc

Yuno PGP Public Key

Data Validation Before Import

Before Yuno begins the import, provide the following to Yuno Support:

Information	Purpose
External identifier name	The field name your provider uses as the unique card identifier
Approximate count	Number of payment methods being migrated
Known data gaps	Any missing data (e.g., missing cardholder names, expiration dates)

Step 3: Client-Side Implementation

After Yuno imports the card data, you complete the migration via the Yuno API by adding customers and enrolling payment methods.

Required Data Parameters

Parameter	Description
`account_id`	Your Yuno account identifier
`merchant_customer_id`	Your internal customer ID
`first_name`	Customer’s first name
`last_name`	Customer’s last name
`email`	Customer’s email address
`country`	ISO 3166-1 alpha-2 country code
`document_number`	Customer’s tax/identity document number
`document_type`	Document type (e.g., `CPF`, `CNPJ`, `CC`)
`payment_method_type`	Type of payment method (e.g., `CARD`)
`payment_method_id`	The provider’s original payment method identifier
`vaulted_token`	The Yuno token generated during import

Customer Import

Import customer records using the Customers API:

POST /v1/customers
{
  "merchant_customer_id": "your_customer_id_001",
  "first_name": "Dee",
  "last_name": "Hock",
  "email": "customer1@example.com",
  "country": "US"
}

Enroll Migrated Payment Methods

Link migrated tokens to customers by enrolling the payment methods:

POST /v1/customers/{customer_id}/payment-methods
{
  "payment_method_type": "CARD",
  "vaulted_token": "tok_yuno_abc123"
}

How Token Migration Works

Token Mapping File

After migration, Yuno provides a mapping file linking source tokens to Yuno tokens:

{
  "migrations": [
    {
      "source_token": "tok_source_001",
      "yuno_token": "tok_yuno_abc123",
      "status": "MIGRATED",
      "card_last_four": "4242",
      "card_brand": "VISA"
    },
    {
      "source_token": "tok_source_002",
      "yuno_token": "tok_yuno_def456",
      "status": "MIGRATED",
      "card_last_four": "1234",
      "card_brand": "MASTERCARD"
    }
  ]
}

Update your database to replace source processor tokens with Yuno tokens using the mapping file. Transactions submitted with old source tokens will fail.

Subscription Migration

Active subscriptions must be recreated in Yuno with the migrated payment method tokens:

Export active subscriptions from your current processor.
Map each subscription’s payment token to the corresponding Yuno token.
Create subscriptions in Yuno with matching billing schedules.
Coordinate the cutover date to avoid duplicate charges.

Schedule subscription migration to occur just after a billing cycle completes at your current processor. This minimizes the risk of duplicate charges and provides a clean transition point.

Data Protection & PCI Compliance

Yuno tokenizes and encrypts all imported card data in compliance with PCI DSS standards. However, as the merchant you remain responsible for:

Managing customer data protection in accordance with local regulations.
Communicating any fees or issues to your customers during the migration process.
Ensuring sensitive data is encrypted before transfer using the provided PGP key.

Migration Timeline

Phase	Duration	Activities
Assessment	1-2 weeks	Data review, scope definition, validation requirements
Setup	1 week	SSH keys, SFTP channels, PGP encryption, API configuration
Token transfer	1-3 days	Depends on volume
Validation	1 week	Test transactions, reconciliation
Cutover	1 day	Traffic switch
Total	3-5 weeks	End-to-end

Best Practices

Start early: Begin the migration assessment well before your planned go-live date.
Run in parallel: Process a percentage of transactions through Yuno while maintaining the old processor as a fallback.
Validate thoroughly: Test migrated tokens with real transactions before full cutover.
Communicate with customers: Inform customers that their payment experience will not change during the migration.
Keep the mapping file: Retain the token mapping file for reference during the transition period.
Pre-validate your data: Check for known gaps (missing names, expired cards) before submitting the migration file to reduce iteration cycles.

Exporting Tokens from Yuno

Yuno provides a secure, PCI DSS-compliant process for exporting tokenized card data from its vault to your systems or a third-party provider.

When to Request an Export

You may request a token export when:

Switching to a different payment processor or tokenization provider.
Managing tokens within your own PCI DSS-certified infrastructure.

Prerequisites

Three requirements must be satisfied sequentially:

Formal Request

Submit a written request to your primary Yuno contact and support@y.uno including:

Authorization from the third party receiving the data
Confirmation of the recipient (internal team or external provider)
Legal and compliance approval from your organization

PCI DSS Certification

The receiving entity must hold a current PCI DSS Attestation of Compliance (AOC), regardless of whether the recipient is an external provider or your own infrastructure.

Technical Requirements

The receiving entity must provide:

Requirement	Purpose
PGP public key	Encrypt the export file for secure transfer
Static IP address	Whitelist for SFTP access
SSH public key	Authentication for SFTP connection

Export File Format

Exported files are PGP-encrypted and formatted as CSV with UTF-8 encoding.

Field	Description
`holder_name`	Cardholder name
`number`	Primary Account Number (PAN)
`token`	Token stored in Yuno’s vault
`expiration_year`	Card expiration year
`expiration_month`	Card expiration month

Secure Delivery Process

Yuno’s Security Team prepares and encrypts the export file, creates an SFTP user account, and uploads the file.
Notification is sent confirming file readiness, SFTP access details, and the active access window.
You access the SFTP using your SSH key and whitelisted IP, download the file within the defined time window. The file is automatically removed after the window expires.

The file is never sent by email or made publicly accessible. Access is strictly limited to the configured secure SFTP channel.

Security & Compliance

Yuno maintains PCI DSS Level 1 certification.
All exports are fully logged and monitored.
Only authorized personnel handle encrypted data.
Files are not stored beyond the required access window.

​Overview

​What Can Be Migrated

​Step 1 & 2: Importing Cards from Your Gateway

​Merchant Responsibilities

​Secure Transfer Protocol

​Requirements You Must Provide

​Mandatory Fields in the Migration File

​PGP Encryption Key

​Data Validation Before Import

​Step 3: Client-Side Implementation

​Required Data Parameters

​Customer Import

​Enroll Migrated Payment Methods

​How Token Migration Works

​Token Mapping File

​Subscription Migration

​Data Protection & PCI Compliance

​Migration Timeline

​Best Practices

​Exporting Tokens from Yuno

​When to Request an Export

​Prerequisites

​Export File Format

​Secure Delivery Process

​Security & Compliance

Overview

What Can Be Migrated

Step 1 & 2: Importing Cards from Your Gateway

Merchant Responsibilities

Secure Transfer Protocol

Requirements You Must Provide

Mandatory Fields in the Migration File

PGP Encryption Key

Data Validation Before Import

Step 3: Client-Side Implementation

Required Data Parameters

Customer Import

Enroll Migrated Payment Methods

How Token Migration Works

Token Mapping File

Subscription Migration

Data Protection & PCI Compliance

Migration Timeline

Best Practices

Exporting Tokens from Yuno

When to Request an Export

Prerequisites

Export File Format

Secure Delivery Process

Security & Compliance