Acepte pagos con tarjeta y reciba USDC — con o sin cuenta

Cómo funciona un pago

El flujo es el mismo en todos los modos. Solo cambian el destino del dinero y las herramientas alrededor.

URL base para cada llamada a la API: https://api.utopay.app. Las solicitudes y respuestas son JSON (content-type: application/json). Los importes son números en la moneda del pedido; las horas, milisegundos Unix.

Inicio rápido

Un pago real en una sola solicitud — sin registro. El comprador va directo a PayPal; si PayPal no puede aceptar este pago, se abre nuestra página con los demás métodos.

curl -X POST https://api.utopay.app/v1/pay \
  -H "content-type: application/json" \
  -d '{
    "amount": 100,
    "currency": "USD",
    "payout_wallet": "0xYourPolygonWalletAddress000000000000000000",
    "provider": "paypal",
    "success_url": "https://yoursite.com/thanks"
  }'
# → { "id": "ord_…", "checkout_url": "https://api.utopay.app/pay/ord_…/go?provider=paypal", … }

Redirija al comprador a checkout_url. Tras el pago llegan unos 95.5 USDC a su wallet. Con cuenta llamaría en su lugar a POST /v1/payments con una clave API — mismos campos, más historial, webhooks y saldo.

Comparar modos

Sin cuenta

POST /v1/pay

Sin cabecera Authorization. El dinero siempre va directo a payout_wallet — una dirección EVM que pueda recibir USDC en Polygon. Mismo cuerpo que POST /v1/payments, más:

• Siempre direct: "settlement": "custody" devuelve 400 — sin cuenta no hay saldo que acreditar.
• Comisión fija del 4.5%, sin programa de referidos, sin webhooks (callback_url se guarda pero no se llama), sin modo de prueba, diseño de pago estándar.
• Seguimiento: consulte el endpoint público GET /api/checkout/:id/status (sin clave) o vigile su wallet.

Cuenta y claves API

Una cuenta puede tener hasta 20 proyectos (uno por sitio). Cada uno tiene sus propias claves, webhooks, wallet, marca, modo de fondos y estadísticas; el saldo es común a toda la cuenta.

Authorization: Bearer utopay_sk_live_xxxxxxxxxxxxxxxxxxxx

La clave se muestra una sola vez; solo guardamos su hash. Nunca ponga una clave secreta en código de navegador o móvil.

Crear un pago

POST /v1/payments Bearer sk

curl -X POST https://api.utopay.app/v1/payments \
  -H "Authorization: Bearer utopay_sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "amount": 250,
    "currency": "EUR",
    "email": "[email protected]",
    "description": "Invoice #118",
    "provider": "revolut",
    "success_url": "https://yoursite.com/thanks"
  }'

{
  "id": "ord_Kd83mQp0aVxY",
  "status": "pending",
  "amount": 250, "currency": "EUR",
  "checkout_url": "https://api.utopay.app/pay/ord_Kd83mQp0aVxY/go?provider=revolut",
  "payment_page_url": "https://api.utopay.app/pay/ord_Kd83mQp0aVxY",
  "provider": "revolut",
  "routing": { "mode": "direct_to_provider", "requested_provider": "revolut", "reason": null },
  "settlement": "direct",
  "payout_coin": "USDC", "payout_network": "polygon",
  …  full list in Order object
}

Redirija siempre al comprador a checkout_url. Guarde payment_page_url si quiere un enlace "elegir otro método" — siempre abre nuestra página.

Enviar al comprador directo a un método de pago

Funciona en todos los modos — con clave API, sin cuenta, en enlaces de pago del panel y en el formulario sin código de /payment-links. Indique provider y el comprador irá directamente a ese proveedor (p. ej. PayPal) sin ver nuestro formulario de pago.

routing en la respuesta indica qué pasó: mode es direct_to_provider o payment_page; reason es null, provider_offline, provider_below_minimum, provider_currency, provider_disabled o project_routing (elegido entre los proveedores preferidos de su proyecto).

GET /v1/providers?amount=&currency= público

