On-ramp integration guide

This guide walks through using Latitude’s on-ramp product. The examples cover two corridors: MXN → USDC via virtual CLABE (SPEI) and PHP → USDC via QR Ph (InstaPay). The flow is identical across corridors; only the KYC document type in Step 2 and the deposit account shape in Step 5 differ by country.

Before you start, make sure you’re familiar with the API basics — authentication, idempotency, webhooks, and prefunding.

Summary

The high-level steps are as follows:

1. (Optional) Create a webhook subscription for individual and conversion events
2. Create an individual that represents the end user
3. Upload document images for KYC verification
4. Wait for KYC result
5. Create a conversion_account that represents the on-ramp mechanism
   • The response contains a deposit account (virtual CLABE for MX, QR Ph payload for PH)
   • Share the deposit instructions with the end user
   • The user can now deposit fiat at any time
6. User deposits fiat
7. Receive webhooks for conversion lifecycle events

Detailed Steps

Step 1: (Optional) Create a Webhook Subscription

Create a webhook subscription to be notified of individual and conversion events. See API basics — Webhooks for details. The relevant event types for this flow are:

• conversion.created — sent when a deposit is received into a virtual account
• conversion.payout_initiated — sent when a blockchain transfer is initiated
• conversion.completed — sent when a blockchain transfer is completed
• individual.status_changed — sent when an individual’s status changes

Step 2: Create an Individual

The only field that differs between corridors here is document: MX uses a CURP, PH uses a TIN. All other fields (name, address, consent, etc.) have the same shape.

1
POST /v1/individuals HTTP/1.1
2
Content-Type: application/json
3
4
{
5
  "given_name": "María",
6
  "family_name": "González Hernández",
7
  "country": "MX",
8
  "product_types": ["on_ramp"],
9
  "email": "[email protected]",
10
  "phone": "+525512345678",
11
  "date_of_birth": "1988-03-14",
12
  "document": {
13
    "type": "curp",
14
    "number": "GARC850615HDFRRL09"
15
  },
16
  "address": {
17
    "line_1": "Av. Paseo de la Reforma 505",
18
    "line_2": "Piso 12, Col. Cuauhtémoc",
19
    "city": "Ciudad de México",
20
    "state": "CDMX",
21
    "postal_code": "06500"
22
  },
23
  "idv_consent_recorded_at": "2025-01-30T14:00:00Z"
24
}

idv_consent_recorded_at is required for on-ramp: timestamp when the end user accepted identity verification consent (ISO 8601).

Response:

1
HTTP/1.1 201 Created
2
Content-Type: application/json
3
4
{
5
  "id": "ind_7a3b2c1d",
6
  "status": "action_required",
7
  "status_details": [
8
    {
9
      "code": "verification_front_image_needed",
10
      "message": "Please upload a photo of the front of your government-issued ID."
11
    },
12
    {
13
      "code": "verification_back_image_needed",
14
      "message": "Please upload a photo of the back of your government-issued ID."
15
    }
16
  ],
17
  "given_name": "María",
18
  "family_name": "González Hernández",
19
  "email": "[email protected]",
20
  "phone": "+525512345678",
21
  "date_of_birth": "1988-03-14",
22
  "country": "MX",
23
  "document": {
24
    "type": "curp",
25
    "number": "GARC850615HDFRRL09"
26
  },
27
  "address": {
28
    "line_1": "Av. Paseo de la Reforma 505",
29
    "line_2": "Piso 12, Col. Cuauhtémoc",
30
    "city": "Ciudad de México",
31
    "state": "CDMX",
32
    "postal_code": "06500",
33
    "country": "MX"
34
  },
35
  "financial_accounts": [],
36
  "product_types": ["on_ramp"],
37
  "created_at": "2025-01-30T14:32:00Z",
38
  "updated_at": "2025-01-30T14:32:00Z"
39
}

