Skip to main content

​
Gateway API — Flow Examples

All endpoints require authentication via API key and signature.

​
Response structure

All endpoints return the same flat, client-friendly envelope: 
{
  "error_code": null,
  "message": null,
  "data": {}
}
  • On success: error_code and message are null; data holds the payload.
  • On error: error_code and message are populated; data is null (or contains field-level details when applicable).
List endpoints embed pagination inside data alongside results (or a custom wrapper key): 
{
  "error_code": null,
  "message": null,
  "data": {
    "results": [ ... ],
    "pagination": {
      "count": 94,
      "next": "https://api.ripio.com/wallet/transactions/?page=2",
      "previous": null,
      "per_page": 20,
      "total_pages": 5
    }
  }
}
Cursor-paginated endpoints (see high-volume flows) return nc / pc instead of pagination: 
{
  "error_code": null,
  "message": null,
  "data": {
    "results": [ ... ],
    "nc": "cD0yMDI2LTAyLTI0KzAw...",
    "pc": null
  }
}
nc = next cursor, pc = previous cursor. These are opaque base64 tokens — the client must pass them back verbatim via ?cursor=<token> without parsing them.

​
Flow 1: Crypto Send

To perform a crypto send you need the network and the network_fee for the currency being sent. Both are retrieved from the networks endpoint.

​
Step 1 — Fetch available networks for the currency

Required permission: general_data_read 
GET /network/currency-networks/USDT/
Response: 
{
  "error_code": null,
  "message": null,
  "data": [
    {
      "currency": "USDT",
      "currency_balance_id": 14,
      "network": {
        "id": 3,
        "code": "ethereum",
        "name": "Ethereum",
        "status_tag": null,
        "deliver_time": "~10 min",
        "enabled": true,
        "use_memo": false
      },
      "native_network": false,
      "standard": "ERC20",
      "network_standard": "ERC20",
      "fee": "2.50",
      "fee_tag": null,
      "send": true,
      "receive": true,
      "order": 1,
      "enabled": true,
      "min_amount": "10.00",
      "max_amount": null,
      "is_partial_disabled_send": false,
      "is_partial_disabled_receive": false,
      "messages": []
    },
    {
      "currency": "USDT",
      "currency_balance_id": 14,
      "network": {
        "id": 7,
        "code": "tron",
        "name": "Tron (TRC20)",
        "status_tag": null,
        "deliver_time": "~5 min",
        "enabled": true,
        "use_memo": false
      },
      "native_network": false,
      "standard": "TRC20",
      "network_standard": "TRC20",
      "fee": "1.00",
      "fee_tag": null,
      "send": true,
      "receive": true,
      "order": 2,
      "enabled": true,
      "min_amount": "5.00",
      "max_amount": null,
      "is_partial_disabled_send": false,
      "is_partial_disabled_receive": false,
      "messages": []
    }
  ]
}
Relevant fields to extract:
  • network.code → value to use in gateway_data.network of the send request
  • fee → value to use in network_fee of the send request
  • send: true → confirms that sending is enabled for that network
  • network.use_memo → indicates whether a memo_id must be included

​
Step 2 (optional) — Verify the crypto gateway is enabled

Required permission: general_data_read 
GET /transactions/gateways/?gateway=crypto&action=SEND
Response: 
{
  "error_code": null,
  "message": null,
  "data": [
    {
      "gateway": "crypto",
      "name": "Crypto",
      "order": 1,
      "actions": [
        {
          "action": "SEND",
          "schemas": [2, 3, 4],
          "enabled": true,
          "account_enabled": true,
          "fee": "0.00",
          "fixed_fee": "0.00",
          "alt_fee": null,
          "alt_fee_currency": null,
          "custom_fee_currencies": {},
          "taxes": [],
          "deliver_time": "~10 min",
          "extra_data": {},
          "blocked": false
        }
      ]
    }
  ]
}
Verify that enabled: true, account_enabled: true, and blocked: false.

​
Step 3 — Execute the send

