# Pagos sin interfaz: checkout por depósito en una sola llamada

> Un nuevo endpoint de API para programadores que ya saben con qué token y red pagará el cliente, crea el pago y obtén una dirección de depósito lista para usar en una sola ida y vuelta, sin necesidad de UI alojada.

Source: https://mutopay.com/es/blog/headless-payment-api/
Language: es
Date: 2026-04-14

---

Si estás construyendo tu propio checkout, una app móvil, una plataforma asociada, una tienda personalizada, la página alojada `/pay/{id}` no siempre encaja. Ya tienes un flujo de wallet. Ya sabes en qué cadena y con qué token quiere pagar tu cliente. Lo que realmente quieres es una sola llamada de API que te devuelva una dirección de depósito y el monto exacto a enviar.

Para eso existe `POST /api/payments/headless`.

## La forma de la llamada

Una entrada. Una salida.

```bash
curl -X POST https://mutopay.com/api/payments/headless \
  -H "X-API-Key: ep_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "currency": "USD",
    "description": "Pedido #1042",
    "external_id": "order_1042",

    "src_token_symbol": "USDT",
    "src_token_address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "src_chain_id": "137",
    "src_decimals": 6,
    "src_address": "0xCustomerWallet..."
  }'
```

```json
{
  "id": "pay_abc123...",
  "status": "awaiting_payment",
  "route_type": "bridge",
  "protocol": "rubic",
  "deposit": {
    "address": "0xRubicDepositAddress...",
    "chain_id": "137",
    "chain_type": "evm",
    "token_symbol": "USDT",
    "token_address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "token_decimals": 6,
    "amount_raw": "25100000",
    "amount_human": "25.10",
    "payment_uri": "ethereum:0x...@137?value=25100000"
  },
  "bridge": {
    "name": "Across",
    "estimated_time_ms": 60000,
    "src_usd": "25.10",
    "bridge_fee_usd": "0.10"
  },
  "order_id": "rubic_exchange_id...",
  "expires_at": "2026-04-14T15:30:00Z"
}
```

Tu app ya tiene todo lo que necesita: dile al cliente que envíe **exactamente** `amount_raw` del token de origen a `address`. Renderiza un QR desde `payment_uri` si quieres. Haz polling a `GET /api/payments/{id}/status` hasta el estado final.

## Dos tipos de ruta, una sola forma

- **Directa**: mismo token, misma cadena (el cliente paga USDT en Polygon y tú liquidas USDT en Polygon). La dirección de depósito es tu wallet. Sin comisiones de puente ni esperas.
- **Depósito de swap / bridge**: una ruta entre tokens o entre cadenas donde el cliente envía una sola transacción a una dirección de entrada y el token de liquidación llega a tu wallet. Sin firmar ninguna orden.

Las rutas que requieren que el cliente firme una orden tipada o envíe una transacción de swap on-chain no se soportan en este endpoint. Si esa es la única ruta disponible, recibirás un 422. Para esos casos, usa la página alojada `/pay/{id}` o el trío de bajo nivel `/quotes` + `/build-order` + `/submit-order`.

## Lo que aún te toca hacer

Dos cosas:

**1. Consigue el tx hash si puedes.** Para depósitos de swap/bridge no hace falta hacer nada, el monitor en segundo plano detecta el depósito y marca el pago como completado. Para rutas directas, el monitor sólo verifica cuando tiene un tx hash, así que llama a `POST /api/payments/{id}/confirm` con `{ "tx_hash": "0x..." }` cuando el cliente transmita la transacción. Si tu UI de wallet te da el hash (la mayoría lo hace), es una sola línea.

**2. Haz polling del estado.** `GET /api/payments/{id}/status` devuelve el estado actual más un tx hash cuando el pago llegue. El webhook que configuraste en tu canal dispara los mismos eventos (`payment.completed`, `payment.failed`, etc.), usa lo que encaje con tu arquitectura.

## Cuándo usar cada uno

| Lo que estás construyendo | Usa |
|---|---|
| Una integración estilo WooCommerce / Shopify con redirección | `POST /api/payments` → `/pay/{id}` |
| Un checkout personalizado donde controlas el flujo de wallet | `POST /api/payments/headless` |
| Necesitas ofrecer varias rutas de swap y que el usuario elija | `POST /api/payments` + `/quotes` + `/build-order` |

El endpoint headless es más estrecho a propósito. Elige automáticamente la mejor ruta por depósito, se compromete con ella y te devuelve una dirección de depósito. Si necesitas más control, velocidad vs precio, varias opciones de ruta, flujos de orden firmada, los endpoints granulares siguen ahí.

Referencia completa en [la documentación de la API](/api/docs). Preguntas bienvenidas.