Métodos disponibles ahora para este importe y moneda, con id, name, region, status, minimum_amount y minimum_currency. La lista cambia — consúltela en lugar de fijarla en el código.

* Los mínimos y la disponibilidad dependen de la red de pagos y cambian; el importe se convierte a la moneda del mínimo antes de comparar. Algunos proveedores pueden pedir al comprador una verificación de identidad rápida y única.

Monedas y qué recibe

currency es la moneda en que paga el comprador. Sea cual sea, el proveedor convierte el dinero y se mueve como USDC en Polygon.

GET /v1/currencies público

Cualquier otro código devuelve 400. Un proveedor puede mostrar al comprador el precio convertido a su propia moneda (p. ej. Revolut en EUR) — el comprador paga igualmente el equivalente de su importe. Algunos métodos solo aceptan ciertas monedas; para ellos, /v1/providers?currency=… los omite.

Qué llega y adónde

El USDC exacto que llegó figura en received_amount del pedido tras el pago; puede diferir un poco de la estimación porque el tipo de cambio lo fija el proveedor. Los saldos guardados se pueden cambiar entre monedas y retirar en USDC, USDT, BTC, ETH y más — vea Guardado en UTOPAY.

Estado del pago

GET /v1/payments/:id Bearer sk

El pedido con la misma estructura. Mientras no esté en paid, también consultamos el estado real en el proveedor, así que el sondeo es fiable aunque un callback se retrase — el abono al saldo y su webhook ocurren exactamente una vez en cualquier caso. Solo es visible el proyecto de la propia clave (si no, 404).

GET /v1/payments?limit=&offset=&status= Bearer sk

Pedidos del proyecto, los más recientes primero. limit 1–500 (por defecto 50), status = pending | paid | failed.

GET /api/checkout/:id/status público

Sin clave: { "id", "status", "amount", "currency", "updated_at" }. Úselo para pedidos creados sin cuenta. No tome una visita a success_url como prueba de pago — compruebe el estado.

Pasarela cripto

El comprador paga directamente en cripto — USDT, USDC, ETH, BTC y más — a una dirección única del pedido. Todo lo que llega se reenvía on-chain a su wallet al instante — o, con settlement: "custody", se acredita a su saldo en UTOPAY (no hacen falta wallets). Comisión del 1.5%, descontada del importe recibido; la comisión de la blockchain va aparte.

GET /v1/crypto/coins público

Cada moneda/red con ticker (lo que pasa como coin, p. ej. polygon/usdc, bep20/usdt, erc20/usdt, base/usdc, eth, btc, trc20/usdt), network, family (tipo de dirección), minimum y available. Funcionan las redes EVM, Tron, Bitcoin, Solana, TON y otras; available: false significa que la red no está disponible temporalmente.

POST /v1/crypto/payments Bearer sk · POST /v1/crypto/pay sin cuenta

curl -X POST https://api.utopay.app/v1/crypto/pay \
  -H "content-type: application/json" \
  -d '{ "coin": "bep20/usdt", "amount": 100, "currency": "USD",
        "payout_address": "0xYourWallet0000000000000000000000000000000" }'
# → { "id": "ord_…", "kind": "crypto", "checkout_url": "https://api.utopay.app/pay/ord_…",
#     "crypto": { "coin": "bep20/usdt", "network": "BNB Smart Chain (BEP-20)", "symbol": "USDT",
#                 "address": "0x…", "amount_coin": 100.02, "minimum": 1.66, "detected": false, "underpaid": false } }

• Redirija al comprador a checkout_url (importe, red, dirección, QR, estado en vivo) — o muestre crypto.address y crypto.amount_coin en su propia página.
• Estados: pending (con crypto.detected: true en cuanto se ve la transferencia, antes de las confirmaciones) → paid. Si llega menos de lo solicitado (falta más del 1%), el estado es underpaid y el evento payment.underpaid — el dinero ya está en su wallet, decida usted.
• Los webhooks, GET /v1/payments/:id y las claves de prueba funcionan igual que con pagos con tarjeta. Las transferencias por debajo de minimum o en otra moneda/red no se procesan — la página de pago avisa al comprador.