Required permission: withdrawal_write 
POST /transactions/crypto/send/
Body (using data from Step 1 — Tron network): 
{
  "amount": "50.00",
  "currency": "USDT",
  "address_to": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "gateway": "crypto",
  "network_fee": "1.00",
  "gateway_data": {
    "network": "tron",
    "memo_id": null
  },
  "otp_code": "123456"
}
Note on OTP code: otp_code parameter is NOT needed for send to a whitelisted address. Addresses can be whitelisted from Ripio App. Public endpoint to whitelist addressess and bank accounts is coming soon.
Note on network fee: Although the backend validates network_fee, the client must send it explicitly (retrieved from the network endpoint). This allows knowing the total cost of the operation (amount + network_fee) upfront before confirming it. Without this value, the backend would deduct the fee from the sent amount and the recipient would receive less than expected. The network_fee value is honored as long as the transaction is accepted.
Response (201 Created): 
{
  "error_code": null,
  "message": null,
  "data": {
    "id": 7823941,
    "external_id": null,
    "operation_type": "SEND",
    "txn_type": "SEN",
    "gateway": "crypto",
    "gateway_details": "tron",
    "from_currency": "USDT",
    "to_currency": "USDT",
    "fiat_currency": "ARS",
    "fee_currency": "USDT",
    "fee": "1.00",
    "fee_fiat": "1050.00",
    "rate": "1.00",
    "rate_usd": "1.00",
    "amount_from": "50.00",
    "amount_to": "50.00",
    "amount_fiat": "52500.00",
    "amount_usd": "50.00",
    "status": "PEN",
    "created_at": "2026-04-16T14:32:00Z",
    "updated_at": "2026-04-16T14:32:00Z",
    "origin": null,
    "destination": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "tax": "0.00",
    "tax_currency": null,
    "extra_data": {}
  }
}
Note on memo networks: For networks that use a memo such as XRP (use_memo: true), memo_id must be included in gateway_data.
Business rule errors:
error_codeCondition
GTW_0404Gateway crypto is disabled or not enabled for the account
CUR_0403Currency is disabled or not available for sending
NET_0400gateway_data.network value is unknown
NET_0401Network exists but send is currently disabled for that currency
ADR_0400Address is invalid for the selected network (includes sending to own address)
ADR_0401Destination address is blacklisted
ADR_0402Address flagged as high risk by compliance
FEE_0401network_fee is below the accepted minimum for the current conditions
TXN_0401Amount is below the network minimum or above the network maximum
OTP_0401OTP code required but not provided (send above amount threshold)
OTP_0400OTP code is incorrect
When there are errors in multiple fields, error_code/message surface the first one (useful for a toast notification) and data preserves the full structure for mapping errors to each form input.

​
Flow 2: CVU Withdrawal (Argentina)

Only available for accounts with country: AR and an assigned CVU. Withdraws ARS to a previously verified CVU/CBU bank account.

​
Step 1 — Fetch gateway limits

Required permission: general_data_read 
GET /transactions/limits/?gateway=bank-transfer-cvu&action=WITHDRAWAL
Response: 
{
  "error_code": null,
  "message": null,
  "data": [
    {
      "gateway": "bank-transfer-cvu",
      "actions": [
        {
          "action": "WITHDRAWAL",
          "schema": 3,
          "currency": "ARS",
          "currency_balance_id": 1,
          "display_currency": "ARS",
          "limits": {
            "min_amount": "500.00",
            "max_amount": "500000.00",
            "daily_amount": "500000.00",
            "daily_qty": 5,
            "monthly_amount": "5000000.00",
            "monthly_qty": 50,
            "annual_amount": null,
            "annual_qty": null
          },
          "remaining": {
            "daily_amount": "350000.00",
            "daily_qty": 4,
            "monthly_amount": "4500000.00",
            "monthly_qty": 48,
            "annual_amount": null,
            "annual_qty": null
          }
        }
      ]
    }
  ]
}
Verify that the amount to withdraw is between min_amount and max_amount, and that remaining.daily_amount is sufficient.

​
Step 2 — Execute the CVU withdrawal

Required permission: withdrawal_write 
POST /transactions/bank-transfer-cvu/withdrawal/
Body: 
{
  "amount": "10000.00",
  "currency": "ARS",
  "gateway_data": {
    "bank_account": "un.alias.ejemplo"
  },
  "otp_code": "123456"
}
bank_account can be an alias, CBU, or external CVU as the destination.
Note on OTP code: otp_code parameter is only needed for transfers to third party accounts. Endpoint to whitelist (no need for OTP) bank accounts coming soon.
Response (201 Created): 
{
  "error_code": null,
  "message": null,
  "data": {
    "id": 7823950,
    "external_id": null,
    "operation_type": "WITHDRAWAL",
    "txn_type": "WIT",
    "gateway": "bank-transfer-cvu",
    "gateway_details": null,
    "from_currency": "ARS",
    "to_currency": "ARS",
    "fiat_currency": "ARS",
    "fee_currency": "ARS",
    "fee": "0.00",
    "fee_fiat": "0.00",
    "rate": "1.00",
    "rate_usd": "0.00095",
    "amount_from": "10000.00",
    "amount_to": "10000.00",
    "amount_fiat": "10000.00",
    "amount_usd": "9.50",
    "status": "PEN",
    "created_at": "2026-04-16T15:00:00Z",
    "updated_at": "2026-04-16T15:00:00Z",
    "origin": null,
    "destination": "0720461088000000012345",
    "tax": "0.00",
    "tax_currency": null,
    "extra_data": {}
  }
}
Business rule errors:
error_codeCondition
TXN_0500Account country is not AR
GTW_0404CVU gateway is disabled
TXN_0450bank_account not provided in gateway_data
CVU_1000Account does not have a Ripio CVU
CVU_1006Account’s CVU is temporarily blocked
CVU_1005bank_account format is invalid, or destination account is not in ARS
OTP_0401OTP required but not provided (third-party transfer above amount threshold)
OTP_0400OTP code is incorrect

