TOKIIA Pay API Documentation — Pasarela de Pagos Crypto

API v1 — Producción

Acepta pagos crypto
con TOKIIA Pay

Pasarela de pagos con stablecoins para tu negocio. Integra en minutos, cobra USDT de tus clientes, y retira a tu wallet cuando quieras.

Rápido

Integración en 10 minutos. Solo necesitas una API Key y una llamada HTTP.

Seguro

Seguridad Shamir 2-de-3 en hot wallets. Fondos protegidos a nivel criptográfico.

Multi-chain

Polygon, BSC, TRON y Ethereum. Tu cliente paga en la red que prefiera.

Autenticación

Todas las llamadas (excepto /rates) requieren tu API Key

Incluye tu API Key en el header X-API-Key de cada petición:

Header

X-API-Key: tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxx

La API Key se genera al registrarte como merchant en TOKIIA Pay. Guárdala de forma segura — no se puede recuperar.

Base URL

https://panel.tokiia.com/api/v1

Redes Soportadas

TOKIIA Pay opera en múltiples blockchains

Red	Identificador	Token	Costo por TX
Polygon PoS	`polygon`	USDT	~$0.01
TRON	`tron`	USDT TRC-20	~$0.50
BSC	`bsc`	USDT BEP-20	~$0.10
Ethereum	`ethereum`	USDT ERC-20	~$2-5

Guía Rápida

Empieza a cobrar en 6 pasos

Regístrate como Merchant

Contacta al equipo TOKIIA y obtén tu API Key (tk_live_xxx)

Crea un Invoice

Llama a POST /invoice/create con el monto a cobrar

Muestra la Dirección

Recibes una deposit_address. Tu cliente envía USDT ahí

Recibe Confirmación

TOKIIA detecta el pago on-chain y notifica via webhook

Verifica el Estado

Consulta GET /invoice/{'{'}id{'}'} para confirmar el status

Retira tus Fondos

Envía USDT a tu wallet con POST /payout/create

POST/invoice/createAPI Key

Crea un cobro. Genera una dirección de depósito donde tu cliente envía USDT. El invoice expira en 1 hora.

Parámetros del Body

amount requeridonumberMonto a cobrar en USD (mayor a 0)

currency opcionalstringMoneda de referencia. Default: "USDT"

network opcionalstringRed blockchain: polygon, tron, bsc, ethereum

description opcionalstringDescripción del cobro

external_id opcionalstringID de tu sistema para conciliar

callback_url opcionalstringURL para recibir webhook cuando el pago se confirme

metadata opcionalobjectDatos extra que recibirás en el webhook

Ejemplo — cURL

cURL

curl -X POST "https://panel.tokiia.com/api/v1/invoice/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tk_live_xxx" \
  -d '{
    "amount": 100.00,
    "network": "tron",
    "description": "Suscripción mensual",
    "callback_url": "https://tuapp.com/webhook"
  }'

Ejemplo — JavaScript

JavaScript

const response = await fetch('https://panel.tokiia.com/api/v1/invoice/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'tk_live_xxx'
  },
  body: JSON.stringify({
    amount: 100.00,
    network: 'tron',
    description: 'Suscripción mensual',
    callback_url: 'https://tuapp.com/webhook'
  })
});

const data = await response.json();
// data.deposit_address → mostrar al cliente para que pague

Respuesta exitosa — 201

JSON

{
  "invoice_id": "inv_abc123def456",
  "invoice_number": "INV-00001",
  "amount": 100.00,
  "coin": "USDT",
  "network": "tron",
  "deposit_address": "TNBS9rb6bGSG2YUe6CDjUccXSF7uMYALks",
  "qr_code_data": "tron:TNBS9rb6b...?amount=100&coin=USDT",
  "status": "pending",
  "expires_at": "2026-02-25T13:00:00Z",
  "created_at": "2026-02-25T12:00:00Z"
}

GET/invoice/{id}API Key

Consulta el estado de un invoice. Útil para verificar si un pago se completó.

Estados posibles

Status	Descripción
pending	Esperando pago del cliente
completed	Pago recibido y confirmado on-chain
expired	No se recibió pago antes de la expiración

Ejemplo

cURL

curl "https://panel.tokiia.com/api/v1/invoice/inv_abc123" \
  -H "X-API-Key: tk_live_xxx"

POST/payout/createAPI Key

Envía USDT desde tu balance a una dirección externa. Ideal para retiros, pagos a proveedores o liquidaciones.

Parámetros del Body

amount requeridonumberMonto a enviar (mayor a 0)

destination_address requeridostringWallet destino

network opcionalstringRed blockchain. Default: red configurada del merchant

description opcionalstringDescripción del pago

Ejemplo

cURL

curl -X POST "https://panel.tokiia.com/api/v1/payout/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tk_live_xxx" \
  -d '{
    "amount": 50.00,
    "destination_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD08",
    "network": "polygon"
  }'

Respuesta — 201

JSON