The response includes status and status_details. For on-ramp individuals, the initial status is action_required because document images are needed for KYC verification. The status_details array contains objects with a machine-readable code and a human-readable message explaining what’s needed.

Individual Statuses

When the status is action_required, status_details is an array of objects with code and message. When status is active, pending, or rejected, status_details is null.

Note: status_details[].code is a machine-readable string you can use for programmatic branching. status_details[].message is a human-readable string suitable for manual review. New codes may be added over time without changing the set of statuses.

Step 3: Upload Verification Images

Note: Latitude supports other options for completing KYC. Contact us to discuss alternatives.

After creating the individual, upload photos of the front and back (if applicable) of the end user’s government ID.

Request:

1
POST /v1/individuals/ind_7a3b2c1d/verification_images HTTP/1.1
2
Content-Type: application/json
3
4
{
5
  "images": [
6
    {
7
      "type": "document-front",
8
      "content": "data:image/jpeg;base64,/9j/4AAQ..."
9
    },
10
    {
11
      "type": "document-back",
12
      "content": "data:image/jpeg;base64,/9j/4AAQ..."
13
    }
14
  ]
15
}

The type field identifies what the image represents. The accepted types are document-front and document-back. The content field is the image as a base64-encoded data URI.

Response:

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
4
{
5
  "individual_id": "ind_7a3b2c1d",
6
  "images": [
7
    {
8
      "id": "vimg_xyz789",
9
      "type": "document-front",
10
      "content_type": "image/jpeg",
11
      "created_at": "2025-01-30T14:33:00Z"
12
    },
13
    {
14
      "id": "vimg_def456",
15
      "type": "document-back",
16
      "content_type": "image/jpeg",
17
      "created_at": "2025-01-30T14:33:00Z"
18
    }
19
  ]
20
}

Replacing an Image

The endpoint uses merge-by-side semantics: only the sides included in the request are replaced. Existing images for other sides are preserved. For example, to replace just the front image:

1
POST /v1/individuals/ind_7a3b2c1d/verification_images HTTP/1.1
2
Content-Type: application/json
3
4
{
5
  "images": [
6
    {
7
      "type": "document-front",
8
      "content": "data:image/jpeg;base64,/9j/NEW..."
9
    }
10
  ]
11
}

Retrieving Image Metadata

1
GET /v1/individuals/ind_7a3b2c1d/verification_images HTTP/1.1

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
4
{
5
  "individual_id": "ind_7a3b2c1d",
6
  "images": [
7
    {
8
      "id": "vimg_xyz789",
9
      "type": "document-front",
10
      "content_type": "image/jpeg",
11
      "created_at": "2025-01-30T14:33:00Z"
12
    },
13
    {
14
      "id": "vimg_def456",
15
      "type": "document-back",
16
      "content_type": "image/jpeg",
17
      "created_at": "2025-01-30T14:33:00Z"
18
    }
19
  ]
20
}

Sandbox Image Testing

In sandbox, any valid image will generate an approved outcome by default. Use the following magic strings as the base64-encoded image content to trigger specific outcomes:

Sample request to simulate one image being blurry:

1
POST /v1/individuals/ind_7a3b2c1d/verification_images HTTP/1.1
2
Content-Type: application/json
3
4
{
5
  "images": [
6
    {
7
      "type": "document-front",
8
      "content": "data:image/jpeg;base64,cmVqZWN0ZWQtYmx1cnJ5"
9
    },
10
    {
11
      "type": "document-back",
12
      "content": "data:image/jpeg;base64,YXBwcm92ZWQ="
13
    }
14
  ]
15
}

Step 4: Wait for KYC Result

After uploading document images, the individual’s status moves to pending while KYC verification is processed. You will receive an individual.status_changed webhook when the status changes.

• If the status changes to active, proceed to create a conversion_account.
• If the status changes to action_required, check status_details[].code to determine what’s needed.

After taking the requested action (e.g., uploading clearer photos), the individual returns to pending and KYC verification is re-processed.

