Payroll

Build a payroll product where your customers (employers) pay their employees and contractors anywhere in the world using stablecoin rails. Each employer is onboarded as a business customer. You register their payees as destinations and trigger payouts on their behalf; Lumx converts stablecoin to local fiat and settles into each payee’s account.

Step 1: Generate your API key

Head over to dashboard.lumx.io. Once logged in, generate a new API key and store it securely. See Authentication for details.

Step 2: Onboard the employer

For each employer using your product, create a business customer.

Request

curl -X POST https://api-sandbox.lumx.io/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "BUSINESS",
    "legalName": "Acme Inc.",
    "taxId": "42.887.120/0001-00",
    "incorporationDate": "2020-01-01",
    "country": "BRA",
    "email": "finance@acme.com",
    "accounts": ["USD"]
  }'

Before the employer can transact, they must accept Lumx’s terms of service (POST /customers/{id}/tos) and complete KYB. See Business verification for the full onboarding flow.

Step 3: Fund the employer’s wallet

Once the employer’s USD account is ACTIVE, create an autoconversion rule for it, using the account’s id as accountId. You do this once: the response’s sourceDepositInfo carries the ACH, Fedwire, and SWIFT details to share with the employer’s finance team, and every wire that lands is converted to stablecoin and credited to the employer’s wallet, whatever the amount.

Request

curl -X POST https://api-sandbox.lumx.io/autoconversion-rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "accountId": "af04e979-360a-428a-84e6-cbd8ffc4942b",
    "targetCurrency": "USDC",
    "purpose": "PERSONAL_ACCOUNT",
    "name": "Payroll funding"
  }'

Each deposit must be worth at least 50 USD. A USD account holds one active rule at a time. If the employer already holds stablecoin on-chain, they can also transfer it directly to the wallet returned at customer creation, no conversion needed. Subscribe to the onramp.success webhook to know the moment the wallet is funded and ready to run payouts. For the response, the deposit details per currency, and when to create a one-off on-ramp instead, see Global accounts.

Step 4: Register each payee’s destination

For each employee or contractor the employer wants to pay, register a destination under the employer’s customer record. Set holder.relationship to EMPLOYEE so the destination is correctly categorized for compliance. The taxId format varies by country; see Tax IDs by country and Coverage for the full list of supported rails and currencies.

Request

curl -X POST https://api-sandbox.lumx.io/destinations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Maria Santos - Engineering",
    "rail": "PIX",
    "currency": "BRL",
    "identifier": {
      "keyType": "CPF",
      "keyValue": "123.456.789-00"
    },
    "holder": {
      "type": "INDIVIDUAL",
      "relationship": "EMPLOYEE",
      "name": "Maria Santos",
      "taxId": "123.456.789-00",
      "birthDate": "1990-05-15",
      "email": "maria.santos@acme.com",
      "address": {
        "line1": "Rua Augusta 100",
        "city": "São Paulo",
        "state": "SP",
        "postalCode": "01304-000",
        "country": "BRA"
      }
    }
  }'

Request

curl -X POST https://api-sandbox.lumx.io/destinations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Carlos Hernández - Operations",
    "rail": "SPEI",
    "currency": "MXN",
    "identifier": {
      "keyType": "CLABE",
      "keyValue": "012180001234567899"
    },
    "holder": {
      "type": "INDIVIDUAL",
      "relationship": "EMPLOYEE",
      "name": "Carlos Hernández",
      "taxId": "HEGC900515ABC",
      "birthDate": "1990-05-15",
      "email": "carlos.hernandez@acme.com",
      "address": {
        "line1": "Calzada de Tlalpan 3465",
        "city": "Mexico City",
        "state": "CDMX",
        "postalCode": "04650",
        "country": "MEX"
      }
    }
  }'

Request

curl -X POST https://api-sandbox.lumx.io/destinations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Jane Doe - Marketing",
    "rail": "ACH",
    "currency": "USD",
    "identifier": {
      "type": "CHECKING",
      "accountNumber": "123456789012",
      "routingNumber": "021000021"
    },
    "bank": {
      "name": "JPMorgan Chase Bank",
      "address": {
        "line1": "383 Madison Avenue",
        "city": "New York",
        "state": "NY",
        "postalCode": "10179",
        "country": "USA"
      }
    },
    "holder": {
      "type": "INDIVIDUAL",
      "relationship": "EMPLOYEE",
      "name": "Jane Doe",
      "taxId": "123-45-6789",
      "birthDate": "1985-09-12",
      "email": "jane.doe@acme.com",
      "address": {
        "line1": "350 5th Avenue",
        "city": "New York",
        "state": "NY",
        "postalCode": "10118",
        "country": "USA"
      }
    }
  }'

Request

curl -X POST https://api-sandbox.lumx.io/destinations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Sarah Lee - Executive",
    "rail": "FEDWIRE",
    "currency": "USD",
    "identifier": {
      "type": "CHECKING",
      "accountNumber": "987654321098",
      "routingNumber": "021000021"
    },
    "bank": {
      "name": "JPMorgan Chase Bank",
      "address": {
        "line1": "383 Madison Avenue",
        "city": "New York",
        "state": "NY",
        "postalCode": "10179",
        "country": "USA"
      }
    },
    "holder": {
      "type": "INDIVIDUAL",
      "relationship": "EMPLOYEE",
      "name": "Sarah Lee",
      "taxId": "234-56-7890",
      "birthDate": "1982-04-08",
      "email": "sarah.lee@acme.com",
      "address": {
        "line1": "1 Market Street",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "country": "USA"
      }
    }
  }'

Request

