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:

POST /v1/individuals HTTP/1.1
{
  "product_types": ["global_payouts"],
  "given_name": "Rahul",
  "family_name": "Patel",
  "country": "IN",
  "email": "[email protected]",
  "phone": "+919876543210",
  "address": {
    "line_1": "Flat 304, Building B, Sunshine Apartments",
    "city": "Bengaluru",
    "state": "Karnataka",
    "postal_code": "560001"
  },
  "financial_accounts": [
    {
      "type": "upi",
      "details": {
        "upi_id": "9876543210@paytm"
      }
    }
  ]
}

Expected Headers:

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

Canonical Request Payload

A plaintext representation of the request, consisting of the following parts joined by newlines:

Request method
Request path
Query string — omitted entirely (no line, not a blank line) when the request has no query string
Formatted headers (name:value, lowercased names), sorted by name, one per line
A sorted list of signed header names, delimited by semicolons
The SHA256 hash of the request payload

There are no blank separator lines between the parts.

Example (a POST with no query string, so the query string line is absent):

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 (POST /v1/transfers) and Conversion Accounts (POST /v1/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": "php",
    "financial_account": { "id": "fa_3UoI7VvsajLrPo1A" },
    "payout_method": "instapay"
  }'

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. Successful responses (200 and 201) are cached; error responses are not, so a request that failed can be retried with the same key.

If the same key is sent with a different request body, the API will return a 409 Conflict error. A key that is not a valid 36-character UUID is rejected with a 400 Bad Request.

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:

POST /v1/webhook_subscriptions HTTP/1.1
Content-Type: application/json
{
  "url": "https://your-domain.com/webhooks/latitude",
  "event_types": [
    "transfer.completed",
    "transfer.failed",
    "individual.status_changed",
    "conversion.created",
    "conversion.completed"
  ]
}

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.payout_initiated`	A transfer’s payout leg was initiated
`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.

{
  "event_type": "transfer.completed",
  "event_payload": { ... }
}

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.

{
  "event_type": "transfer.created",
  "event_payload": {
    "id": "tr_01h3x5n6z7y8w9v0u1t2s3r4",
    "client_reference_id": "order-4815",
    "source_amount": "100.00",
    "source_currency": "usdc",
    "destination_amount": "5640.15",
    "destination_currency": "php",
    "exchange_rate": "57.0",
    "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
    "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
    "payout_method": "instapay",
    "status": "awaiting_funds",
    "total_fee": "1.05",
    "fee_currency": "usdc",
    "total_tax": "0.00",
    "tax_currency": "usdc",
    "net_source_amount": "98.95",
    "completed_in": null,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "failure_reason": null,
    "settlement_reference_id": null,
    "deposit_instructions": {
      "type": "crypto_wallet",
      "currency": "usdc",
      "payment_methods": ["base"],
      "details": {
        "address": "0x2f1a3c9b7e4d5a6f8c0b1d2e3f4a5b6c7d8e9f01"
      },
      "deadline": "2025-01-15T10:33:00Z"
    }
  }
}

`transfer.funded`

Fired once funds are received and the transfer begins processing.

{
  "event_type": "transfer.funded",
  "event_payload": {
    "id": "tr_01h3x5n6z7y8w9v0u1t2s3r4",
    "client_reference_id": "order-4815",
    "source_amount": "100.00",
    "source_currency": "usdc",
    "destination_amount": "5640.15",
    "destination_currency": "php",
    "exchange_rate": "57.0",
    "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
    "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
    "payout_method": "instapay",
    "status": "started",
    "total_fee": "1.05",
    "fee_currency": "usdc",
    "total_tax": "0.00",
    "tax_currency": "usdc",
    "net_source_amount": "98.95",
    "completed_in": null,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:31:12Z",
    "failure_reason": null,
    "settlement_reference_id": null,
    "deposit_instructions": {
      "type": "crypto_wallet",
      "currency": "usdc",
      "payment_methods": ["base"],
      "details": {
        "address": "0x2f1a3c9b7e4d5a6f8c0b1d2e3f4a5b6c7d8e9f01"
      },
      "deadline": "2025-01-15T10:33:00Z"
    }
  }
}