Sample individual.status_changed webhook (KYC passed):

1
{
2
  "event_type": "individual.status_changed",
3
  "event_payload": {
4
    "id": "ind_7a3b2c1d",
5
    "status": "active",
6
    "status_detail": null,
7
    "previous_status": "pending",
8
    "updated_at": "2025-01-30T14:35:00Z"
9
  }
10
}

Sample individual.status_changed webhook (action needed):

1
{
2
  "event_type": "individual.status_changed",
3
  "event_payload": {
4
    "id": "ind_7a3b2c1d",
5
    "status": "action_required",
6
    "status_details": [
7
      {
8
        "code": "verification_front_image_blurry",
9
        "message": "The front image of the ID was too blurry. Please upload a clearer photo."
10
      }
11
    ],
12
    "previous_status": "pending",
13
    "updated_at": "2025-01-30T14:35:00Z"
14
  }
15
}

Step 5: Create a Conversion Account

The individual must have active status before a conversion account can be created.

The request is the same shape in both corridors; set source_currency to mxn for MX or php for PH. The deposit_account returned in the response differs by country — see the tabs below the request.

Request:

1
POST /v1/conversion_accounts HTTP/1.1
2
Content-Type: application/json
3
4
{
5
  "individual_id": "ind_7a3b2c1d",
6
  "payout_account": {
7
    "type": "crypto_wallet",
8
    "details": {
9
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
10
      "network": "base"
11
    }
12
  },
13
  "source_currency": "mxn",
14
  "destination_currency": "usdc"
15
}

Response:

1
HTTP/1.1 201 Created
2
Content-Type: application/json
3
4
{
5
  "id": "cacc_4e5f6a7b",
6
  "individual_id": "ind_7a3b2c1d",
7
  "payout_account": {
8
    "id": "fa_5e6f7g8h",
9
    "type": "crypto_wallet",
10
    "details": {
11
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
12
      "network": "base"
13
    },
14
    "created_at": "2025-01-30T14:33:15Z",
15
    "updated_at": "2025-01-30T14:33:15Z"
16
  },
17
  "deposit_account": {
18
    "id": "fa_9i0j1k2l",
19
    "type": "virtual_account",
20
    "details": {
21
      "clabe": "646180294817365024"
22
    },
23
    "created_at": "2025-01-30T14:33:15Z",
24
    "updated_at": "2025-01-30T14:33:15Z"
25
  },
26
  "source_currency": "mxn",
27
  "destination_currency": "usdc",
28
  "status": "active",
29
  "created_at": "2025-01-30T14:33:15Z",
30
  "updated_at": "2025-01-30T14:33:15Z"
31
}

The deposit_account financial accounts are also associated with the individual and will appear in GET /v1/individuals/{id}.

Sharing deposit instructions with the end user

• MX: share the clabe string with the end user. They can then send a SPEI transfer to that CLABE from any Mexican bank.
• PH: the qrph_payload is an EMV QR Ph payload string conforming to the ph.ppmi.p2m.qrph standard. Render it as a scannable QR code in your UI using any standard QR code library (e.g. qrcode.js, zxing). The end user scans it with their bank or e-wallet app to pay via InstaPay.

Step 6: User Deposits Fiat

At this point, the end user may send funds to the deposit account at any time — via SPEI to the CLABE (MX), or by scanning the QR Ph code (PH). Each time a deposit is received, a new conversion will be created.

Simulate Deposit (Sandbox Only)

In sandbox, a deposit can be simulated using the sandbox-only simulation endpoint. Provide the financial_account_id of the deposit account and the amount of fiat currency to deposit. This endpoint works the same way for both corridors; just vary currency and the financial_account_id.

Request:

1
POST /v1/deposits/simulate HTTP/1.1
2
Content-Type: application/json
3
4
{
5
  "financial_account_id": "fa_9i0j1k2l",
6
  "amount": "50.00",
7
  "currency": "MXN"
8
}

