Utransfa API Documentation

Welcome to the Utransfa API documentation. Utransfa is a crypto payments system designed to adapt to your evolving needs. You can accept, convert, pay out, and store a variety of cryptocurrencies with ease.

Overview

Utransfa's flexible structure allows you to switch counterparties effortlessly, minimizing your risk of single-point failure. The API accepts JSON request bodies, returns JSON responses, and uses webhooks for real-time transaction notifications.

Key Features

• Accept cryptocurrency deposits with auto-generated addresses
• Process cryptocurrency withdrawals
• Real-time webhook notifications for deposits and withdrawals
• Support for USDT-TRC20, BTC, TRX, and ERC20 tokens
• Merchant management system
• Resend webhook functionality

Supported Cryptocurrencies

• tusdt - USDT-TRC20 (Tether on TRON network)
• btc - Bitcoin
• trx - TRON
• erc20 - Ethereum ERC20 tokens

Create Merchant

In order to begin running the required operations, you need a Merchant ID. The process of adding a merchant is followed by a webhook, where the webhook URL receives a POST request of the entire notification (withdrawal/deposit).

Request Parameters

Example Request

curl -X POST https://utransfa.com/utransfa/add_merchant \
  -H "Content-Type: application/json" \
  -d '{
    "email": "testing@utransfa.com",
    "merchant_name": "Utransfa",
    "web_hook": "https://yourdomain.com/endpoint"
  }'

<?php
// Set content type to JSON
header('Content-Type: application/json');

// Check if the request method is POST
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $input = json_decode(file_get_contents('php://input'), true);
    
    // Process merchant data
    $email = $input['email'];
    $merchant_name = $input['merchant_name'];
    $web_hook = $input['web_hook'];
}
?>

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/your-endpoint', methods=['POST'])
def your_function():
    if request.method == 'POST':
        input_data = request.get_json()
        
        # Process merchant data
        email = input_data['email']
        merchant_name = input_data['merchant_name']
        web_hook = input_data['web_hook']
        
        return jsonify(input_data)

if __name__ == '__main__':
    app.run()

Response Example

{
  "merchant_key": "8f44d8fa2ae82326fb29bb95be7389",
  "msg": "Merchant created successfully",
  "status": "created"
}

Quick Start Guide

Get started with Utransfa in 3 simple steps.

Deposit Funds (Generate Address)

Generate a cryptocurrency deposit address for receiving payments. Each address is unique and tied to your merchant account.

Request Parameters

Example Request

curl -X POST https://utransfa.com/utransfa/create_address \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "8f44d8fa2ae82326fb29bb95be7389",
    "symbol": "tusdt"
  }'

const response = await fetch('https://utransfa.com/utransfa/create_address', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    merchant_key: '8f44d8fa2ae82326fb29bb95be7389',
    symbol: 'tusdt'
  })
});

const data = await response.json();
console.log(data.address); // Display address to user

import requests
import json

url = 'https://utransfa.com/utransfa/create_address'
payload = {
    'merchant_key': '8f44d8fa2ae82326fb29bb95be7389',
    'symbol': 'tusdt'
}

response = requests.post(url, json=payload)
data = response.json()

print(f"Deposit Address: {data['address']}")
print(f"Address ID: {data['address_id']}")

<?php
$url = 'https://utransfa.com/utransfa/create_address';
$data = array(
    'merchant_key' => '8f44d8fa2ae82326fb29bb95be7389',
    'symbol' => 'tusdt'
);

$options = array(
    'http' => array(
        'header'  => "Content-type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    )
);

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result);

echo "Address: " . $response->address;
?>

Response Example

{
  "address": "TEebexXTJJvCcxbPg1qLUvbdU94VnAu94Y",
  "symbol": "tusdt",
  "address_id": 1334183,
  "symbol_img_url": "https://utransfa.com/utransfa/web/images/TEebexXTJJvCcxbPg1qLUvbdU94VnAu94Y.png"
}

Deposit Webhook Notification

When a deposit is confirmed, Utransfa will send a POST request to your webhook URL with the following data:

{
  "txid": "98718d5d5b171218a2996c34bcb7fafacaca94f9907e00c73ff35a889eb07897",
  "address_to": "TLPjdwGx4cFjJqYnu5sKFzzzR3q3gcBVT1",
  "symbol": "tusdt",
  "amount": 23,
  "confirmation": 3,
  "real_Fee": 1.3,
  "msg": "payments confirmed",
  "status": "succesful",
  "type": "deposit",
  "deposit_id": "23456787"
}

Funds Withdrawal

Process cryptocurrency withdrawals to external addresses. The system will notify you via webhook when the withdrawal is complete.

Request Parameters

Example Request

curl -X POST https://utransfa.com/utransfa/transfa_funds \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "8f44d8fa2ae82326fb29bb95be7389",
    "address": "TLPjdwGx4cFjJqYnu5sKFzzzR3q3gcBVT1",
    "symbol": "tusdt",
    "amount": 23
  }'

Response Example

{
  "msg": "awaiting payments",
  "status": "pending",
  "withdrawal_id": 482323,
  "symbol": "tusdt"
}

Withdrawal Webhook Notification

After a successful withdrawal, a POST request is sent to your webhook with the following data:

{
  "txid": "98718d5d5b171218a2996c34bcb7fafacaca94f9907e00c73ff35a889eb07897",
  "address_to": "TLPjdwGx4cFjJqYnu5sKFzzzR3q3gcBVT1",
  "symbol": "tusdt",
  "amount": 23,
  "confirmation": 3,
  "real_Fee": 1.3,
  "msg": "payments confirmed",
  "status": "succesful",
  "type": "withdrawal",
  "withdrawal_id": "23456787"
}

Get Address Info

Retrieve information about a specific crypto address, including balance and transaction history.

Request Parameters

Example Request

curl -X POST https://utransfa.com/utransfa/get_address_info \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "8f44d8fa2ae82326fb29bb95be7389",
    "address": "TLPjdwGx4cFjJqYnu5sKFzzzR3q3gcBVT1",
    "symbol": "tusdt"
  }'

Webhooks

Webhooks allow you to receive real-time notifications about deposits and withdrawals. When a transaction is confirmed, Utransfa sends an HTTP POST request to your webhook URL.

Setting Up Webhooks

1. Specify your webhook URL when creating your merchant account
2. Ensure your endpoint can receive POST requests
3. Parse the JSON payload to get transaction details
4. Use the type field to differentiate between deposits and withdrawals

Webhook Events

Webhook Payload Structure

{
  "txid": "98718d5d5b171218a2996c34bcb7fafacaca94f9907e00c73ff35a889eb07897",
  "address_to": "TLPjdwGx4cFjJqYnu5sKFzzzR3q3gcBVT1",
  "symbol": "tusdt",
  "amount": 23,
  "confirmation": 3,
  "real_Fee": 1.3,
  "msg": "payments confirmed",
  "status": "succesful",
  "type": "deposit", // or "withdrawal"
  "deposit_id": "23456787" // or "withdrawal_id" for withdrawals
}

Handling Webhooks - PHP Example

<?php
// Set content type to JSON
header('Content-Type: application/json');

if ($_SERVER['REQUEST_METHOD'] == "POST") {
    // Get the input data
    $input = json_decode(file_get_contents('php://input'), true);
    
    $txid = $input['txid'];
    $type = $input['type'];
    $address_to = $input['address_to'];
    $amount = $input['amount'];
    $symbol = $input['symbol'];
    $confirmations = $input['confirmation'];
    $status = $input['status'];
    
    if ($type == "deposit") {
        $deposit_id = $input['deposit_id'];
        
        // Process deposit logic
        // Update your database, credit user account, etc.
        
    } else if ($type == "withdrawal") {
        $withdrawal_id = $input['withdraw_id'];
        
        // Process withdrawal logic
        // Update transaction status, notify user, etc.
    }
    
    // Return success response
    echo json_encode(['status' => 'received']);
}
?>

Handling Webhooks - Python Example

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/webhook")
async def webhook(request: Request):
    # Get the input data
    input_data = await request.json()
    
    txid = input_data.get('txid')
    type_ = input_data.get('type')
    address_to = input_data.get('address_to')
    amount = input_data.get('amount')
    symbol = input_data.get('symbol')
    confirmations = input_data.get('confirmation')
    status = input_data.get('status')
    
    if type_ == "deposit":
        deposit_id = input_data.get('deposit_id')
        # Process deposit logic here
        
    elif type_ == "withdrawal":
        withdrawal_id = input_data.get('withdraw_id')
        # Process withdrawal logic here
    
    return JSONResponse(content={"status": "received"})

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Resend Webhook

