API basics | Latitude | Documentation

This page covers the shared fundamentals that apply across all Latitude API products.

Base URL

All API requests are made to:

https://api.latitude.xyz/v1

Authentication

Latitude uses HMAC-SHA256 signature-based authentication. All API requests must include a properly formatted Authorization header containing the signature and metadata.

Required Headers

Header	Description
`Authorization`	HMAC-SHA256 Credential=Credential,SignedHeaders=SignedHeaders,Signature=Signature
`Host`	Latitude API host
`X-API-Key`	The API key associated to the customer account
`X-Date`	The current UTC time in ISO 8601 format. Example: `2025-09-16T12:07:15-05:00.000Z`
`X-Content-SHA256`	SHA256 hash of the request body
`X-Nonce`	We recommend using a unix timestamp concatenated with a 6-digit random value. Example: `1757865235000892731`

Authorization Header Components

Component	Description
`Credential`	The API key associated to the customer account
`SignedHeaders`	A list of headers used to create the signature, delimited by semicolons. Example: `host;x-api-key;x-date;x-content-sha256;x-nonce`
`Signature`	The Base64-encoded signature of the canonical request payload

Example: Properly Signed Request

Request:

1 POST /v1/individuals HTTP/1.1
2 
3 {
4   "product_types": ["global_payouts"],
5   "given_name": "Rahul",
6   "family_name": "Patel",
7   "country": "IN",
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   },
16   "financial_accounts": [
17     {
18       "type": "upi",
19       "details": {
20         "upi_id": "9876543210@paytm"
21       }
22     }
23   ]
24 }

Expected Headers:

1 Authorization: HMAC-SHA256 Credential=key_gdrbD2lQAO8pkxiOIM7vFZes3HN38yoW,SignedHeaders=host;x-api-key;x-date;x-content-sha256;x-nonce,Signature=YTc5YjU1Y2YxYzZkNDQ4ZTU1ODRkYzY4MzE1YWRhODRjODNiNzZmMGYzYjhjMDdmYmVhMGQ4YTE0MzZjOGUwYg==
2 X-API-Key: key_gdrbD2lQAO8pkxiOIM7vFZes3HN38yoW
3 X-Date: 2025-09-16T12:07:15-05:00.000Z
4 X-Content-SHA256: 7a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5c6d7e8f
5 X-Nonce: 1757865235000892731

Canonical Request Payload

A plaintext representation of the request, consisting of the following parts (all parts should be included, even if blank):

Request method
Request path
Query params
Formatted headers, sorted by name
A sorted list of signed headers, delimited by semicolons
The SHA256 hash of the request payload

Example:

POST
/v1/individuals
host:api.latitude.xyz
x-api-key:key_gdrbD2lQAO8pkxiOIM7vFZes3HN38yoW
x-content-sha256:7a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5c6d7e8f
x-date:2025-09-16T12:07:15-05:00.000Z
x-nonce:1757865235000892731
host;x-api-key;x-content-sha256;x-date;x-nonce
7a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5c6d7e8f

Signature Calculation

The final signature is generated by:

Producing a SHA256 hash of the canonical request payload
Adding the resulting hash to the final payload, and producing a HMAC-SHA256 signature using the secret key
Encoding the final signature using Base64

Final Payload:

HMAC-SHA256
2025-09-16T12:07:15-05:00.000Z
0d3b565633fe54a0850fa3bbcc1c108993297d63890766dc18e821bd924fbf6d

Final Signature:

a79b55cf1c6d448e5584dc68315ada84c83b76f0f3b8c07fbea0d8a1436c8e0b

Base64 Encoded Signature:

YTc5YjU1Y2YxYzZkNDQ4ZTU1ODRkYzY4MzE1YWRhODRjODNiNzZmMGYzYjhjMDdmYmVhMGQ4YTE0MzZjOGUwYg==

Idempotency

