The PayZu Crypto API enables two main operations: on-ramp (converting BRL to cryptocurrency) and off-ramp (converting cryptocurrency to BRL). This document explains the complete flow for each operation.

On-Ramp Flow (BRL → Crypto)

The on-ramp flow allows users to purchase cryptocurrency using Brazilian Reais via Pix. The process involves creating a quote, placing an order, and receiving crypto in the destination wallet.

How it works at PayZu

When a user wants to buy crypto, your application creates a quote to lock the exchange rate, then creates an order specifying the destination wallet. The API returns a Pix QR Code that the user scans to complete the payment. Once the Pix is confirmed, the system automatically processes the crypto transfer to the user's wallet.

Throughout the process, webhooks are sent to your callbackUrl with status updates, allowing you to track the order in real-time.

Conceptual Flow of On-Ramp

┌─────────────────────────────────────────────┐
│  User requests crypto purchase              │
│  (e.g., R$ 100 → USDT)                      │
└─────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────┐
│  Create Quote                               │
│  POST /v1/quotes                            │
│  Locks exchange rate for limited time       │
└─────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────┐
│  Create Order                               │
│  POST /v1/orders                            │
│  Returns Pix QR Code for payment            │
│  Status: PENDING_DEPOSIT                    │
└─────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────┐
│  User pays via Pix                          │
│  Scans QR Code in banking app               │
└─────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────┐
│  Payment confirmed                          │
│  Webhook: status = DEPOSIT_RECEIVED         │
└─────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────┐
│  Crypto processing                          │
│  Webhook: status = TRANSFERRING_TO_PARTNER  │
│  Webhook: status = WAITING_CRYPTO           │
│  Webhook: status = CRYPTO_RECEIVED          │
└─────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────┐
│  Crypto sent to user wallet                 │
│  Webhook: status = SENDING_TO_USER          │
└─────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────┐
│  Order completed                            │
│  Webhook: status = COMPLETED                │
│  User receives crypto in wallet             │
└─────────────────────────────────────────────┘

Step-by-Step Integration

1. Create a Quote (Optional but Recommended)

Before creating an order, you can create a quote to lock the exchange rate:

POST /v1/quotes
{
  "symbol": "USDT/BRL",
  "type": "on_ramp",
  "amount": 100,
  "network": "TRX"
}

The quote locks the rate for a limited time (indicated by expiresAt). Use the returned id when creating the order.

2. Create an Order

Create an order with the quote ID or directly with amount:

POST /v1/orders
{
  "quoteId": "550e8400-e29b-41d4-a716-446655440000",
  "destination": {
    "asset": "USDT",
    "network": "TRX",
    "address": "TXyz1234567890abcdef"
  },
  "callbackUrl": "https://your-server.com/webhooks/crypto"
}

The response includes a Pix QR Code that the user must pay.

3. User Completes Pix Payment

Display the QR Code to the user. They scan it with their banking app and complete the payment. The Pix confirmation is automatic and typically takes a few seconds.

4. Receive Webhooks

As the order progresses, webhooks are sent to your callbackUrl:

{
  "event": "order.updated",
  "order": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "status": "COMPLETED",
    "destination": {
      "txHash": "abc123def456..."
    }
  }
}

5. Order Complete

When status is COMPLETED, the crypto has been sent to the user's wallet. The txHash in the response can be used to verify the transaction on the blockchain.

Important Considerations

Quote Expiration: Quotes expire after a limited time. If expired, create a new quote before ordering.
Minimum Amount: The minimum order amount is R$ 10.
Network Fees: Different networks have different fees. TRX typically has the lowest fees.
Processing Time: Most orders complete within 5-15 minutes after Pix confirmation.
Wallet Validation: Ensure the destination address is valid for the selected network to avoid loss of funds.