Integration Guides

Global payouts integration guide

This guide walks through the primary flows for integrating with Latitude’s global payouts product. You’ll learn how to create recipients, optionally lock exchange rates with quotes, and execute transfers.

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. Prerequisites
    • Prefund your Latitude account with USD or USDC
    • (Optional) Create a webhook subscription for transfer events
  2. Create a recipient with financial account details
  3. (Optional) Create a quote to lock an exchange rate for 2 minutes
  4. Create a transfer — either referencing a quote or with transfer parameters directly
  5. Determine the outcome via webhooks or polling

Detailed Steps

Step 0: Prerequisites

a) Prefund your Latitude account

See API basics — Prefunded flows for funding options.

b) (Optional) Create a webhook subscription

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

  • transfer.completed — sent when a transfer completes successfully
  • transfer.failed — sent when a transfer terminally fails

Step 1: Create a Recipient with Financial Account

Create a recipient profile with financial account information. The required fields vary by country — see Country-specific details for the full reference.

Request:

1POST /v1/recipients HTTP/1.1
2Content-Type: application/json
3
4{
5  "given_name": "Rahul",
6  "family_name": "Patel",
7  "type": "individual",
8  "email": "[email protected]",
9  "phone": "+919876543210",
10  "address": {
11    "line_1": "Flat 304, Building B, Sunshine Apartments",
12    "city": "Bengaluru",
13    "state": "Karnataka",
14    "postal_code": "560001",
15    "country": "in"
16  },
17  "financial_account": {
18    "type": "upi",
19    "details": {
20      "vpa": "9876543210@paytm"
21    }
22  }
23}

Response:

1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5  "id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
6  "given_name": "Rahul",
7  "family_name": "Patel",
8  "type": "individual",
9  "email": "[email protected]",
10  "phone": "+919876543210",
11  "address": {
12    "line_1": "Flat 304, Building B, Sunshine Apartments",
13    "line_2": null,
14    "city": "Bengaluru",
15    "state": "Karnataka",
16    "postal_code": "560001",
17    "country": "IN"
18  },
19  "document": null,
20  "legal_name": null,
21  "status": "pending",
22  "financial_account": {
23    "id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
24    "type": "upi",
25    "details": {
26      "vpa": "9876543210@paytm"
27    },
28    "created_at": "2025-01-15T10:30:00Z",
29    "updated_at": "2025-01-15T10:30:00Z"
30  },
31  "created_at": "2025-01-15T10:30:00Z",
32  "updated_at": "2025-01-15T10:30:00Z"
33}

Step 2: (Optional) Create a Quote

Create a quote to lock the conversion rate and fees for 2 minutes. You must specify either source_amount (to send a fixed amount) or destination_amount (to have a specific amount arrive).

Request:

1POST /v1/quotes HTTP/1.1
2Content-Type: application/json
3
4{
5  "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
6  "payout_method": "upi",
7  "source_amount": "100.00",
8  "source_currency": "usd",
9  "destination_currency": "inr"
10}

Response:

1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5  "id": "qu_01h3x5n6z7y8w9v0u1t2s3r4",
6  "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
7  "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
8  "source_amount": "100.00",
9  "source_currency": "usd",
10  "destination_amount": "8356.42",
11  "destination_currency": "inr",
12  "exchange_rate": "83.5642",
13  "payout_method": "upi",
14  "total_fee": "1.05",
15  "fee_currency": "usd",
16  "total_tax": "0.00",
17  "tax_currency": "usd",
18  "expires_at": "2025-01-15T10:32:00Z",
19  "created_at": "2025-01-15T10:30:00Z"
20}

Step 3: Create a Transfer

You can create a transfer in two ways:

Reference the quote ID to use the locked exchange rate and fees.

Request:

1POST /v1/transfers HTTP/1.1
2Content-Type: application/json
3
4{
5  "quote_id": "qu_01h3x5n6z7y8w9v0u1t2s3r4"
6}

Option B: Without a quote

Provide the transfer parameters directly. The exchange rate will be determined at the time the transfer is processed. You may specify either source_amount or destination_amount.

Request:

1POST /v1/transfers HTTP/1.1
2Content-Type: application/json
3
4{
5  "source_amount": "100.00",
6  "source_currency": "usd",
7  "destination_currency": "inr",
8  "financial_account_id": "fa_02j4y6p7a8b9c0d1e2f3g4h5",
9  "payout_method": "upi"
10}

Response (both options):

1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5  "id": "tr_01h3x5n6z7y8w9v0u1t2s3r4",
6  "client_reference_id": null,
7  "source_amount": "100.00",
8  "source_currency": "usd",
9  "destination_amount": "8356.42",
10  "destination_currency": "inr",
11  "exchange_rate": "83.5642",
12  "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
13  "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
14  "payout_method": "upi",
15  "status": "processing",
16  "total_fee": "1.05",
17  "fee_currency": "usd",
18  "total_tax": "0.00",
19  "tax_currency": "usd",
20  "completed_in": null,
21  "created_at": "2025-01-15T10:30:00Z",
22  "updated_at": "2025-01-15T10:30:00Z"
23}

Step 4: Determine the Outcome

Once you’ve created a transfer, there are two options to determine the outcome:

  1. Webhooks (recommended): Listen for transfer.completed or transfer.failed events. See API basics — Webhooks.
  2. Polling: Call GET /v1/transfers/{id} to check the current status.