SDigital2SDigital2
Integration Flows

On-Ramp + Withdrawal Flow (Fiat to Crypto)

Convert Brazilian Real (BRL) to cryptocurrency and then withdraw it to an external wallet

Back to Integration Flows

Overview

There are two ways to create on-ramp transactions:

  1. With Exchange Rate Quote - Lock in rates for price certainty
  2. Without Quote (Market Rate) - Use market rates at execution time

Method 1: With Exchange Rate Quote

This method provides rate certainty by locking in exchange rates before creating the transaction.

Flow Overview

Step 1: Get Exchange Rate Quote for On-Ramp

Request a quote for converting BRL to cryptocurrency:

curl -X POST "https://api.sdigital2.com/v1/exchange-rates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "ETHEREUM",
    "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
    "sourceCurrency": "BRL",
    "sourceAmount": "100.00",
    "destinationCurrency": "USDC",
    "lockDuration": "30s"
  }'

Response:

{
  "id": "272d9849-d212-4218-b39f-d4ead3ca514c",
  "sourceCurrency": "BRL",
  "sourceAmount": "100.00",
  "destinationCurrency": "USDC",
  "destinationAmount": "17.489663",
  "grossDestinationAmount": "18.685864",
  "baseExchangeRate": "0.186858",
  "appliedExchangeRate": "0.174896",
  "fees": {
    "bps": "105",
    "flatAmount": "1",
    "totalAmount": "1.1962",
    "currency": "USDC"
  },
  "expiresAt": "2025-09-13T20:07:08.596Z"
}

Step 2: Create On-Ramp Transaction with Quote

Create the on-ramp transaction:

curl -X POST "https://api.sdigital2.com/v1/transactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
    "source": {
      "paymentRail": "PIX"
    },
    "destination": {
      "paymentRail": "ETHEREUM"
    },
    "exchangeRateId": "272d9849-d212-4218-b39f-d4ead3ca514c",
    "purpose": "INVESTMENT"
  }'

Response includes payment instructions:

{
  "id": "aff65090-68ef-4d81-b06f-509ccbe51d00",
  "type": "ON_RAMP",
  "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
  "sourceAmount": "100",
  "source": {
    "currency": "BRL",
    "paymentRail": "PIX"
  },
  "destination": {
    "currency": "USDC",
    "paymentRail": "ETHEREUM"
  },
  "purpose": "INVESTMENT",
  "createdAt": "2025-09-13T20:06:54.738Z",
  "updatedAt": "2025-09-13T20:06:54.735Z",
  "status": "AWAITING_FUNDS",
  "depositInstructions": {
    "paymentRail": "PIX",
    "brCode": "000201010212268..."
  }
}

Step 3: Customer Makes PIX Payment

Provide the PIX Code to your customer. They need to make the PIX payment using their banking app or PIX-enabled service.

For Integration:

  • Display the PIX Code as a QR code for mobile users
  • Provide the PIX Code as copyable text for desktop users
  • Set a reasonable timeout for payment completion
  • Provide clear instructions on how to make PIX payments

Step 4: Monitor Transaction Completion

Poll the transaction status until it completes:

curl -X GET "https://api.sdigital2.com/v1/transactions/{transaction_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Completed On-Ramp Response:

{
  "id": "85ebd88b-e19b-4fa9-9250-efacc063b7cc",
  "type": "ON_RAMP",
  "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
  "sourceAmount": "100",
  "source": {
    "currency": "BRL",
    "paymentRail": "PIX"
  },
  "destination": {
    "currency": "USDC",
    "paymentRail": "ETHEREUM"
  },
  "purpose": "INVESTMENT",
  "createdAt": "2025-09-08T22:55:07.897Z",
  "updatedAt": "2025-09-08T22:55:07.888Z",
  "status": "SUCCESS",
  "depositInstructions": {
    "paymentRail": "PIX",
    "brCode": "000201010212268..."
  },
  "receipt": {
    "sourceCurrency": "BRL",
    "sourceAmount": "100.00",
    "destinationCurrency": "USDC",
    "destinationAmount": "17.489663",
    "grossDestinationAmount": "18.685864",
    "baseExchangeRate": "0.184458",
    "appliedExchangeRate": "0.182181",
    "fees": {
      "bps": "15",
      "flatAmount": "1",
      "totalAmount": "1.138343",
      "currency": "USDC"
    }
  }
}

Once complete, the customer's USDC balance on Ethereum will be updated with the converted amount.

Step 5: Create Withdrawal

After the on-ramp transaction completes, create a withdrawal to send the cryptocurrency to an external wallet:

curl -X POST "https://api.sdigital2.com/v1/withdrawals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
    "currency": "USDC",
    "amount": "17.489663",
    "chain": "ETHEREUM",
    "destinationWalletAddress": "0x742d35Cc6634C0532925a3b8D8C9C2e3C8b4f8E9"
  }'

Response:

{
  "id": "c2e3d98a-b40d-4d60-896e-ae7bb6716948",
  "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
  "currency": "USDC",
  "amount": "17.489663",
  "chain": "ETHEREUM",
  "destinationWalletAddress": "0x2fc4512d5859226cf0bf61fbbbdb5444fda60053",
  "createdAt": "2025-09-13T18:01:00.764Z",
  "updatedAt": "2025-09-13T18:01:00.756Z",
  "status": "PENDING"
}

Important: Ensure the destination wallet address is valid for the selected blockchain network. Transactions cannot be reversed!

Step 6: Monitor Withdrawal Status