The Transfers and Conversion Accounts endpoints support idempotency. This allows you to safely retry requests without accidentally performing the same operation twice. To use it, include an Idempotency-Key header with a UUID value. We recommend a V4 UUID to avoid collisions.

$ curl -v --location https://api.latitude.xyz/v1/transfers \
>   --header 'Idempotency-Key: b3a7c700-3950-420b-8ecf-a1ca5d0afcbb' \
>   --header 'Content-Type: application/json' \
>   --data-raw '{
>     "source_amount": "100.00",
>     "source_currency": "usd",
>     "destination_currency": "inr",
>     "financial_account_id": "fa_3UoI7VvsajLrPo1A",
>     "payout_method": "upi"
>   }'

When you supply a valid Idempotency-Key, we save the resulting status code and body and return it for subsequent requests with the same key. When we return a saved result, we include an Idempotency-Replayed: true header in the response.

If the same key is sent with a different request body, the API will return a 409 Conflict error.

Note: Cached responses expire after 24 hours. We recommend generating a new UUID for each unique operation and storing it alongside your internal records so retries use the same key.

Webhooks

Subscribe to webhook events to get real-time notifications about transfer status changes, conversion updates, and KYC results. This is the recommended way to track the lifecycle of your payments.

To create a subscription, send a POST request to /v1/webhook_subscriptions with the URL where you’d like to receive events and the event types you’re interested in.

Request:

1 POST /v1/webhook_subscriptions HTTP/1.1
2 Content-Type: application/json
3 
4 {
5   "url": "https://your-domain.com/webhooks/latitude",
6   "event_types": [
7     "transfer.completed",
8     "transfer.failed",
9     "individual.status_changed",
10     "conversion.created",
11     "conversion.completed"
12   ]
13 }

Available Event Types

Event Type	Description
`transfer.created`	A transfer was created and is awaiting funding
`transfer.funded`	A transfer was funded and execution has started
`transfer.completed`	A transfer completed successfully
`transfer.failed`	A transfer terminally failed
`transfer.expired`	A transfer’s funding deadline passed before it was funded
`conversion.created`	A deposit was received into a virtual account
`conversion.payout_initiated`	A blockchain transfer was initiated to a destination wallet
`conversion.completed`	A blockchain transfer was completed to a destination wallet
`conversion.failed`	A conversion terminally failed
`individual.status_changed`	An individual’s status changed (e.g. KYC result)

Note: Webhook subscriptions are created at the organization level, not per-individual or per-transfer. Once a subscription is active, you will receive events for all individuals, transfers, and conversions across your account.

Event Type Payload Examples

Every webhook is delivered as a POST request with a JSON body of the form below. The event_type field identifies the event, and event_payload contains the resource snapshot at the time the event fired.

1 {
2   "event_type": "transfer.completed",
3   "event_payload": { ... }
4 }

The shape of event_payload depends on the resource the event relates to: transfer events carry a transfer object, conversion events carry a conversion object, and individual.status_changed carries an individual status object. Realistic examples for each event type follow.

`transfer.created`

Fired when a transfer is created. For transfers funded via a crypto deposit, the payload includes deposit_instructions describing where to send funds.

1 {
2   "event_type": "transfer.created",
3   "event_payload": {
4     "id": "tr_01h3x5n6z7y8w9v0u1t2s3r4",
5     "client_reference_id": "order-4815",
6     "source_amount": "100.00",
7     "source_currency": "usdc",
8     "destination_amount": "8356.42",
9     "destination_currency": "inr",
10     "exchange_rate": "83.5642",
11     "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
12     "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
13     "payout_method": "upi",
14     "status": "awaiting_funds",
15     "total_fee": "1.05",
16     "fee_currency": "usdc",
17     "total_tax": "0.00",
18     "tax_currency": "usdc",
19     "net_source_amount": "98.95",
20     "completed_in": null,
21     "created_at": "2025-01-15T10:30:00Z",
22     "updated_at": "2025-01-15T10:30:00Z",
23     "failure_reason": null,
24     "settlement_reference_id": null,
25     "deposit_instructions": {
26       "type": "crypto_wallet",
27       "currency": "usdc",
28       "payment_methods": ["ethereum"],
29       "details": {
30         "address": "0x2f1a3c9b7e4d5a6f8c0b1d2e3f4a5b6c7d8e9f01"
31       },
32       "deadline": "2025-01-15T11:30:00Z"
33     }
34   }
35 }