​
Flow 3: PIX Withdrawal (Brazil)

Only available for accounts with country: BR. Withdraws BRL using a destination PIX key.

​
Step 1 — Fetch gateway limits

Required permission: general_data_read 
GET /transactions/limits/?gateway=pix&action=WITHDRAWAL
Response: 
{
  "error_code": null,
  "message": null,
  "data": [
    {
      "gateway": "pix",
      "actions": [
        {
          "action": "WITHDRAWAL",
          "schema": 3,
          "currency": "BRL",
          "currency_balance_id": 2,
          "display_currency": "BRL",
          "limits": {
            "min_amount": "10.00",
            "max_amount": "20000.00",
            "daily_amount": "20000.00",
            "daily_qty": 10,
            "monthly_amount": "100000.00",
            "monthly_qty": 100,
            "annual_amount": null,
            "annual_qty": null
          },
          "remaining": {
            "daily_amount": "18500.00",
            "daily_qty": 9,
            "monthly_amount": "95000.00",
            "monthly_qty": 98,
            "annual_amount": null,
            "annual_qty": null
          }
        }
      ]
    }
  ]
}

​
Step 2 — Execute the PIX withdrawal

Required permission: withdrawal_write 
POST /transactions/pix/withdrawal/
Body: 
{
  "amount": "500.00",
  "currency": "BRL",
  "gateway_data": {
    "pix_key": "[email protected]"
  },
  "otp_code": 123456
}
Note on OTP code: otp_code is only required for transfers to third-party PIX keys above the configured amount threshold. For PIX keys registered in the user’s own account (/banking/pix/), it can be omitted.
Valid pix_key examples:
  • CPF: "123.456.789-00" or "12345678900"
  • Email: "[email protected]"
  • Phone: "+5511999990000"
  • Random key (EVP): "e5f3b2a1-4c6d-11ed-bdc3-0242ac120002"
Response (201 Created): 
{
  "error_code": null,
  "message": null,
  "data": {
    "id": 7823960,
    "external_id": null,
    "operation_type": "WITHDRAWAL",
    "txn_type": "WIT",
    "gateway": "pix",
    "gateway_details": null,
    "from_currency": "BRL",
    "to_currency": "BRL",
    "fiat_currency": "BRL",
    "fee_currency": "BRL",
    "fee": "0.00",
    "fee_fiat": "0.00",
    "rate": "1.00",
    "rate_usd": "0.19",
    "amount_from": "500.00",
    "amount_to": "500.00",
    "amount_fiat": "500.00",
    "amount_usd": "95.00",
    "status": "PEN",
    "created_at": "2026-04-16T15:10:00Z",
    "updated_at": "2026-04-16T15:10:00Z",
    "origin": null,
    "destination": "[email protected]",
    "tax": "0.00",
    "tax_currency": null,
    "extra_data": {}
  }
}
Business rule errors:
error_codeCondition
TXN_0500Account country is not BR
GTW_0404PIX gateway is disabled
TXN_0450pix_key not provided in gateway_data
PIX_0400PIX key is registered in the account but is disabled
PIX_0401PIX recipient bank account is inactive
PIX_0402PIX key ownership data does not match the expected recipient
PIX_0500External PIX provider returned an error

​
Flow 4: Transaction queries

​
List transactions with filters

