Partner Integration Guide

Complete API documentation for white-label payment gateway integration

Version 1.0 | December 2025

Table of Contents

1. Getting Started

5. Webhooks

2. Authentication

6. Pricing Tiers

3. API Reference

7. Error Handling

4. Customer Management

8. Support

1. Getting Started

Prerequisites

Signed partner agreement
Approved partner application
Business verification completed
Technical contact designated

Quick Start

Receive API credentials via secure channel
Configure webhook endpoints
Test in sandbox environment
Request production access

2. Authentication

All API requests require authentication via API key in the header:

// Request Headers
{
  "X-API-Key": "pk_live_your_api_key_here",
  "X-Partner-ID": "P-your-partner-id",
  "Content-Type": "application/json"
}
            

Security Notice: Never expose your API key in client-side code. All API calls should be made from your server.

Sandbox Environment

Base URL: https://sandbox.trustodi.com/api/v1

Use pk_test_ prefixed keys

Production Environment

Base URL: https://api.trustodi.com/api/v1

Use pk_live_ prefixed keys

3. Rate Limits

Tier	Requests/Minute	Requests/Day	Concurrent
Starter	60	10,000	5
Growth	300	100,000	20
Enterprise	1,000	Unlimited	100

4. Customer Management API

Create Customer

POST /customers

Create a new customer under your partner account

// Request Body
{
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1234567890",
  "country": "US",
  "external_id": "your-internal-user-id"
}

// Response
{
  "id": "cus_abc123xyz",
  "partner_id": "P-your-partner-id",
  "kyc_status": "pending",
  "kyc_link": "https://kyc.trustodi.com/verify/...",
  "created_at": "2025-12-28T10:00:00Z"
}
            

Get Customer

GET /customers/{customer_id}

Retrieve customer details and KYC status

List Customers

GET /customers?page=1&limit=50&status=verified

List all customers with pagination and filtering

5. Account Management API

Create Virtual Bank Account

POST /customers/{customer_id}/accounts/virtual

Create a virtual bank account for receiving fiat deposits

// Request Body
{
  "currency": "USD",
  "account_name": "Primary Account"
}

// Response
{
  "id": "acc_virt_123",
  "account_number": "1234567890",
  "routing_number": "021000021",
  "bank_name": "TRUSTODI Virtual Bank",
  "currency": "USD",
  "balance": "0.00"
}
            

Link External Bank Account

POST /customers/{customer_id}/accounts/external

Link customer's external bank account for withdrawals

// Request Body
{
  "account_holder_name": "John Doe",
  "account_number": "9876543210",
  "routing_number": "021000021",
  "bank_name": "Chase Bank",
  "country": "US",
  "currency": "USD"
}
            

Country-Specific Codes: Some countries require additional bank codes: India (IFSC), UK (Sort Code), Australia (BSB), Mexico (CLABE), Nigeria (NUBAN), etc.

6. Payment Processing API

Get Exchange Rates

GET /rates?from=USD&to=USDC&amount=1000

Get real-time exchange rates with fee breakdown

// Response
{
  "from_currency": "USD",
  "to_currency": "USDC",
  "amount": 1000,
  "rate": 0.995,
  "fee": 5.00,
  "fee_percentage": 0.5,
  "you_receive": 990.00,
  "expires_at": "2025-12-28T10:05:00Z"
}
            

Initiate On-Ramp (Fiat to Crypto)

POST /payments/onramp

Convert fiat deposit to cryptocurrency

// Request Body
{
  "customer_id": "cus_abc123xyz",
  "source_account_id": "acc_virt_123",
  "amount": 1000.00,
  "source_currency": "USD",
  "target_currency": "USDC",
  "target_wallet": "0x1234...abcd",
  "target_chain": "SOL"
}

// Response
{
  "id": "txn_onramp_456",
  "status": "processing",
  "amount": 1000.00,
  "fee": 5.00,
  "crypto_amount": "990.00",
  "estimated_completion": "2025-12-28T10:30:00Z"
}
            

Initiate Off-Ramp (Crypto to Bank)

POST /payments/offramp