`transfer.funded`

Fired once funds are received and the transfer begins processing.

1 {
2   "event_type": "transfer.funded",
3   "event_payload": {
4     "id": "tr_01h3x5n6z7y8w9v0u1t2s3r4",
5     "client_reference_id": "order-4815",
6     "source_amount": "100.00",
7     "source_currency": "usdc",
8     "destination_amount": "8356.42",
9     "destination_currency": "inr",
10     "exchange_rate": "83.5642",
11     "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
12     "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
13     "payout_method": "upi",
14     "status": "started",
15     "total_fee": "1.05",
16     "fee_currency": "usdc",
17     "total_tax": "0.00",
18     "tax_currency": "usdc",
19     "net_source_amount": "98.95",
20     "completed_in": null,
21     "created_at": "2025-01-15T10:30:00Z",
22     "updated_at": "2025-01-15T10:31:12Z",
23     "failure_reason": null,
24     "settlement_reference_id": null,
25     "deposit_instructions": {
26       "type": "crypto_wallet",
27       "currency": "usdc",
28       "payment_methods": ["ethereum"],
29       "details": {
30         "address": "0x2f1a3c9b7e4d5a6f8c0b1d2e3f4a5b6c7d8e9f01"
31       },
32       "deadline": "2025-01-15T11:30:00Z"
33     }
34   }
35 }

`transfer.completed`

Fired when the payout settles successfully. completed_in (seconds) and settlement_reference_id are populated.

1 {
2   "event_type": "transfer.completed",
3   "event_payload": {
4     "id": "tr_01h3x5n6z7y8w9v0u1t2s3r4",
5     "client_reference_id": "order-4815",
6     "source_amount": "100.00",
7     "source_currency": "usdc",
8     "destination_amount": "8356.42",
9     "destination_currency": "inr",
10     "exchange_rate": "83.5642",
11     "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
12     "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
13     "payout_method": "upi",
14     "status": "completed",
15     "total_fee": "1.05",
16     "fee_currency": "usdc",
17     "total_tax": "0.00",
18     "tax_currency": "usdc",
19     "net_source_amount": "98.95",
20     "completed_in": "42",
21     "created_at": "2025-01-15T10:30:00Z",
22     "updated_at": "2025-01-15T10:31:54Z",
23     "failure_reason": null,
24     "settlement_reference_id": "UPI-2025-0115-8A3F2C",
25     "deposit_instructions": {
26       "type": "crypto_wallet",
27       "currency": "usdc",
28       "payment_methods": ["ethereum"],
29       "details": {
30         "address": "0x2f1a3c9b7e4d5a6f8c0b1d2e3f4a5b6c7d8e9f01"
31       },
32       "deadline": "2025-01-15T11:30:00Z"
33     }
34   }
35 }

`transfer.failed`

Fired when a transfer terminally fails during processing. failure_reason describes the cause.

