Getting Started

Welcome to the TurboCash API. This API lets you accept stablecoin payments and manage payouts programmatically — across Arbitrum, Base and TRON, with no KYB required.

Base URL

https://api.turbocash.io

Quick Start

To get started, you'll need:

1. An API key for authentication (passed via the X-API-Key HTTP header)
2. A configured wallet chain for your chosen blockchain network
3. A symbol and chain from the available currencies list

Create your first payment

curl -X POST "https://api.turbocash.io/post_create_order" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d "order_id=ORDER_001" \
  -d "amount=100" \
  -d "symbol=USDC" \
  -d "chain=arbitrum" \
  -d "base_currency=EUR"

Response:

{
  "payment_url": "https://turbocash.io/d4e5f6g7-h8i9-j0k1-l2m3-n4o5p6q7r8s9?token=4f2b3c..."
}

Create Payment Order

Creates a new stablecoin payment order and returns a hosted payment URL for the customer.

Parameters

Example Request

curl -X POST "https://api.turbocash.io/post_create_order" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-API-Key: sk_live_abc123xyz789" \
  -d "order_id=ORDER_12345" \
  -d "amount=100.50" \
  -d "symbol=USDC" \
  -d "chain=arbitrum" \
  -d "base_currency=EUR"

Response

{
  "payment_url": "https://turbocash.io/a1b2c3d4-e5f6-7890-abcd-ef1234567890?token=9a8b7c..."
}

Error Responses

• 400 Invalid amount, asset input, or cryptocurrency not available
• 401 Invalid authentication credentials
• 404 Cryptocurrency not found
• 500 No wallet chain configured or internal error

Get Payment Info

Retrieves the current state of a payment by its ID.

Path Parameters

Headers

Example Request

curl -X GET "https://api.turbocash.io/get_payment_infos/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: sk_live_abc123xyz789"

Response

{
  "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "order_id": "ORDER_12345",
  "status": "confirmed",
  "amount_due": "100.50",
  "amount_received": "100.50",
  "symbol": "USDC",
  "chain": "arbitrum",
  "base_currency": "EUR",
  "payment_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "created_at": "2026-05-13T10:30:00Z",
  "confirmed_at": "2026-05-13T10:34:21Z"
}

Payment Status Values

• pending Awaiting any incoming transaction
• partially_received Some funds received, below requested amount
• received Full amount received, awaiting confirmations
• confirmed Full amount confirmed on-chain
• partially_confirmed Some confirmed, some still awaiting confirmations

Get Payout Info

Retrieves the status of a payout (withdrawal or refund) by ID.

Path Parameters

Example Request

curl -X GET "https://api.turbocash.io/get_payout_infos/b1c2d3e4-f5g6-7890-hijk-lm1234567890" \
  -H "X-API-Key: sk_live_abc123xyz789"

Response

{
  "payout_id": "b1c2d3e4-f5g6-7890-hijk-lm1234567890",
  "order_id": "ORDER_99001",
  "status": "confirmed",
  "amount": "50.00",
  "symbol": "USDC",
  "chain": "arbitrum",
  "destination_address": "0x613526e1f5e12189569a2fbeff8b31dfaef791b1",
  "tx_hash": "0xabcdef…",
  "created_at": "2026-05-13T11:00:00Z",
  "confirmed_at": "2026-05-13T11:02:08Z"
}

Payout Status Values

• pending Created, not yet broadcast
• queued Queued for broadcast
• sent Broadcast to the network
• confirmed Confirmed on-chain
• failed Broadcast or confirmation failed

List Available Currencies

Returns the list of assets and chains enabled for your merchant account.

Headers

Example Request

curl -X POST "https://api.turbocash.io/post_currencies" \
  -H "X-API-Key: sk_live_abc123xyz789"

Response

{
  "currencies": [
    { "symbol": "USDC", "chain": "arbitrum", "min_amount": "0.50" },
    { "symbol": "USDT", "chain": "arbitrum", "min_amount": "0.50" },
    { "symbol": "USDC", "chain": "base",     "min_amount": "0.50" },
    { "symbol": "USDT", "chain": "tron",     "min_amount": "1.00" }
  ]
}

Create Withdrawal

Creates a withdrawal request from your merchant balance to an external wallet address.

Parameters

Example Request

curl -X POST "https://api.turbocash.io/post_create_withdrawal" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-API-Key: sk_live_abc123xyz789" \
  -d "order_id=ORDER_99001" \
  -d "amount=50" \
  -d "address_to=0x613526e1f5e12189569a2fbeff8b31dfaef791b1" \
  -d "chain=arbitrum" \
  -d "symbol=USDC" \
  -d "base_currency=EUR"

Response

{
  "payout_id": "b1c2d3e4-f5g6-7890-hijk-lm1234567890",
  "status": "pending",
  "payout_type": "withdrawal",
  "amount": 50.0,
  "symbol": "USDC",
  "chain": "arbitrum",
  "source_wallet_address": "0x…",
  "destination_address": "0x613526e1f5e12189569a2fbeff8b31dfaef791b1",
  "created_at": "2026-05-13T11:00:00Z"
}

Authentication

All authenticated endpoints require your merchant API key, passed via the X-API-Key HTTP header. The only exception is the hosted payment page, which uses the opaque token query parameter embedded in payment_url.

• X-API-Key — your secret API key (format: sk_live_xxx or sk_test_xxx)
• token — opaque public payment access token, automatically included in payment_url

Webhooks

TurboCash delivers signed webhook callbacks for payment and payout lifecycle events. Use them to update orders and trigger downstream business logic.

Setup

Configure a webhook endpoint URL and a shared secret in the merchant dashboard. The shared secret is used to compute an HMAC signature included on every webhook request.

Signature Verification

Each request includes an X-Webhook-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your webhook_secret.

import hmac, hashlib

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Delivery Policy

• Max attempts: 9
• Retry window: ~4 hours total
• Permanent failure HTTP codes: 400, 401, 403, 404, 410, 422
• Retry delays: 30s, 60s, 120s, 240s, 480s, 960s, 1920s, 3840s, 6750s

Error Handling

The API returns standard HTTP status codes. Error bodies are JSON objects with a human-readable message.

Status Codes

• 200 Success
• 400 Bad request — invalid parameters or business rule violation
• 401 Unauthorized — missing or invalid X-API-Key
• 403 Forbidden — key valid but action not allowed
• 404 Not found — resource doesn't exist
• 422 Unprocessable entity — semantic validation failed
• 429 Rate limited — slow down
• 500 Internal error — try again later or contact support

Error Response Format

{
  "error": "Invalid asset input",
  "detail": "symbol 'BTC' is not enabled on chain 'arbitrum'"
}