`transfer.completed`

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

{
  "event_type": "transfer.completed",
  "event_payload": {
    "id": "tr_01h3x5n6z7y8w9v0u1t2s3r4",
    "client_reference_id": "order-4815",
    "source_amount": "100.00",
    "source_currency": "usdc",
    "destination_amount": "5640.15",
    "destination_currency": "php",
    "exchange_rate": "57.0",
    "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
    "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
    "payout_method": "instapay",
    "status": "completed",
    "total_fee": "1.05",
    "fee_currency": "usdc",
    "total_tax": "0.00",
    "tax_currency": "usdc",
    "net_source_amount": "98.95",
    "completed_in": "42",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:31:54Z",
    "failure_reason": null,
    "settlement_reference_id": "INSTAPAY-2025-0115-8A3F2C",
    "deposit_instructions": {
      "type": "crypto_wallet",
      "currency": "usdc",
      "payment_methods": ["base"],
      "details": {
        "address": "0x2f1a3c9b7e4d5a6f8c0b1d2e3f4a5b6c7d8e9f01"
      },
      "deadline": "2025-01-15T10:33:00Z"
    }
  }
}

`transfer.failed`

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

{
  "event_type": "transfer.failed",
  "event_payload": {
    "id": "tr_01h3x5n6z7y8w9v0u1t2s3r4",
    "client_reference_id": "order-4815",
    "source_amount": "100.00",
    "source_currency": "usdc",
    "destination_amount": "5640.15",
    "destination_currency": "php",
    "exchange_rate": "57.0",
    "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
    "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
    "payout_method": "instapay",
    "status": "failed",
    "total_fee": "1.05",
    "fee_currency": "usdc",
    "total_tax": "0.00",
    "tax_currency": "usdc",
    "net_source_amount": "98.95",
    "completed_in": null,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:32:08Z",
    "failure_reason": "Recipient bank account could not be credited",
    "settlement_reference_id": null,
    "deposit_instructions": {
      "type": "crypto_wallet",
      "currency": "usdc",
      "payment_methods": ["base"],
      "details": {
        "address": "0x2f1a3c9b7e4d5a6f8c0b1d2e3f4a5b6c7d8e9f01"
      },
      "deadline": "2025-01-15T10:33:00Z"
    }
  }
}

`transfer.expired`

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

{
  "event_type": "transfer.expired",
  "event_payload": {
    "id": "tr_01h3x5n6z7y8w9v0u1t2s3r4",
    "client_reference_id": "order-4815",
    "source_amount": "100.00",
    "source_currency": "usdc",
    "destination_amount": "5640.15",
    "destination_currency": "php",
    "exchange_rate": "57.0",
    "recipient_id": "rec_01h3x5n6z7y8w9v0u1t2s3r4",
    "financial_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
    "payout_method": "instapay",
    "status": "expired",
    "total_fee": "1.05",
    "fee_currency": "usdc",
    "total_tax": "0.00",
    "tax_currency": "usdc",
    "net_source_amount": "98.95",
    "completed_in": null,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T11:30:00Z",
    "failure_reason": null,
    "settlement_reference_id": null,
    "deposit_instructions": {
      "type": "crypto_wallet",
      "currency": "usdc",
      "payment_methods": ["base"],
      "details": {
        "address": "0x2f1a3c9b7e4d5a6f8c0b1d2e3f4a5b6c7d8e9f01"
      },
      "deadline": "2025-01-15T10:33:00Z"
    }
  }
}

`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.

{
  "event_type": "conversion.created",
  "event_payload": {
    "id": "cnv_01h9z8y7x6w5v4u3t2s1r0q9",
    "conversion_account_id": "cnva_01h3x5n6z7y8w9v0u1t2s3r4",
    "individual_id": "ind_01h3x5n6z7y8w9v0u1t2s3r4",
    "status": "pending",
    "deposit": {
      "amount": "1000.00",
      "currency": "usd",
      "received_at": "2025-01-15T09:00:00Z"
    },
    "payout": {
      "amount": "997.00",
      "currency": "usdc",
      "payout_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
      "tx_hash": null,
      "initiated_at": null,
      "completed_at": null
    },
    "total_fee": "3.00",
    "fee_currency": "usd",
    "exchange_rate": "1.0",
    "created_at": "2025-01-15T09:00:00Z",
    "updated_at": "2025-01-15T09:00:00Z"
  }
}

`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.