Track the withdrawal progress:

curl -X GET "https://api.sdigital2.com/v1/withdrawals/{withdrawal_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Completed Withdrawal Response:

{
  "id": "c2e3d98a-b40d-4d60-896e-ae7bb6716948",
  "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
  "currency": "USDC",
  "amount": "17.489663",
  "chain": "ETHEREUM",
  "destinationWalletAddress": "0x2fc4512d5859226cf0bf61fbbbdb5444fda60053",
  "createdAt": "2025-09-13T18:01:00.764Z",
  "updatedAt": "2025-09-13T18:01:00.756Z",
  "status": "SUCCESS",
  "receipt": {
    "transactionHash": "0xb1189aa2a2c17eff237ece7a99bc284d70218ee13f3dea8e0027227d97244ca8",
    "blockExplorerUrl": "https://etherscan.io/tx/0xb1189aa2a2c17eff237ece7a99bc284d70218ee13f3dea8e0027227d97244ca8"
  }
}

Method 2: Without Exchange Rate Quote (Market Rate)

This method uses market rates at execution time, requiring fewer API calls but without rate guarantees.

Flow Overview

Step 1: Create On-Ramp Transaction with Market Rate

Create the transaction directly without an exchange rate quote. You'll need to specify additional fields:

curl -X POST "https://api.sdigital2.com/v1/transactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
    "sourceAmount": "100.00",
    "source": {
      "paymentRail": "PIX",
      "currency": "BRL"
    },
    "destination": {
      "paymentRail": "ETHEREUM",
      "currency": "USDC"
    },
    "purpose": "INVESTMENT"
  }'

Key Differences from Method 1:

  • No exchangeRateId field
  • Must specify sourceAmount field
  • Must specify currency in the source and destination objects
  • Exchange rate is determined at execution time

Response includes payment instructions:

{
  "id": "82c1bfb7-ef1e-42e3-94d3-8c8b7677b14d",
  "type": "ON_RAMP",
  "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
  "status": "PENDING",
  "depositInstructions": {
    "paymentRail": "PIX",
    "brCode": "000201010212268..."
  },
  "sourceAmount": "100.00",
  "source": {
    "currency": "BRL",
    "paymentRail": "PIX"
  },
  "destination": {
    "currency": "USDC",
    "paymentRail": "ETHEREUM"
  },
  "purpose": "INVESTMENT",
  "createdAt": "2025-09-13T18:01:00.764Z",
  "updatedAt": "2025-09-13T18:01:00.756Z"
}

Step 2: Customer Makes PIX Payment

Follow the same process as Method 1 - provide the PIX Code to your customer for payment.

Step 3: Monitor Transaction Completion

Monitor the transaction status the same way as Method 1. The final receipt will include the actual exchange rate that was applied:

{
  "id": "82c1bfb7-ef1e-42e3-94d3-8c8b7677b14d",
  "type": "ON_RAMP",
  "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
  "status": "SUCCESS",
  "sourceAmount": "100.00",
  "source": {
    "currency": "BRL",
    "paymentRail": "PIX"
  },
  "destination": {
    "currency": "USDC",
    "paymentRail": "ETHEREUM"
  },
  "purpose": "INVESTMENT",
  "receipt": {
    "sourceCurrency": "BRL",
    "sourceAmount": "100.00",
    "destinationCurrency": "USDC",
    "destinationAmount": "17.489663",
    "grossDestinationAmount": "17.751389",
    "baseExchangeRate": "0.177514",
    "appliedExchangeRate": "0.174897",
    "fees": {
      "bps": "150",
      "flatAmount": "0.5",
      "totalAmount": "0.761726",
      "currency": "USDC"
    }
  },
  "createdAt": "2025-09-13T18:01:00.764Z",
  "updatedAt": "2025-09-13T18:01:00.756Z"
}

Steps 4-5: Create and Monitor Withdrawal

Follow the same withdrawal process as Method 1 to send the cryptocurrency to an external wallet.

Market Rate Considerations:

  • Exchange rates fluctuate in real-time
  • Final crypto amounts may differ from estimates
  • Best for users who prioritize simplicity over rate certainty
  • Consider showing rate estimates in your UI before confirmation

Choosing the Right Method

Use Method 1 (With Quote) when:

  • Users need price certainty before confirming
  • Building trading or financial applications
  • Handling large transaction amounts
  • Users are price-sensitive

Use Method 2 (Market Rate) when:

  • Building simple conversion tools
  • Users prioritize speed over precision
  • Handling smaller transaction amounts
  • Rate fluctuations are acceptable

Next Steps

Off-Ramp Flow

Learn how to convert crypto to fiat

API Reference

Explore detailed endpoint documentation and schemas

Off-Ramp Flow (Crypto to Fiat)

Convert cryptocurrency (USDT/USDC) to Brazilian Real (BRL) and send funds via PIX

On this page

OverviewMethod 1: With Exchange Rate QuoteFlow OverviewStep 1: Get Exchange Rate Quote for On-RampStep 2: Create On-Ramp Transaction with QuoteStep 3: Customer Makes PIX PaymentStep 4: Monitor Transaction CompletionStep 5: Create WithdrawalStep 6: Monitor Withdrawal StatusMethod 2: Without Exchange Rate Quote (Market Rate)Flow OverviewStep 1: Create On-Ramp Transaction with Market RateStep 2: Customer Makes PIX PaymentStep 3: Monitor Transaction CompletionSteps 4-5: Create and Monitor WithdrawalChoosing the Right MethodNext Steps