Convert Brazilian Real (BRL) to stablecoins (USDC or USDT) via PIX payment.

​
Prerequisites

Before initiating an on-ramp transaction:
  1. Verified Customer: Customer must be KYC-approved (see onboarding guides)
  2. Exchange Rate (Optional): Get a quote or lock a rate (see exchange rate guides)
  3. Partner Fee (Optional): Configure custom fees (see partner fees)

​
Transaction Flow

1

Initiate On-Ramp

Submit transaction request with amount and currencies
2

Receive Payment Instructions

Get PIX QR code or payment details
3

Customer Makes Payment

Customer pays via PIX within time limit
4

Payment Confirmation

System detects and confirms payment
5

Stablecoin Delivery

USDC/USDT credited to customer’s wallet

​
Creating an On-Ramp Transaction

​
Option 1: With Floating Rate

Use current market rates that adjust at execution time: 
curl -X POST https://api.lumx.io/transactions/on-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sourceCurrency": "BRL",
    "sourceAmount": "10000.00",
    "targetCurrency": "USDC",
    "payment": {
      "rail": "pix"
    },
    "partnerFeeId": "123e4567-e89b-12d3-a456-426614174004"
  }'

​
Request Parameters

ParameterTypeRequiredDescription
customerIdstringYesUUID of the verified customer
sourceCurrencystringYesMust be "BRL"
sourceAmountstringYesAmount in BRL to convert
targetCurrencystringYes"USDC" or "USDT"
payment.railstringYesMust be "pix"
partnerFeeIdstringNoUUID of partner fee configuration

​
Option 2: With Locked Rate

Use a pre-locked exchange rate for guaranteed conversion: 
curl -X POST https://api.lumx.io/transactions/on-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "exchangeRateId": "123e4567-e89b-12d3-a456-426614174000",
    "payment": {
      "rail": "pix"
    }
  }'

​
Request Parameters

ParameterTypeRequiredDescription
customerIdstringYesUUID of the verified customer
exchangeRateIdstringYesUUID of locked exchange rate
payment.railstringYesMust be "pix"

​
Transaction Response

​
Initial Response (Awaiting Funds)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "on_ramp",
  "request": {
    "sourceCurrency": "BRL",
    "sourceAmount": "10000.00",
    "targetCurrency": "USDC",
    "payment": {
      "rail": "pix"
    }
  },
  "state": {
    "status": "awaiting_funds",
    "payment": {
      "rail": "pix",
      "brCode": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5915Test Merchant6009Sao Paulo62070503***63041234"
    }
  },
  "createdAt": "2024-03-20T15:30:00Z",
  "updatedAt": "2024-03-20T15:30:05Z"
}

​
Key Response Fields

FieldDescription
idUnique transaction identifier
state.statusCurrent transaction status
state.payment.brCodePIX QR code data for payment

​
PIX Payment Instructions

Use the brCode field to generate a QR code or provide as text for PIX Copia e Cola.
PIX payments have a time limit. Ensure prompt payment completion.

​
Transaction Status Monitoring

Monitor transaction progress by polling the transaction endpoint: 
curl -X GET https://api.lumx.io/transactions/{transactionId} \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Transaction Statuses

awaiting_funds

Waiting for customer’s PIX payment

processing

Payment received, minting stablecoins

success

Stablecoins delivered to wallet

failed

Transaction failed or expired

​
Success Response

{
  "id": "123e4567-e89b-12d3-a456-426614174002",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "on_ramp",
  "request": {
    "sourceCurrency": "BRL",
    "sourceAmount": "10000.00",
    "targetCurrency": "USDC",
    "payment": {
      "rail": "pix"
    }
  },
  "state": {
    "status": "success",
    "payment": {
      "rail": "pix",
      "brCode": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5915Test Merchant6009Sao Paulo62070503***63041234"
    },
    "receipt": {
      "rate": "6.0066",
      "sourceAmount": "10000.00",
      "targetAmount": "1664.44",
      "sourceCurrency": "BRL",
      "targetCurrency": "USDC",
      "fees": {
        "currency": "USDC",
        "lumx": {
          "percentage": "10.000000",
          "flat": "1"
        },
        "developer": {
          "percentage": "0.000000",
          "flat": "0"
        }
      }
    },
    "blockchain": {
      "transactionHash": "0x1234567890123456789012345678901234567890",
      "blockExplorerUrl": "https://amoy.polygonscan.com/tx/0x1234567890123456789012345678901234567890"
    }
  },
  "createdAt": "2024-03-20T15:30:00Z",
  "updatedAt": "2024-03-20T15:35:00Z"
}

​
Next Steps

Off-Ramp Guide

Convert stablecoins back to fiat

Transfer Guide

Send funds between customers

Webhooks

Set up real-time notifications