Convert crypto and send to bank account

// Request Body
{
  "customer_id": "cus_abc123xyz",
  "destination_account_id": "acc_ext_789",
  "crypto_amount": "500.00",
  "crypto_currency": "USDC",
  "target_currency": "USD"
}

// Response
{
  "id": "txn_offramp_789",
  "status": "awaiting_crypto",
  "deposit_address": "0xdeposit...addr",
  "deposit_memo": null,
  "fiat_amount": 495.00,
  "fee": 5.00
}
            

Get Transaction Status

GET /payments/{transaction_id}

Get detailed transaction status and history

Transaction Statuses

Status	Description
`pending`	Transaction created, awaiting processing
`processing`	Transaction is being processed
`awaiting_crypto`	Waiting for crypto deposit (off-ramp)
`completed`	Successfully completed
`failed`	Transaction failed
`cancelled`	Transaction was cancelled

7. Webhooks

Configure webhook endpoints to receive real-time notifications for events:

Webhook Events

customer.kyc.completed
customer.kyc.failed
account.created
account.balance.updated

payment.completed
payment.failed
payment.status.changed
deposit.received

Webhook Payload Example

{
  "id": "evt_123abc",
  "type": "payment.completed",
  "created_at": "2025-12-28T10:30:00Z",
  "data": {
    "transaction_id": "txn_onramp_456",
    "customer_id": "cus_abc123xyz",
    "amount": 1000.00,
    "status": "completed"
  }
}
            

Webhook Security: All webhooks include an X-Signature header. Verify this signature using your webhook secret to ensure authenticity.

8. Partner Pricing Tiers

Starter

$0

per month

Up to 100 customers
$50K monthly volume
0.75% transaction fee
Email support
Sandbox access

Growth

$299

per month

Up to 1,000 customers
$500K monthly volume
0.5% transaction fee
Priority support
Dedicated account mgr

Enterprise

Custom

contact sales

Unlimited customers
Unlimited volume
Custom pricing
24/7 phone support
SLA guarantee

9. Volume-Based Pricing

Monthly Volume	Transaction Fee	Flat Fee
Up to $1M	1.2%	$3.00
$1M - $5M	1.0%	$2.50
$5M - $10M	0.8%	$2.00
$10M - $50M	0.6%	$1.50
$50M+	Contact for custom pricing

💬 Get Custom API Pricing

10. Error Handling

All API errors follow a consistent format:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Customer account has insufficient balance for this transaction",
    "details": {
      "available": 50.00,
      "required": 100.00
    }
  }
}
            

Common Error Codes

HTTP	Code	Description
400	INVALID_REQUEST	Request body validation failed
401	UNAUTHORIZED	Invalid or missing API key
403	FORBIDDEN	Action not permitted for your tier
404	NOT_FOUND	Resource does not exist
409	DUPLICATE	Resource already exists
422	KYC_REQUIRED	Customer KYC not verified
429	RATE_LIMITED	Too many requests
500	INTERNAL_ERROR	Server error (contact support)

11. Supported Countries & Currencies

Fiat Currencies

USD, EUR, GBP, CAD, AUD, CHF, JPY, INR, NGN, GHS, KES, ZAR, BRL, MXN, ARS, HKD, SGD

Cryptocurrencies

USDC (SOL, ETH, POL, ARB, BSC), USDT (TRX, ETH, SOL), BTC, ETH

Coming Soon

New capabilities in development:

💳 Card Onramp

Credit/debit card to crypto conversion API

🔄 Card to Bank

Card payment to bank transfer API

🏛️ Bank to Bank

Direct international bank transfer API

🛒 TRUSTODI Pay

Merchant payment processing API

12. Support & Resources

📧

Email Support

partners@trustodi.com

📱

Telegram

@TrustodiSupport

📚

Developer Docs

docs.trustodi.com

Enterprise Support SLA
                    Critical issues: 1-hour response
High priority: 4-hour response

                    Normal priority: 24-hour response
24/7 phone support available

                

Ready to Get Started?

Contact our partnerships team to discuss your integration needs

partners@trustodi.com | app.trustodi.com/partner