Transactions

Understanding on-ramp and off-ramp transactions with exchange rates in the SDigital2 API

Back to Core Concepts

Overview

Transactions are the core of the SDigital2 API, enabling cryptocurrency-to-fiat (off-ramp) and fiat-to-cryptocurrency (on-ramp) conversions. Each transaction has a lifecycle that begins with creation and progresses through various statuses until completion or failure.

Transaction Types

OFF_RAMP (Crypto to Fiat):

Convert cryptocurrency (USDT/USDC) to Brazilian Real (BRL)
Funds are sent via PIX to a verified bank account
Requires sufficient cryptocurrency balance
Destination must specify a bankAccountId for the PIX payment

ON_RAMP (Fiat to Crypto):

Convert Brazilian Real (BRL) to cryptocurrency (USDT/USDC)
Customer makes PIX payment using provided PIX BR Code
Cryptocurrency is credited to customer's balance
Destination specifies the blockchain network and currency

Transaction Lifecycle

On-Ramp Transaction Lifecycle

Off-Ramp Transaction Lifecycle

Transaction Statuses

AWAITING_FUNDS: The transaction has been created and is waiting for the customer's deposit on the selected payment rail.
TRANSFERRING_FIAT: The deposit has been identified and the system is confirming fiat settlement.
TRADING: Funding is confirmed and the source currency is being converted to the target currency.
TRANSFERRING_STABLECOIN: The stablecoin is being sent to the destination wallet.
SUCCESS: Transaction completed successfully.
FAILED: The transaction failed or expired.
REFUNDING: The transaction failed and funds are being sent back to the originating account.
REFUNDED: Funds have been successfully returned to the originating account.

Transaction Purposes

When creating a transaction, you must specify a purpose:

PERSONAL_ACCOUNT: Personal transfers to own accounts (requires SELF bank account relationship)
INVESTMENT: Investment-related transactions
REAL_ESTATE: Real estate purchases or payments
TRADE_TRANSACTIONS: Commercial trade and goods
TAX: Tax payments
LOAN: Loan disbursements or repayments
BILLS: Bill payments
EXPENSES_REIMBURSEMENT: Expense reimbursements
PROFESSIONAL_SERVICES: Professional service payments

Exchange Rate Locking

One of the key features of the SDigital2 API is exchange rate locking, which ensures price certainty for your users during the transaction process.

How Exchange Rate Locking Works

Request a Quote: Call the exchange rates endpoint with your desired conversion parameters
Receive Locked Rate: Get a time-limited quote with guaranteed exchange rates
Use in Transaction: Reference the quote ID when creating a transaction to lock in the rate
Price Protection: The locked rate is guaranteed regardless of market fluctuations during the lock period

Lock Duration Options

30 seconds (30s) - For quick transactions
1 minute (1m) - Standard duration
5 minutes (5m) - Extended time for complex flows

Exchange Rate Quote Example

{
  "id": "e4fdeef0-fdbd-4aeb-9669-9205d5455ae2",
  "sourceCurrency": "USDC",
  "sourceAmount": "100.000000",
  "destinationCurrency": "BRL",
  "destinationAmount": "524.20",
  "grossDestinationAmount": "535.17",
  "baseExchangeRate": "5.351740",
  "appliedExchangeRate": "5.242029",
  "fees": {
    "bps": "105",
    "flatAmount": "1",
    "totalAmount": "2.05",
    "currency": "USDC"
  },
  "expiresAt": "2025-09-13T08:12:04.695Z"
}

PIX Payment Timing: For PIX on-ramp flows, if funds are not sent before the quote expires but the customer still eventually sends the funds, an automatic refund will be sent back to the sending account. If the automatic refund doesn't occur, please reach out to the SDigital2 team for assistance.

Understanding the Base Exchange Rate

The baseExchangeRate is SDigital2's internal exchange rate used as the foundation for currency conversions. This is not the mid-market rate that you might see on financial websites or trading platforms.

Key Points about the Base Exchange Rate

Internal Rate: The baseExchangeRate is an internal SDigital2 rate, not the mid-market rate
Pre-Fee Rate: This is the base exchange rate before fees are applied
Market Hours Accuracy: During weekdays from 10 AM to 4 PM America/Sao_Paulo, the baseExchangeRate will be very close to the mid-market rate
No Guarantees Outside Market Hours: There are no guarantees about how close the rate will be to mid-market rates outside of business hours (evenings, nights) and on weekends
Fee Application: The final appliedExchangeRate includes all fees applied to the baseExchangeRate

Rate Timing Considerations

Optimal Timing: For the most competitive rates closest to mid-market prices, consider timing your transactions during São Paulo business hours (10 AM - 4 PM America/Sao_Paulo, Monday through Friday).

During Market Hours (10 AM - 4 PM America/Sao_Paulo, Weekdays):

Base exchange rates closely track mid-market rates
Most competitive pricing available

Outside Market Hours (Evenings, Nights, Weekends):

Rates may deviate more significantly from mid-market rates
Larger spreads may be applied to account for market volatility

Rate vs. Fee Structure

Understanding the relationship between different rate fields in exchange rate quotes:

baseExchangeRate - SDigital2's internal rate before any fees
appliedExchangeRate - Final rate after all fees are applied
grossDestinationAmount - Amount calculated using the base rate
destinationAmount - Final amount after fees are deducted

Transactions

On this page