{
  "payout_id": "po_xyz789",
  "amount": 50.00,
  "fee": 0.75,
  "net_amount": 49.25,
  "network": "polygon",
  "destination_address": "0x742d...bD08",
  "status": "pending"
}

GET/balanceAPI Key

Consulta tu balance disponible y pendiente, desglosado por red.

Ejemplo

cURL

curl "https://panel.tokiia.com/api/v1/balance" \
  -H "X-API-Key: tk_live_xxx"

Respuesta — 200

JSON

{
  "balances": [
    { "network": "polygon", "available": 1500.00, "pending": 200.00 },
    { "network": "tron", "available": 800.00, "pending": 0 },
    { "network": "bsc", "available": 350.00, "pending": 50.00 }
  ]
}

GET/transactionsAPI Key

Lista todas tus transacciones (invoices + payouts) con paginación.

Query Parameters

page opcionalnumberNúmero de página. Default: 1

per_page opcionalnumberResultados por página. Default: 25, máximo: 100

Ejemplo

cURL

curl "https://panel.tokiia.com/api/v1/transactions?page=1&per_page=10" \
  -H "X-API-Key: tk_live_xxx"

POST/address/validateAPI Key

Valida si una dirección wallet es correcta para una red específica. Útil antes de crear un payout.

Ejemplo

cURL

curl -X POST "https://panel.tokiia.com/api/v1/address/validate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tk_live_xxx" \
  -d '{ "address": "0x742d...bD08", "network": "polygon" }'

Respuesta — 200

JSON

{
  "valid": true,
  "network": "polygon",
  "format": "evm"
}

GET/ratesPúblico

Obtiene tasas de conversión actuales. No requiere autenticación.

Ejemplo

cURL

curl "https://panel.tokiia.com/api/v1/rates"

Respuesta — 200

JSON

{
  "rates": {
    "USDT": { "usd": 1.00, "usd_24h_change": 0.03 },
    "TRX":  { "usd": 0.28, "usd_24h_change": 1.07 },
    "BNB":  { "usd": 600.13, "usd_24h_change": -0.01 }
  },
  "timestamp": "2026-02-25T12:00:00Z",
  "cache_ttl_seconds": 300
}

Webhooks

Recibe notificaciones automáticas cuando un pago cambia de estado

Si incluyes callback_url al crear un invoice, TOKIIA Pay enviará un POST a esa URL cuando el pago se complete:

Webhook Payload

// POST a tu callback_url
{
  "event": "invoice.completed",
  "data": {
    "id": "inv_abc123",
    "status": "completed",
    "amount": 100.00,
    "paid_amount": 100.00,
    "tx_hash": "0xabc123...def456",
    "external_id": "order-123",
    "paid_at": "2026-02-25T11:35:00Z"
  }
}

Eventos disponibles

Evento	Descripción
`invoice.completed`	Pago recibido y confirmado on-chain
`invoice.expired`	El invoice expiró sin recibir pago
`payout.sent`	Payout enviado a la blockchain
`payout.confirmed`	Payout confirmado on-chain

Buenas prácticas

Responde con HTTP 200 en menos de 5 segundos
Verifica el pago consultando GET /invoice/{id} antes de entregar el servicio
Implementa idempotencia — podrías recibir el mismo evento más de una vez

Rate Limits

Límites por categoría de endpoint

Categoría	Límite	Endpoints
Invoices	100 req/min	/invoice/create
Payouts	50 req/min	/payout/create
Lectura	300 req/min	/balance, /transactions, /invoice/{id}, /rates

Errores

Todas las respuestas de error siguen el mismo formato

Error Response

{
  "error": "Descripción del error"
}

HTTP	Error	Causa
400	amount must be greater than 0	Monto inválido o faltante
400	destination_address is required	Falta dirección en payout
401	API key inválida	Key no enviada o incorrecta
403	Merchant no activo	La cuenta está suspendida
404	Invoice not found	El invoice no existe o no te pertenece
429	Rate limit exceeded	Demasiadas peticiones por minuto
500	Internal server error	Error del servidor — contacta soporte

TOKIIA Pay API v1 — tokiia.com — Dashboard

Acepta pagos crypto con TOKIIA Pay

Rápido

Seguro

Multi-chain

Autenticación

Base URL

Redes Soportadas

Guía Rápida

Regístrate como Merchant

Crea un Invoice

Muestra la Dirección

Recibe Confirmación

Verifica el Estado

Retira tus Fondos

Parámetros del Body

Ejemplo — cURL

Ejemplo — JavaScript

Respuesta exitosa — 201

Estados posibles

Ejemplo

Parámetros del Body

Ejemplo

Respuesta — 201

Ejemplo

Respuesta — 200

Query Parameters

Ejemplo

Ejemplo

Respuesta — 200

Ejemplo

Respuesta — 200

Webhooks

Eventos disponibles

Buenas prácticas

Rate Limits

Errores

¿Listo para integrar TOKIIA Pay?

Acepta pagos crypto
con TOKIIA Pay