Required permission: general_data_read 
GET /transactions/?gateway=crypto&currency=USDT&ordering=-date_created
Response (cursor pagination): 
{
  "error_code": null,
  "message": null,
  "data": {
    "results": [
      {
        "id": 7823941,
        "operation_type": "SEND",
        "gateway": "crypto",
        "from_currency": "USDT",
        "amount_from": "50.00",
        "status": "PEN",
        "created_at": "2026-04-16T14:32:00Z"
      }
    ],
    "nc": "cD0yMDI2LTA0LTE2KzE0JTNBMzIlM0EwMC4wMDAwMDAlMkIwMCUzQTAw",
    "pc": null
  }
}
The nc and pc tokens are opaque (URL-safe base64). The client passes them back verbatim via ?cursor=<token>. Do not attempt to parse or modify them.
Next page: 
GET /transactions/?cursor=cD0yMDI2LTA0LTE2KzE0JTNBMzIlM0EwMC4wMDAwMDAlMkIwMCUzQTAw
Available query parameters:
ParameterTypeDescription
gatewaystringFilter by gateway: crypto, bank-transfer-cvu, pix, balance
currencystringFilter by currency (matches both currency and crypto_currency)
txn_typeenumRaw type: BUY, SELL, SWAP, SEN, REC, WIT, DEP
payment_method_idintFilter by payment method ID
orderingenumdate_created or -date_created (default)
cursorstringOpaque token returned in nc/pc from the previous response

​
Fetch a transaction detail

GET /transactions/7823941/
Response: 
{
  "error_code": null,
  "message": null,
  "data": {
    "id": 7823941,
    "operation_type": "SEND",
    "txn_type": "SEN",
    "gateway": "crypto",
    "...": "..."
  }
}
When the transaction does not exist: 
{ "error_code": "ERR_0004", "message": "Not found", "data": null }

​
Possible transaction statuses

StatusDescription
PENPending
PROProcessing
COMCompleted
ERRError
WTGWaiting
CANCancelled
REFRefunded
REJRejected

​
Flow 5: Balance check before operating

Before executing any operation, it is recommended to verify the available balance. Required permissions: general_data_read, balance_read 
GET /balance/wallet
Response: 
{
  "error_code": null,
  "message": null,
  "data": [
    {
      "currency": "USDT",
      "currency_internal_id": 14,
      "amount": "250.00",
      "locked_amount": "0.00"
    },
    {
      "currency": "BTC",
      "currency_internal_id": 5,
      "amount": "0.00451230",
      "locked_amount": "0.00000000"
    },
    {
      "currency": "ARS",
      "currency_internal_id": 1,
      "amount": "125000.00",
      "locked_amount": "0.00"
    }
  ]
}
  • amount: available balance (the amount that can be used in operations)
  • locked_amount: funds reserved by open orders

​
Generic error codes

When the upstream service does not return a specific {code, detail} atom (e.g. authentication errors or DRF-level errors), the gateway falls back to generic codes mapped by HTTP status:
error_codeHTTPMeaning
ERR_0001500Internal error
ERR_0003400Bad request
ERR_0004404Not found
ERR_0005409Conflict
ERR_0006503Service unavailable
ERR_0008401Unauthorized
ERR_0009403Forbidden
ERR_0010405Method not allowed
ERR_0011—Generic / unmapped
ERR_0012429Too many requests
Example response when no valid credentials are provided: 
{
  "error_code": "ERR_0008",
  "message": "Authentication credentials were not provided.",
  "data": null
}
Domain-specific codes (TXN_0420, CURR_0002, CVU_1000, etc.) are passed through unchanged from the upstream microservice. ERR_XXXX codes only appear when no specific code is found.
For more information on error codes, refer to the Errors page.

​
Quick endpoint reference

EndpointMethodPermissionDescription
/health/GET—Health check
/account/GETgeneral_data_readAccount profile
/balance/GETgeneral_data_read, balance_readAll balances
/balance/walletGETgeneral_data_read, balance_readWallet balances (excluding DEX)
/balance/viralGETgeneral_data_read, balance_readDEX balances (memecoins)
/currencies/GETgeneral_data_readAvailable currencies
/rates/GETgeneral_data_readExchange rates
/addresses/GETgeneral_data_readAccount crypto addresses
/network/currency-networks/{currency}/GETgeneral_data_readAvailable networks for a currency
/transactions/gateways/GETgeneral_data_readGateways and their enabled actions
/transactions/limits/GETgeneral_data_readOperational limits by gateway
/transactions/GETgeneral_data_readTransaction list (cursor-paginated)
/transactions/{pk}/GETgeneral_data_readTransaction detail
/transactions/crypto/send/POSTwithdrawal_writeSend crypto to an external address
/transactions/bank-transfer-cvu/withdrawal/POSTwithdrawal_writeWithdrawal to CVU/CBU (AR only)
/transactions/pix/withdrawal/POSTwithdrawal_writeWithdrawal via PIX (BR only)
/banking/cvu/GETgeneral_data_readUser’s own CVU (AR only)
/banking/pix/GETgeneral_data_readRegistered PIX accounts (BR only)