1 {
2   "event_type": "transfer.failed",
3   "event_payload": {
4     "id": "tr_01h3x5n6z7y8w9v0u1t2s3r4",
5     "client_reference_id": "order-4815",
6     "source_amount": "100.00",
7     "source_currency": "usdc",
8     "destination_amount": "8356.42",
9     "destination_currency": "inr",
10     "exchange_rate": "83.5642",
11     "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
12     "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
13     "payout_method": "upi",
14     "status": "failed",
15     "total_fee": "1.05",
16     "fee_currency": "usdc",
17     "total_tax": "0.00",
18     "tax_currency": "usdc",
19     "net_source_amount": "98.95",
20     "completed_in": null,
21     "created_at": "2025-01-15T10:30:00Z",
22     "updated_at": "2025-01-15T10:32:08Z",
23     "failure_reason": "Recipient bank account could not be credited",
24     "settlement_reference_id": null,
25     "deposit_instructions": {
26       "type": "crypto_wallet",
27       "currency": "usdc",
28       "payment_methods": ["ethereum"],
29       "details": {
30         "address": "0x2f1a3c9b7e4d5a6f8c0b1d2e3f4a5b6c7d8e9f01"
31       },
32       "deadline": "2025-01-15T11:30:00Z"
33     }
34   }
35 }

`transfer.expired`

Fired when a transfer’s funding deadline passes before funds are received. The transfer never started processing.

1 {
2   "event_type": "transfer.expired",
3   "event_payload": {
4     "id": "tr_01h3x5n6z7y8w9v0u1t2s3r4",
5     "client_reference_id": "order-4815",
6     "source_amount": "100.00",
7     "source_currency": "usdc",
8     "destination_amount": "8356.42",
9     "destination_currency": "inr",
10     "exchange_rate": "83.5642",
11     "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
12     "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
13     "payout_method": "upi",
14     "status": "expired",
15     "total_fee": "1.05",
16     "fee_currency": "usdc",
17     "total_tax": "0.00",
18     "tax_currency": "usdc",
19     "net_source_amount": "98.95",
20     "completed_in": null,
21     "created_at": "2025-01-15T10:30:00Z",
22     "updated_at": "2025-01-15T11:30:00Z",
23     "failure_reason": null,
24     "settlement_reference_id": null,
25     "deposit_instructions": {
26       "type": "crypto_wallet",
27       "currency": "usdc",
28       "payment_methods": ["ethereum"],
29       "details": {
30         "address": "0x2f1a3c9b7e4d5a6f8c0b1d2e3f4a5b6c7d8e9f01"
31       },
32       "deadline": "2025-01-15T11:30:00Z"
33     }
34   }
35 }

`conversion.created`

Fired when a deposit is received into a conversion account’s virtual account. The blockchain payout has not yet been initiated, so payout timestamps and tx_hash are null.

1 {
2   "event_type": "conversion.created",
3   "event_payload": {
4     "id": "conv_01h9z8y7x6w5v4u3t2s1r0q9",
5     "conversion_account_id": "ca_01h3x5n6z7y8w9v0u1t2s3r4",
6     "individual_id": "ind_01h3x5n6z7y8w9v0u1t2s3r4",
7     "status": "pending",
8     "deposit": {
9       "amount": "1000.00",
10       "currency": "usd",
11       "received_at": "2025-01-15T09:00:00Z"
12     },
13     "payout": {
14       "amount": "997.00",
15       "currency": "usdc",
16       "payout_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
17       "tx_hash": null,
18       "initiated_at": null,
19       "completed_at": null
20     },
21     "total_fee": "3.00",
22     "fee_currency": "usd",
23     "exchange_rate": "1.0",
24     "created_at": "2025-01-15T09:00:00Z",
25     "updated_at": "2025-01-15T09:00:00Z"
26   }
27 }

`conversion.payout_initiated`

Fired when the blockchain payout to the destination wallet is broadcast. initiated_at and tx_hash are populated; completed_at is still null.

1 {
2   "event_type": "conversion.payout_initiated",
3   "event_payload": {
4     "id": "conv_01h9z8y7x6w5v4u3t2s1r0q9",
5     "conversion_account_id": "ca_01h3x5n6z7y8w9v0u1t2s3r4",
6     "individual_id": "ind_01h3x5n6z7y8w9v0u1t2s3r4",
7     "status": "started",
8     "deposit": {
9       "amount": "1000.00",
10       "currency": "usd",
11       "received_at": "2025-01-15T09:00:00Z"
12     },
13     "payout": {
14       "amount": "997.00",
15       "currency": "usdc",
16       "payout_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
17       "tx_hash": "0x8f2c1a9b3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2f",
18       "initiated_at": "2025-01-15T09:01:30Z",
19       "completed_at": null
20     },
21     "total_fee": "3.00",
22     "fee_currency": "usd",
23     "exchange_rate": "1.0",
24     "created_at": "2025-01-15T09:00:00Z",
25     "updated_at": "2025-01-15T09:01:30Z"
26   }
27 }

