User Data & Friction

The core trade-off

When integrating with M2M, you control how much user data you provide upfront. This creates a fundamental trade-off:

Approach	Integration Effort	User Friction	Description
Full data upfront	High	None	Provide all user data when creating the link
Webhook fallback	Medium	Low	Provide partial data, respond to webhooks for the rest
Minimal	Low	High	Only provide `referenceId`, users enter everything

Understanding friction

“Friction” refers to the steps a user must complete before making a transaction:

Zero friction (full data upfront)

User opens link and immediately sees:

Pre-filled personal information
Pre-filled payment method
Ready to confirm transaction

No forms to fill, no ID verification prompts.

Low friction (webhook fallback)

User opens link and sees:

Some pre-filled information
May need to confirm or add minor details
Quick verification step if needed

Fast completion, minimal input required.

High friction (minimal integration)

User opens link and must:

Enter full legal name (all parts)
Enter government ID number
Enter date of birth
Complete full CIP verification
Add payment method

More steps = higher abandonment risk.

Data fields and their impact

Required CIP fields

M2M requires these fields for identity verification (CIP). Each missing field increases friction:

Field	Description	Impact if missing
`name.firstName`	First name	User enters manually
`name.secondName`	Middle name / second first name	User enters manually
`name.lastName`	Primary surname	User enters manually
`name.secondLastName`	Secondary surname (maternal)	User enters manually
`idNumber`	Government ID (e.g., CURP)	User enters + may need ID verification
`idType`	Type of ID document	User selects from list
`dob`	Date of birth	User enters with date picker

Optional but valuable

Field	Description	Impact
`paymentMethod`	Payment destination — required when `userData` is provided (see Payment Methods)	User adds payment method if missing
`idImage`	ID document photo (base64)	May skip photo capture step

Payment methods

The paymentMethod field uses a flexible structure to support different payment types and countries:

Bank Account

For bank transfers, include the country code (ISO 3166-1 alpha-2) and the appropriate account identifier:Mexico (CLABE)

{
  "paymentMethod": {
    "type": "bank_account",
    "bankAccount": {
      "country": "MX",
      "accountNumber": "012345678901234567"
    }
  }
}

Argentina (CBU)

{
  "paymentMethod": {
    "type": "bank_account",
    "bankAccount": {
      "country": "AR",
      "accountNumber": "0110599940000041079153"
    }
  }
}

Colombia

{
  "paymentMethod": {
    "type": "bank_account",
    "bankAccount": {
      "country": "CO",
      "accountNumber": "12345678901234",
      "accountType": "savings",
      "bankCode": "007"
    }
  }
}

Field	Required	Description
`type`	Yes	Must be `bank_account`
`bankAccount.country`	Yes	ISO 3166-1 alpha-2 country code
`bankAccount.accountNumber`	Yes	Account identifier (CLABE, CBU, IBAN, etc.)
`bankAccount.accountType`	No	`savings` or `checking` (required for some countries)
`bankAccount.bankCode`	No	Bank code or routing number (required for some countries)

Card

For card-based payouts, card data must be sent through the VGS Inbound Proxy for PCI compliance. The M2M API only accepts tokenized card numbers.

{
  "paymentMethod": {
    "type": "card",
    "card": {
      "number": "tok_sandbox_4fKq8H2xLmNpRtYw",
      "expiryMonth": "12",
      "expiryYear": "2028",
      "cardholderName": "Juan García",
      "last4": "4242",
      "brand": "visa"
    }
  }
}

Card numbers must be routed through the VGS Inbound Proxy. Never send raw PANs directly to the M2M API. Contact your M2M integration specialist for VGS proxy configuration.

Field	Required	Description
`type`	Yes	Must be `card`
`card.number`	Yes	VGS-tokenized card number (`tok_xxx`)
`card.expiryMonth`	Yes	Expiry month (`01`-`12`)
`card.expiryYear`	Yes	Expiry year (4 digits, e.g., `2028`)
`card.cardholderName`	No	Name as it appears on the card
`card.last4`	No	Last 4 digits (VGS can extract this automatically)
`card.brand`	No	Card brand (`visa`, `mastercard`, `amex`, etc.)

Cash Pickup (Future)

For cash pickup at physical locations (coming soon):

{
  "paymentMethod": {
    "type": "cash",
    "cash": {
      "provider": "oxxo"
    }
  }
}

Choose your approach

Option 1: Full data upfront

Best for: Partners with complete KYC data already collected Provide all user data when creating the link:

{
  "referenceId": "user_12345",
  "userData": {
    "name": {
      "firstName": "Juan",
      "secondName": "Carlos",
      "lastName": "Garcia",
      "secondLastName": "Lopez"
    },
    "idNumber": "GALO900515HDFRPN09",
    "idType": "CURP",
    "dob": "1990-05-15",
    "paymentMethod": {
      "type": "bank_account",
      "bankAccount": {
        "country": "MX",
        "accountNumber": "012345678901234567"
      }
    }
  }
}

Result: User opens the link and can immediately complete their transaction. No forms, no verification steps.

Pros:

Best user experience
Highest conversion rates
No webhook infrastructure needed

Cons:

Requires all data at link creation time
May need to collect data from multiple sources
Data must match government records exactly

Option 2: Webhook fallback (Recommended)

Best for: Partners who have partial data or need to fetch it asynchronously Provide what you have upfront, respond to webhooks for the rest:

{
  "referenceId": "user_12345",
  "userData": {
    "name": {
      "firstName": "Juan",
      "lastName": "Garcia"
    }
  }
}

When M2M needs more data, you receive a webhook:

{
  "event": "user.data_request",
  "data": {
    "requiredFields": ["name.secondName", "name.secondLastName", "idNumber", "idType", "dob"],
    "replyEndpoint": "https://api.m2m.leapfinancial.com/partner/data-requests/dr_123"
  }
}

You respond with the missing data:

{
  "referenceId": "user_12345",
  "userData": {
    "name": {
      "secondName": "Carlos",
      "secondLastName": "Lopez"
    },
    "idNumber": "GALO900515HDFRPN09",
    "idType": "CURP",
    "dob": "1990-05-15"
  }
}

Result: User sees a partially pre-filled form. If you respond quickly, they may not need to enter anything.

Pros:

Flexible - provide what you have
Async data fetching supported
Good balance of effort vs. UX
Graceful degradation if webhook fails

Cons:

Requires webhook infrastructure
Response time affects UX
More complex implementation

Option 3: Minimal integration

Best for: Quick POC or when you have no user data Only provide the user identifier:

{
  "referenceId": "user_12345"
}

Result: User must complete full CIP verification in the widget. Expect lower conversion rates.

Pros:

Fastest integration time
No data handling required
Works for any user

Cons:

Highest user friction
Lower conversion rates
Users may abandon the process

Data source precedence

When the same field is provided from multiple sources, M2M uses this precedence:

Priority	Source	Description
1 (highest)	`partner_api`	Data from link creation API
2	`partner_webhook`	Data from data request response
3 (lowest)	`widget`	Data entered by user

Higher priority data is never overwritten by lower priority data. If you provide firstName during link creation, a webhook response cannot change it.

This means you can safely:

Provide partial data upfront
Fill in gaps via webhook
Let users correct only what’s missing

Recommendations

Start with what you have

Don’t wait to collect all data before integrating. Start with the data you have:

Name from user profile? Include it.
Email but no ID? Include the name, skip the ID.
Nothing? Start with minimal and iterate.

Implement webhook fallback

Even if you plan to provide full data, implement webhook handling as a safety net:

Handles edge cases where data is incomplete
Supports users whose data doesn’t match records
Future-proofs your integration

Monitor and iterate

Track your users’ journey:

How many complete without entering data?
Where do users drop off?
Which fields cause the most friction?

Use this data to prioritize which fields to provide upfront.

Match data to government records

CIP verification compares your data to government records. Mismatches cause friction:

Use legal names, not nicknames
Format dates correctly (YYYY-MM-DD)
Validate ID numbers before submission

Example: Progressive enhancement

Here’s how to evolve your integration over time:

Phase 1: MVP (Day 1)

{
  "referenceId": "user_12345"
}

Focus: Get the integration working. Accept higher friction.

Phase 2: Add name data (Week 2)

{
  "referenceId": "user_12345",
  "userData": {
    "name": {
      "firstName": "Juan",
      "lastName": "Garcia"
    }
  }
}

Focus: Reduce friction with data you already have.

Phase 3: Implement webhooks (Week 4)

Handle user.data_request webhooks to provide:

Missing name fields
ID number (fetched from your KYC provider)
Date of birth

Focus: Minimize user input.

Phase 4: Full data (Week 6+)

{
  "referenceId": "user_12345",
  "userData": {
    "name": { /* all fields */ },
    "idNumber": "...",
    "idType": "CURP",
    "dob": "1990-05-15",
    "paymentMethod": {
      "type": "bank_account",
      "bankAccount": {
        "country": "MX",
        "accountNumber": "012345678901234567"
      }
    }
  }
}

Focus: Zero friction for returning users.

Next steps

User Lifecycle

Learn how M2M manages user state across links.

Data Requests

Implement webhook handling for data requests.

Getting Started

Integration

Webhooks

The core trade-off

Understanding friction

Data fields and their impact

Required CIP fields

Optional but valuable

Payment methods

Choose your approach

Option 1: Full data upfront

Option 2: Webhook fallback (Recommended)

Option 3: Minimal integration

Data source precedence

Recommendations

Example: Progressive enhancement

Phase 1: MVP (Day 1)

Phase 2: Add name data (Week 2)

Phase 3: Implement webhooks (Week 4)

Phase 4: Full data (Week 6+)

Next steps

User Lifecycle

Data Requests

Getting Started

Integration

Webhooks

​The core trade-off

​Understanding friction

​Data fields and their impact

​Required CIP fields

​Optional but valuable

​Payment methods

​Choose your approach

​Option 1: Full data upfront

​Option 2: Webhook fallback (Recommended)

​Option 3: Minimal integration

​Data source precedence

​Recommendations

​Example: Progressive enhancement

​Phase 1: MVP (Day 1)

​Phase 2: Add name data (Week 2)

​Phase 3: Implement webhooks (Week 4)

​Phase 4: Full data (Week 6+)

​Next steps

User Lifecycle

Data Requests

The core trade-off

Understanding friction

Data fields and their impact

Required CIP fields

Optional but valuable

Payment methods

Choose your approach

Option 1: Full data upfront

Option 2: Webhook fallback (Recommended)

Option 3: Minimal integration

Data source precedence

Recommendations

Example: Progressive enhancement

Phase 1: MVP (Day 1)

Phase 2: Add name data (Week 2)

Phase 3: Implement webhooks (Week 4)

Phase 4: Full data (Week 6+)

Next steps