API basics

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

Authorization Header Components

Example: Properly Signed Request

Request:

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

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):

1. Request method
2. Request path
3. Query params
4. Formatted headers, sorted by name
5. A sorted list of signed headers, delimited by semicolons
6. The SHA256 hash of the request payload

Example:

POST
/v1/recipients
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:

1. Producing a SHA256 hash of the canonical request payload
2. Adding the resulting hash to the final payload, and producing a HMAC-SHA256 signature using the secret key
3. 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

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.

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.