Note: Sandbox deposits are capped at a small amount per corridor (50 MXN for MX, 50 PHP for PH).

Step 7: Receive Webhooks

Note: Polling is also available as an alternative to webhooks. You can poll for updates on the list conversions endpoint.

The webhook event types and payload shapes are identical across corridors — only the currency fields in deposit and payout, and the numeric values, differ by country.

a) When an individual’s status changes

1
{
2
  "event_type": "individual.status_changed",
3
  "event_payload": {
4
    "id": "ind_7a3b2c1d",
5
    "status": "active",
6
    "status_detail": null,
7
    "previous_status": "pending",
8
    "updated_at": "2025-01-30T14:35:00Z"
9
  }
10
}

b) When a deposit is received into a virtual account

1
{
2
  "event_type": "conversion.created",
3
  "event_payload": {
4
    "id": "cnv_abc123",
5
    "conversion_account_id": "cacc_4e5f6a7b",
6
    "individual_id": "ind_7a3b2c1d",
7
    "status": "processing",
8
    "deposit": {
9
      "amount": "10000.00",
10
      "currency": "mxn",
11
      "funding_account_id": "fa_9i0j1k2l",
12
      "received_at": "2025-01-30T14:40:00Z"
13
    },
14
    "payout": null,
15
    "total_fee": null,
16
    "fee_currency": null,
17
    "exchange_rate": null,
18
    "created_at": "2025-01-30T14:40:00Z",
19
    "updated_at": "2025-01-30T14:40:00Z"
20
  }
21
}

c) When a blockchain transfer is initiated

1
{
2
  "event_type": "conversion.payout_initiated",
3
  "event_payload": {
4
    "id": "cnv_abc123",
5
    "conversion_account_id": "cacc_4e5f6a7b",
6
    "individual_id": "ind_7a3b2c1d",
7
    "status": "processing",
8
    "deposit": {
9
      "amount": "10000.00",
10
      "currency": "mxn",
11
      "funding_account_id": "fa_9i0j1k2l",
12
      "received_at": "2025-01-30T14:40:00Z",
13
      "tx_hash": null
14
    },
15
    "payout": {
16
      "amount": "495.00",
17
      "currency": "usdc",
18
      "payout_account_id": "fa_5e6f7g8h",
19
      "initiated_at": "2025-01-30T14:41:00Z",
20
      "completed_at": null,
21
      "tx_hash": "0x7a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a"
22
    },
23
    "total_fee": "100.00",
24
    "fee_currency": "mxn",
25
    "exchange_rate": "0.0495",
26
    "created_at": "2025-01-30T14:40:00Z",
27
    "updated_at": "2025-01-30T14:41:00Z"
28
  }
29
}

d) When a blockchain transfer is completed

1
{
2
  "event_type": "conversion.completed",
3
  "event_payload": {
4
    "id": "cnv_abc123",
5
    "conversion_account_id": "cacc_4e5f6a7b",
6
    "individual_id": "ind_7a3b2c1d",
7
    "status": "completed",
8
    "deposit": {
9
      "amount": "10000.00",
10
      "currency": "mxn",
11
      "funding_account_id": "fa_9i0j1k2l",
12
      "received_at": "2025-01-30T14:40:00Z"
13
    },
14
    "payout": {
15
      "amount": "495.00",
16
      "currency": "usdc",
17
      "payout_account_id": "fa_5e6f7g8h",
18
      "initiated_at": "2025-01-30T14:41:00Z",
19
      "completed_at": "2025-01-30T14:45:00Z",
20
      "tx_hash": "0x7a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a"
21
    },
22
    "total_fee": "100.00",
23
    "fee_currency": "mxn",
24
    "exchange_rate": "0.0495",
25
    "created_at": "2025-01-30T14:40:00Z",
26
    "updated_at": "2025-01-30T14:45:00Z"
27
  }
28
}