`conversion.completed`

Fired when the blockchain payout confirms. completed_at is populated.

1 {
2   "event_type": "conversion.completed",
3   "event_payload": {
4     "id": "conv_01h9z8y7x6w5v4u3t2s1r0q9",
5     "conversion_account_id": "ca_01h3x5n6z7y8w9v0u1t2s3r4",
6     "individual_id": "ind_01h3x5n6z7y8w9v0u1t2s3r4",
7     "status": "completed",
8     "deposit": {
9       "amount": "1000.00",
10       "currency": "usd",
11       "received_at": "2025-01-15T09:00:00Z"
12     },
13     "payout": {
14       "amount": "997.00",
15       "currency": "usdc",
16       "payout_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
17       "tx_hash": "0x8f2c1a9b3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2f",
18       "initiated_at": "2025-01-15T09:01:30Z",
19       "completed_at": "2025-01-15T09:02:11Z"
20     },
21     "total_fee": "3.00",
22     "fee_currency": "usd",
23     "exchange_rate": "1.0",
24     "created_at": "2025-01-15T09:00:00Z",
25     "updated_at": "2025-01-15T09:02:11Z"
26   }
27 }

`conversion.failed`

Fired when a conversion terminally fails.

1 {
2   "event_type": "conversion.failed",
3   "event_payload": {
4     "id": "conv_01h9z8y7x6w5v4u3t2s1r0q9",
5     "conversion_account_id": "ca_01h3x5n6z7y8w9v0u1t2s3r4",
6     "individual_id": "ind_01h3x5n6z7y8w9v0u1t2s3r4",
7     "status": "failed",
8     "deposit": {
9       "amount": "1000.00",
10       "currency": "usd",
11       "received_at": "2025-01-15T09:00:00Z"
12     },
13     "payout": {
14       "amount": "997.00",
15       "currency": "usdc",
16       "payout_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
17       "tx_hash": null,
18       "initiated_at": null,
19       "completed_at": null
20     },
21     "total_fee": "3.00",
22     "fee_currency": "usd",
23     "exchange_rate": "1.0",
24     "created_at": "2025-01-15T09:00:00Z",
25     "updated_at": "2025-01-15T09:03:45Z"
26   }
27 }

`individual.status_changed`

Fired when an individual’s status changes (for example, as a result of KYC review). status_details lists any action codes with human-readable messages, and is empty when no action is required.

1 {
2   "event_type": "individual.status_changed",
3   "event_payload": {
4     "id": "ind_01h3x5n6z7y8w9v0u1t2s3r4",
5     "status": "action_required",
6     "status_details": [
7       {
8         "code": "verification_image_blurry",
9         "message": "Your ID photo was too blurry. Please upload a clearer photo."
10       }
11     ],
12     "previous_status": "pending",
13     "updated_at": "2025-01-15T12:00:00Z"
14   }
15 }

Prefunded Flows

Currently all Latitude flows are prefunded. You send funds to Latitude and those funds settle before you can execute transfers. You can prefund using:

USD via wire transfer to your Latitude-managed bank account
USDC via blockchain deposit on the Base network

You can find the instructions for funding your account in the dashboard. We will support more flexible and real-time funding flows in the future.

Sandbox Environment

Latitude provides a sandbox environment for testing your integration without moving real money. Contact us to get sandbox API credentials.

The sandbox supports magic strings for simulating different outcomes (e.g. KYC approval/rejection, transfer success/failure). See the individual integration guides for sandbox-specific details.