Quickstart

This walks through creating a single cross-border payout in sandbox, end to end. You'll call two endpoints — initiate then confirm — and see a webhook fire when the payment settles.

Get a sandbox API key

Open Settings → Developers → API Keys in the Lumeo portal. Click New key, select Sandbox, and copy the key. It is shown only once and is prefixed sk_sandbox_.

Set it as an environment variable so you don't paste it inline:

export LUMEO_API_KEY=sk_sandbox_...

Initiate a payout

POST /payments/initiate records the payout intent. It does not move funds yet.

curl -X POST https://api-sandbox.lumeo.co.in/api/v1/payments/initiate \
  -H "Authorization: Bearer $LUMEO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "currency": "USD",
    "destinationAddress": "GTEST_SUCCESS_ADDR_XXXXXXXXXXXXXXXXXX",
    "purposeCode": "P0801",
    "invoiceRef": "invoice-2026-0001"
  }'

import { LumeoClient } from "@lumeo/sdk";
import { randomUUID } from "crypto";

const lumeo = new LumeoClient({ apiKey: process.env.LUMEO_API_KEY! });

const payment = await lumeo.payments.initiate({
  amount: 500.0,
  currency: "USD",
  destinationAddress: "GTEST_SUCCESS_ADDR_XXXXXXXXXXXXXXXXXX",
  purposeCode: "P0801",
  invoiceRef: "invoice-2026-0001",
}, { idempotencyKey: randomUUID() });

console.log(payment.id);     // clx1a2b3c...
console.log(payment.status); // "INITIATED"

You get back a payment id with status: "INITIATED". Save this ID — you need it for the next step.

Confirm the payout

POST /payments/confirm triggers compliance checks and queues the payout for execution.

curl -X POST https://api-sandbox.lumeo.co.in/api/v1/payments/confirm \
  -H "Authorization: Bearer $LUMEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "clx1a2b3c4d5e6f7g8h9",
    "destinationAddress": "GTEST_SUCCESS_ADDR_XXXXXXXXXXXXXXXXXX",
    "amount": "500.00",
    "currency": "USD",
    "vaultId": "your-vault-id"
  }'

The payment moves to COMPLIANCE_CHECK, then PROCESSING, then CONFIRMED within a few seconds in sandbox.

Receive the webhook

curl -X POST https://api-sandbox.lumeo.co.in/api/v1/webhooks \
  -H "Authorization: Bearer $LUMEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-handler.example.com/webhooks/lumeo",
    "events": ["payout.settled", "fira.generated"]
  }'

When the payout settles, Lumeo POSTs to your URL:

{
  "id": "evt_01j4abc",
  "type": "payout.settled",
  "createdAt": "2026-07-01T09:14:28.000Z",
  "data": {
    "paymentId": "clx1a2b3c4d5e6f7g8h9",
    "status": "CONFIRMED",
    "amount": 500.00,
    "currency": "USD",
    "firaId": "fira_01j4abc"
  }
}

Fetch the auto-generated FIRA

A Foreign Inward Remittance Advice is generated automatically for every confirmed cross-border payout. Fetch it using the firaId from the webhook:

curl https://api-sandbox.lumeo.co.in/api/v1/compliance/fira/fira_01j4abc \
  -H "Authorization: Bearer $LUMEO_API_KEY"

What just happened

You just ran the full compliance flow: money initiated → compliance checked → settled → FIRA generated. In production, this sequence completes for real cross-border payouts with real INR settlement.

Next steps

Integrate a payout flow — production-grade integration with idempotency, failure handling, and webhook verification.
Test in sandbox — simulate failure and delay scenarios.
Reconcile a cross-border payment — match a payout to its ledger entry and source invoice.