​
What are Transactions?

Transactions are how money moves in Lumx. There are three main types:
  1. On-Ramp - Converting regular money (BRL) into digital money (USDC/USDT)
  2. Off-Ramp - Converting digital money back to regular money
  3. Transfer - Sending digital money between wallets
Think of it like this:
  • On-ramp = Depositing cash into the digital world
  • Off-ramp = Withdrawing digital money as cash
  • Transfer = Sending digital money to someone else

​
On-Ramp: Fiat to Crypto

When your customer wants to buy stablecoins with Brazilian Reais.

​
How It Works

1

Customer Requests

Customer wants to convert R$1,000 to USDC
2

Get PIX Code

System generates a PIX QR code for payment
3

Customer Pays

Customer scans and pays via their bank app
4

Receive Stablecoins

USDC appears in customer’s wallet (usually within minutes)

​
Real Example

Maria wants to buy $100 worth of USDC:
  1. She requests to convert ~R$600 (depending on exchange rate)
  2. Gets a PIX QR code to pay
  3. Pays using her bank app
  4. Receives USDC in her Lumx wallet

​
Transaction States

StatusWhat It MeansWhat Customer Sees
awaiting_fundsWaiting for PIX payment”Please complete your payment”
processingPayment received, converting”Processing your purchase…”
successComplete!”USDC added to your wallet”
failedSomething went wrong”Transaction failed - refund initiated”

​
Off-Ramp: Crypto to Fiat

When your customer wants to convert their stablecoins back to Brazilian Reais.

​
How It Works

1

Customer Requests

Customer wants to convert 100 USDC to BRL
2

Provide PIX Key

Customer enters their PIX key (CPF, email, phone, etc.)
3

Confirm Transaction

System deducts USDC from wallet
4

Receive Money

BRL arrives in customer’s bank account via PIX

​
Real Example

João wants to cash out 100 USDC:
  1. He requests to convert 100 USDC to BRL
  2. Enters his PIX key (CPF: 123.456.789-00)
  3. USDC is deducted from his wallet
  4. Receives ~R$600 in his bank account

​
PIX Key Types Supported

TypeExampleDescription
CPF123.456.789-00Individual tax ID
CNPJ12.345.678/0001-00Business tax ID
Emailuser@example.comEmail address
Phone+5511999999999Phone number
Random123e4567-e89b-12d3...Random key (EVP)

​
Transfer: Wallet to Wallet

Moving stablecoins between Lumx customers or to external wallets.

​
How It Works

1

Choose Recipient

Select another Lumx customer or enter a wallet address
2

Enter Amount

Specify how much USDC or USDT to send
3

Confirm

Review and confirm the transfer
4

Instant Delivery

Funds arrive instantly in recipient’s wallet

​
Transfer Types

To Lumx Customer

Send to another user in your platform using their customer ID

To External Wallet

Send to any blockchain wallet address (like 0x123…)

​
Transaction Lifecycle

All transactions follow a similar pattern:

​
Understanding Fees

Every transaction may include fees:
  • Lumx Fee: Platform fee for processing
  • Partner Fee: Optional fee you can add for your revenue
  • Network Fee: Blockchain gas fees (covered by Lumx)

​
Fee Example

Customer wants to buy 100 USDC with BRL

Base amount: 100 USDC
Lumx fee (1%): -1 USDC
Partner fee (0.5%): -0.5 USDC
-------------------
Customer receives: 98.5 USDC

​
Settlement Times

How fast transactions complete:
Transaction TypeTypical TimeMaximum Time
On-Ramp (PIX)1-5 minutes30 minutes
Off-Ramp (PIX)1-5 minutes30 minutes
TransferInstant2 minutes
PIX operates 24/7, so transactions work any time, including weekends and holidays.

​
Common Scenarios

​
E-commerce Payment

  1. Customer buys a product for 100 USDC
  2. Transfer from customer wallet to merchant wallet
  3. Merchant can keep USDC or off-ramp to BRL

​
International Remittance

  1. Customer in Brazil on-ramps BRL to USDC
  2. Transfers USDC to family member’s wallet
  3. Family member off-ramps to their local currency

​
Salary Payment

  1. Company on-ramps payroll amount to USDC
  2. Batch transfers to employee wallets
  3. Employees off-ramp as needed

​
Transaction Safety

All transactions are:
  • Recorded on blockchain - Permanent, transparent record
  • Non-reversible - Once complete, cannot be undone
  • KYC verified - Only verified customers can transact
  • Monitored - Automatic fraud and AML checks

​
Transaction Best Practices

​
On-Ramp Transactions

  • Display clear payment countdown timers
  • Provide both QR code and copy-paste PIX options
  • Implement webhook listeners for real-time updates
  • Handle expired transactions gracefully

​
Off-Ramp Transactions

  • Validate PIX key format before submission
  • Confirm recipient details clearly
  • Check balance before initiating
  • Implement proper error handling

​
Transfer Transactions

  • Validate wallet addresses (0x + 40 hex characters)
  • Check sender balance before transfer
  • Implement transfer limits and velocity checks
  • Log all transfer attempts for security

​
Compliance and Security

​
Transaction Monitoring

All transactions are subject to:
  • Anti-money laundering (AML) checks
  • Sanctions screening for external addresses
  • Reporting requirements for large amounts
  • Travel Rule compliance for cross-border transfers

​
PIX Payment Considerations

  • PIX payments have time limits (typically 30 minutes)
  • Transfers to PIX keys are irreversible once processed
  • Always verify PIX key ownership before off-ramp

​
Error Handling

Common transaction errors and solutions:
ErrorCauseSolution
Insufficient BalanceNot enough fundsCheck balance before transaction
Invalid AddressMalformed wallet addressValidate format client-side
Transaction ExpiredPayment time limit exceededCreate new transaction
Limit ExceededOver daily/monthly limitSplit transaction or wait

​
Common Questions

​
Next Steps

Ready to start building?

Customer Setup

Create and verify customers

Process Payments

Accept fiat payments

Send Money

Transfer between wallets