Ejemplos de integración

Cree el pedido en su servidor (nunca con una clave secreta en el navegador), redirija al comprador a checkout_url y marque el pedido como pagado desde el webhook. Guía paso a paso: aceptar cripto en un sitio web; redes y tickers de Tether: aceptar USDT.

const res = await fetch('https://api.utopay.app/v1/crypto/payments', {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.UTOPAY_SK}`, 'content-type': 'application/json' },
  body: JSON.stringify({ coin: 'bep20/usdt', amount: 49.9, currency: 'EUR', description: 'Order #1042',
    success_url: 'https://shop.example/thanks', cancel_url: 'https://shop.example/cart' })
});
const order = await res.json();
if (!res.ok) throw new Error(order.error);
// save order.id with your order, then redirect the buyer
reply.redirect(order.checkout_url);

import os, requests

r = requests.post('https://api.utopay.app/v1/crypto/payments',
    headers={'Authorization': f'Bearer {os.environ["UTOPAY_SK"]}'},
    json={'coin': 'erc20/usdt', 'amount': 120, 'currency': 'USD', 'description': 'Invoice 77'},
    timeout=20)
order = r.json()
r.raise_for_status()
print(order['id'], order['checkout_url'], order['crypto']['address'], order['crypto']['amount_coin'])

$ch = curl_init('https://api.utopay.app/v1/crypto/payments');
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('UTOPAY_SK'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['coin' => 'polygon/usdt', 'amount' => 25, 'currency' => 'USD']),
]);
$order = json_decode(curl_exec($ch), true);
header('Location: ' . $order['checkout_url']);

Liquidación directa

El dinero nunca se queda con nosotros: cada pago se divide on-chain en el momento en que llega el USDC.

• Activar: panel → proyecto → Fondos y liquidaciones → Directo a la wallet, pegue una dirección USDC (Polygon). O por solicitud: "settlement": "direct".
• Recibe USDC en cada pago; además historial, estadísticas, webhooks y avisos en Telegram. Nada que retirar.
• Una wallet por proyecto — si necesita varias wallets, cree varios proyectos.

Guardado en UTOPAY

El USDC llega a la wallet de la plataforma UTOPAY. Con paid su parte se acredita al saldo interno — luego la guarda, cambia, convierte o retira.

• Activar: Fondos y liquidaciones → Guardado en UTOPAY (no hace falta wallet), o "settlement": "custody" por solicitud.
• Abono: amount × 95.5% en la moneda del pedido (USD, EUR, GBP, CAD, INR, SEK); cualquier otra moneda, en USD al tipo actual. Se acredita exactamente una vez.
• Un saldo por cuenta: todos los proyectos en este modo suman; el registro muestra el proyecto de origen.

Redes de retiro: USDC_POLYGON, USDT_POLYGON, USDT_TRC20, USDT_ERC20, ETH, BTC, BNB, TRX. El importe se reserva al instante (pending); el equipo de UTOPAY envía la transferencia, normalmente en un día hábil (done con txid). Las solicitudes rechazadas se reembolsan. Los retiros no se pueden iniciar con una clave API.

Enlaces de pago

Sin código: cree un enlace, envíelo por chat o email y cobre. Panel → proyecto → Enlaces de pago → + Enlace.

• Importe fijo o vacío — lo escribe el comprador. Moneda — cualquiera de la lista.
• Método (opcional): fije un proveedor. Con importe fijo, el enlace envía al comprador directo a él; con importe libre, el comprador solo ve el campo del importe y un botón "Pagar con PayPal". Si el método no está disponible, se muestra el selector de métodos normal.
• URL de retorno — adónde va el comprador tras el pago. Los enlaces de un solo uso pasan a used tras el primer pedido (al abrirlo de nuevo se ve ese pedido); los enlaces reutilizables funcionan hasta que se archivan.
• Los fondos siguen el modo de fondos del proyecto. Los pedidos de enlaces aparecen en el historial y disparan webhooks como los pedidos de la API.

El enlace público es https://api.utopay.app/i/lnk_…. Sin cuenta, use el formulario de /payment-links — crea un pedido /v1/pay con la misma elección de método.

Webhooks y avisos

Con cuenta. Cuando un pedido cambia de estado, UTOPAY lo envía por POST a cada endpoint del proyecto, firmado con HMAC-SHA256.

Registrar: panel → Webhooks → + Endpoint, o POST /api/merchants/:id/webhooks con { "url": "https://you.com/hooks/utopay" }. El secreto whsec_… se muestra en el panel.

POST https://you.com/hooks/utopay
content-type: application/json
x-utopay-event: payment.succeeded
x-utopay-signature: t=1759660123,v1=<hex hmac-sha256>
user-agent: UTOPAY-Webhooks/1.0

{
  "event": "payment.succeeded",
  "created_at": 1759660123456,
  "data": { /* the Order object */ }
}

import crypto from 'node:crypto';
// use the RAW body, not re-serialised JSON
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const a = Buffer.from(v1 || ''), b = Buffer.from(expected);
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

// raw body + x-utopay-signature header + your whsec_… secret
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_UTOPAY_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $raw, getenv('UTOPAY_WHSEC'));
if (!hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int)($sig['t'] ?? 0)) > 300) {
  http_response_code(400); exit;
}
$event = json_decode($raw, true);
if ($event['event'] === 'payment.succeeded') { /* mark $event['data']['id'] as paid */ }
http_response_code(200);

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    t, v1 = parts.get('t', ''), parts.get('v1', '')
    expected = hmac.new(secret.encode(), f'{t}.'.encode() + raw_body, hashlib.sha256).hexdigest()
    fresh = t.isdigit() and abs(time.time() - int(t)) < 300
    return fresh and hmac.compare_digest(expected, v1)

• Responda con cualquier 2xx en 10 s. Reintentos tras 30 s, 2 min, 15 min, 1 h, 6 h — 6 intentos. Las entregas se ven en el panel.
• Sea idempotente — elimine duplicados por data.id.
• Telegram: los pedidos pagados llegan a su chat con importe, descripción e id (Notificaciones).

Modo de prueba

1. Cree una clave secreta de prueba (utopay_sk_test_…) y llame a POST /v1/payments como siempre — todas las validaciones (moneda, proveedor) son iguales.
2. checkout_url apunta a una página sandbox (/sandbox/ord_test_…). Pulse Simulate payment o Simulate failure.
3. Los webhooks y Telegram se disparan como en producción con "is_test": true. No se mueve dinero ni se acredita saldo.

Equipo, marca, enrutamiento

Equipo: invite por email (Equipo). Roles admin, developer, finance, viewer; el creador es owner.

Marca: nombre, logo, color de fondo y de botón en Ajustes — se aplican a la página de pago, las páginas de enlaces y la pantalla de pago completado.

Enrutamiento del proyecto: en Enrutamiento ordene los proveedores preferidos por prioridad. Para pagos API sin provider se usa el primero que esté en línea y admita el importe y la moneda (routing.reason = "project_routing"); si ninguno encaja, el comprador elige en nuestra página. Un provider explícito siempre tiene prioridad.

Objeto del pedido

Lo devuelven create/get/list y va dentro de los webhooks.

Todos los endpoints públicos

Comisiones

• Usted recibe el 95.5% — igual con o sin cuenta, en modo directo y guardado, para cualquier moneda y método. Sin cuotas de alta ni mensuales.
• Los comercios grandes pueden obtener una tarifa individual — contáctenos. La división exacta de cada pedido está en fees.

Programa de referidos

• Nivel 1: el 25% de nuestra comisión de los comercios que usted invitó; nivel 2: el 10% de los comercios que ellos invitaron.
• Se paga on-chain en cada pago a la wallet de referidos indicada en Referidos. Sale de nuestra comisión — los referidos no pagan nada extra.

Errores

Cada error es { "error": "message" } con el estado HTTP correspondiente.