{
  "event_type": "conversion.payout_initiated",
  "event_payload": {
    "id": "cnv_01h9z8y7x6w5v4u3t2s1r0q9",
    "conversion_account_id": "cnva_01h3x5n6z7y8w9v0u1t2s3r4",
    "individual_id": "ind_01h3x5n6z7y8w9v0u1t2s3r4",
    "status": "started",
    "deposit": {
      "amount": "1000.00",
      "currency": "usd",
      "received_at": "2025-01-15T09:00:00Z"
    },
    "payout": {
      "amount": "997.00",
      "currency": "usdc",
      "payout_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
      "tx_hash": "0x8f2c1a9b3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2f",
      "initiated_at": "2025-01-15T09:01:30Z",
      "completed_at": null
    },
    "total_fee": "3.00",
    "fee_currency": "usd",
    "exchange_rate": "1.0",
    "created_at": "2025-01-15T09:00:00Z",
    "updated_at": "2025-01-15T09:01:30Z"
  }
}

`conversion.completed`

Fired when the blockchain payout confirms. completed_at is populated.

{
  "event_type": "conversion.completed",
  "event_payload": {
    "id": "cnv_01h9z8y7x6w5v4u3t2s1r0q9",
    "conversion_account_id": "cnva_01h3x5n6z7y8w9v0u1t2s3r4",
    "individual_id": "ind_01h3x5n6z7y8w9v0u1t2s3r4",
    "status": "completed",
    "deposit": {
      "amount": "1000.00",
      "currency": "usd",
      "received_at": "2025-01-15T09:00:00Z"
    },
    "payout": {
      "amount": "997.00",
      "currency": "usdc",
      "payout_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
      "tx_hash": "0x8f2c1a9b3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2f",
      "initiated_at": "2025-01-15T09:01:30Z",
      "completed_at": "2025-01-15T09:02:11Z"
    },
    "total_fee": "3.00",
    "fee_currency": "usd",
    "exchange_rate": "1.0",
    "created_at": "2025-01-15T09:00:00Z",
    "updated_at": "2025-01-15T09:02:11Z"
  }
}

`conversion.failed`

Fired when a conversion terminally fails.

{
  "event_type": "conversion.failed",
  "event_payload": {
    "id": "cnv_01h9z8y7x6w5v4u3t2s1r0q9",
    "conversion_account_id": "cnva_01h3x5n6z7y8w9v0u1t2s3r4",
    "individual_id": "ind_01h3x5n6z7y8w9v0u1t2s3r4",
    "status": "failed",
    "deposit": {
      "amount": "1000.00",
      "currency": "usd",
      "received_at": "2025-01-15T09:00:00Z"
    },
    "payout": {
      "amount": "997.00",
      "currency": "usdc",
      "payout_account_id": "fa_01h3x5n6z7y8w9v0u1t2s3r4",
      "tx_hash": null,
      "initiated_at": null,
      "completed_at": null
    },
    "total_fee": "3.00",
    "fee_currency": "usd",
    "exchange_rate": "1.0",
    "created_at": "2025-01-15T09:00:00Z",
    "updated_at": "2025-01-15T09:03:45Z"
  }
}

`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. When there are no details, the status_details key is omitted from the payload entirely rather than being sent as an empty array or null.

{
  "event_type": "individual.status_changed",
  "event_payload": {
    "id": "ind_01h3x5n6z7y8w9v0u1t2s3r4",
    "status": "action_required",
    "status_details": [
      {
        "code": "verification_image_blurry",
        "message": "Your ID photo was too blurry. Please provide a clearer photo."
      }
    ],
    "previous_status": "pending",
    "updated_at": "2025-01-15T12:00:00Z"
  }
}

Possible status values are pending, action_required, under_review, active, and rejected.

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.