curl -X POST https://api-sandbox.lumx.io/destinations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Lucas Martin - Engineering",
    "rail": "SEPA",
    "currency": "EUR",
    "identifier": {
      "iban": "FR1420041010050500013M02606",
      "bic": "BNPAFRPP"
    },
    "bank": {
      "name": "BNP Paribas",
      "address": {
        "line1": "16 Boulevard des Italiens",
        "city": "Paris",
        "state": "IDF",
        "postalCode": "75009",
        "country": "FRA"
      }
    },
    "holder": {
      "type": "INDIVIDUAL",
      "relationship": "EMPLOYEE",
      "name": "Lucas Martin",
      "taxId": "1850612345678",
      "birthDate": "1991-11-30",
      "email": "lucas.martin@acme.com",
      "address": {
        "line1": "45 Avenue Montaigne",
        "city": "Paris",
        "state": "IDF",
        "postalCode": "75008",
        "country": "FRA"
      }
    }
  }'

Request

curl -X POST https://api-sandbox.lumx.io/destinations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Oliver Smith - Engineering",
    "rail": "FPS",
    "currency": "GBP",
    "identifier": {
      "sortCode": "040509",
      "accountNumber": "00125977"
    },
    "bank": {
      "name": "Mock Bank",
      "address": {
        "line1": "1 Bank Street",
        "city": "London",
        "state": "LND",
        "postalCode": "EC1A 1BB",
        "country": "GBR"
      }
    },
    "holder": {
      "type": "INDIVIDUAL",
      "relationship": "EMPLOYEE",
      "name": "Oliver Smith",
      "taxId": "QQ123456C",
      "birthDate": "1990-03-22",
      "email": "oliver.smith@acme.com",
      "address": {
        "line1": "10 Downing Lane",
        "city": "London",
        "state": "LND",
        "postalCode": "SW1A 2AA",
        "country": "GBR"
      }
    }
  }'

Request

curl -X POST https://api-sandbox.lumx.io/destinations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "John Doe - Design",
    "rail": "SWIFT",
    "currency": "USD",
    "identifier": {
      "iban": "GB29NWBK60161331926819",
      "bic": "NWBKGB2L"
    },
    "bank": {
      "name": "NatWest Bank",
      "address": {
        "line1": "250 Bishopsgate",
        "city": "London",
        "postalCode": "EC2M 4AA",
        "country": "GBR"
      }
    },
    "holder": {
      "type": "INDIVIDUAL",
      "relationship": "EMPLOYEE",
      "name": "John Doe",
      "taxId": "AB123456C",
      "birthDate": "1988-03-22",
      "email": "john.doe@acme.com",
      "address": {
        "line1": "10 Downing Street",
        "city": "London",
        "postalCode": "SW1A 2AA",
        "country": "GBR"
      }
    }
  }'

Destinations go through verification before they can be used. Subscribe to the destinations.approved webhook to know when a payee is ready to receive payouts. See Destinations for the full reference.

Step 5: Run payroll

For each approved payee, create an off-ramp transaction debiting the employer’s wallet. Use purpose: "PROFESSIONAL_SERVICES" for contractor and salary payments (the closest available code; there’s no dedicated payroll purpose), or EXPENSES_REIMBURSEMENT for reimbursements. See Purpose codes for the full list.

Request

curl -X POST https://api-sandbox.lumx.io/transactions/off-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destinationId": "e80d3137-eddd-4791-b9b8-6e36b289f284",
    "sourceCurrency": "USDC",
    "sourceAmount": "5000.00",
    "purpose": "PROFESSIONAL_SERVICES"
  }'

Response

{
  "id": "9b1c5b8a-3d1f-4a8f-b6e0-2c1b6a7e9f33",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "OFF_RAMP",
  "request": {
    "destinationId": "e80d3137-eddd-4791-b9b8-6e36b289f284",
    "sourceCurrency": "USDC",
    "sourceAmount": "5000.00",
    "purpose": "PROFESSIONAL_SERVICES"
  },
  "state": {
    "status": "TRANSFERRING_STABLECOIN"
  }
}

Repeat the request per payee using a fresh Idempotency-Key each time. There’s no batch endpoint, so run the calls in parallel from your job runner if you need to push a full payroll cycle at once.

Lock in an exchange rate before the payout to guarantee the amount the payee receives. See Exchange Rates.

Step 6: Track payout status

Each off-ramp transaction follows this lifecycle: TRANSFERRING_STABLECOIN → TRADING → TRANSFERRING_FIAT → SUCCESS Subscribe to the offramp.success and offramp.failed webhooks to reconcile payouts as they complete and surface status back to the employer in your product. See Webhooks and the Transactions lifecycle reference.

Global accounts

Fund the employer’s wallet via local fiat rails.

Destinations

Holder relationships and verification.

Transactions

Off-ramp lifecycle and purpose codes.

Off-ramp API

Full API reference for off-ramp transactions.

Use Cases

Onboarding

Collect

Pay out

Build with AI

Step 1: Generate your API key

Step 2: Onboard the employer

Step 3: Fund the employer’s wallet

Step 4: Register each payee’s destination

Step 5: Run payroll

Step 6: Track payout status

Global accounts

Destinations

Transactions

Off-ramp API

​Step 1: Generate your API key

​Step 2: Onboard the employer

​Step 3: Fund the employer’s wallet

​Step 4: Register each payee’s destination

​Step 5: Run payroll

​Step 6: Track payout status

​Related resources

Global accounts

Destinations

Transactions

Off-ramp API

Step 1: Generate your API key

Step 2: Onboard the employer

Step 3: Fund the employer’s wallet

Step 4: Register each payee’s destination

Step 5: Run payroll

Step 6: Track payout status

Related resources