Manually resend a webhook notification for a specific transaction. Useful when your endpoint was temporarily unavailable or you need to reprocess a transaction.

Request Parameters

Example Request

curl -X POST https://utransfa.com/utransfa/sendhooks \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "8bdf58799fcb7b0098b3bdd98aa5ea",
    "type": "deposit",
    "hook_id": "1375689"
  }'

Response Example

{
  "status": "successful",
  "url": "url from database",
  "type": "deposit",
  "route": "api"
}

Best Practices

Follow these best practices to ensure smooth integration with Utransfa API.

1. Store Transaction IDs

Always store the address_id, deposit_id, and withdrawal_id in your database. These are crucial for tracking transactions and matching webhook notifications.

// Example: Store IDs when creating address
$response = createAddress($merchant_key, 'tusdt');
saveToDatabase([
    'address' => $response['address'],
    'address_id' => $response['address_id'],
    'symbol' => $response['symbol'],
    'created_at' => time()
]);

2. Validate Webhook Data

Always validate incoming webhook data before processing transactions:

• Check the type field (deposit or withdrawal)
• Verify the status is "succesful"
• Validate the amount matches expected value
• Confirm the transaction hasn't been processed before (using txid)

3. Handle Webhook Reliability

Implement these strategies to handle webhook delivery:

• Return a 200 OK response quickly to acknowledge receipt
• Process webhooks asynchronously using a queue
• Implement idempotency to prevent duplicate processing
• Use the "Resend Webhook" endpoint if a webhook is missed
• Log all webhook data for debugging and auditing

4. Symbol Notation

Use correct cryptocurrency symbols:

5. Amount Handling for Bitcoin

6. Error Response Handling

Implement proper error handling in your application:

<?php
try {
    $response = callUtransfaAPI($endpoint, $data);
    
    if (isset($response['status']) && $response['status'] === 'created') {
        // Success - process response
        processSuccessfulResponse($response);
    } else {
        // Handle error
        logError('API Error: ' . json_encode($response));
        notifyAdmin($response);
    }
} catch (Exception $e) {
    // Handle connection errors
    logError('Connection failed: ' . $e->getMessage());
    retryLater($endpoint, $data);
}
?>

7. Security Recommendations

• Store your merchant_key securely (environment variables, not in code)
• Use HTTPS for your webhook endpoint
• Validate all incoming data before database operations
• Implement rate limiting on your webhook endpoint
• Log all API interactions for audit trails

Testing Your Integration

Before going live, thoroughly test your Utransfa integration to ensure everything works correctly.

1. Test Merchant Creation

Start by creating a test merchant account:

// Create test merchant
POST https://utransfa.com/utransfa/add_merchant
{
  "email": "test@yourcompany.com",
  "merchant_name": "Test Merchant",
  "web_hook": "https://yourdomain.com/test-webhook"
}

// Save the returned merchant_key for testing

2. Test Address Generation

Generate test addresses for different cryptocurrencies:

// Test USDT-TRC20 address generation
{
  "merchant_key": "your_test_merchant_key",
  "symbol": "tusdt"
}

// Test Bitcoin address generation
{
  "merchant_key": "your_test_merchant_key",
  "symbol": "btc"
}

3. Test Webhook Endpoint

Use tools like ngrok or RequestBin to test your webhook:

ngrok http 8000

4. Test Small Transactions

5. Testing Checklist

6. Common Testing Issues

Issue: Webhook not received

• Check your webhook URL is publicly accessible
• Verify HTTPS is enabled (if required)
• Check firewall settings
• Test with ngrok or RequestBin first
• Use the "Resend Webhook" endpoint to retry

Issue: Invalid symbol error

• Ensure you're using correct notation: tusdt, btc, trx, erc20
• Check for typos (case-sensitive)

Issue: Withdrawal not processing

• Verify the destination address is valid
• Check you have sufficient balance
• For BTC, ensure amount is in decimal format (not satoshis)
• Check withdrawal_id is stored correctly

7. Testing Tools

Need Help?

Can't find what you're looking for? Our support team is here to help.