Desarrolladores

Referencia de la API

Una API REST pequeña para facturas, enlaces de pago, saldos y monedas aceptadas. Usa JSON sobre HTTPS, y cada solicitud se hace con tu clave secreta.

URL base

Producción: https://cryptomerchant.online/api/v1
Desarrollo local: http://localhost:3000/api/v1

Hay una descripción de esta API legible por máquinas en /openapi.json (OpenAPI 3.1). Puedes importarla en Postman o en un generador de clientes.

Autenticación

Envía tu clave secreta en el encabezado Authorization de cada solicitud, como token Bearer. Crea claves en el portal, en Desarrolladores.

HTTP

Authorization: Bearer cm_live_…

Las claves empiezan con cm_live_ en mainnet y con cm_test_ en testnet.
La clave completa se muestra solo una vez, cuando la creas. Solo guardamos un hash de ella, así que guárdala en un lugar seguro.
Usa las claves solo en tu servidor. Nunca las pongas en una página web, una app móvil o un repositorio de código público.
Si una clave pudo haberse filtrado, revócala en el portal y crea una nueva.

Errores

Cuando una solicitud falla, la respuesta tiene un estado HTTP de error y un cuerpo JSON con un code legible por máquinas y un message legible por personas:

JSON

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

Estado HTTP

400: La solicitud no es válida, por ejemplo, falta un campo o el monto es demasiado pequeño.
401: La clave de API falta, es incorrecta o fue revocada.
403: Tu cuenta no puede hacer esto: todavía no está activa o está suspendida.
404: El objeto no existe o pertenece a otro negocio.
409: La factura no permite esto en su estado actual, por ejemplo, cancelar una que ya tiene un pago.
500: Algo salió mal de nuestro lado. Vuelve a intentarlo un poco más tarde.

Códigos que puedes ver

invalid_json: El cuerpo de la solicitud no es un objeto JSON.
invalid_request: Falta un campo o no es válido. El mensaje indica el nombre del campo.
unauthorized: La clave de API falta, es incorrecta o fue revocada.
account_suspended: Esta cuenta de comercio está suspendida.
merchant_not_live: Tu cuenta todavía no está activa. Primero termina la configuración en el portal.
invalid_amount: El monto falta, no es un número o no es mayor que cero.
amount_too_small: El monto vale menos de 50 centavos de dólar estadounidense.
invalid_asset: El ID de moneda no corresponde a ninguna moneda conocida.
asset_not_accepted: No aceptas esa moneda.
invalid_state: La factura no permite esto en su estado actual.
not_found: No hay ningún objeto con ese ID.
server_error: Algo salió mal de nuestro lado.

El objeto factura

Las facturas tienen esta forma en las respuestas de la API y en los webhooks. Los montos son cadenas decimales, así no se pierde precisión.

idstring: ID de la factura, que empieza con inv_.
objectstring: Siempre invoice.
statusstring: El estado actual. Consulta la lista de estados más abajo.
amountstring: El precio que pediste, en currency.
currencystring: La moneda del precio, por ejemplo, USD.
amount_usdstring: El precio en dólares estadounidenses.
descriptionstring | null: Tu descripción, que se muestra al cliente.
order_idstring | null: Tu propia referencia de pedido.
customer_emailstring | null: El correo electrónico del cliente, si lo indicaste.
metadataobject: El objeto que enviaste al crear la factura, devuelto sin cambios.
coinobject | null: La moneda que eligió el cliente, o la moneda en la que realmente pagó, con su id, symbol y network. null hasta que se elige una moneda.
requested_coinobject | null: Normalmente null. Cuando el cliente pagó en otra moneda o por otra red y el pago se contabilizó, es la moneda que pedía la factura, con los mismos campos que coin. Consulta moneda o red equivocada.
pay_addressstring | null: La dirección de depósito de esta factura. null hasta que se elige una moneda.
pay_amountstring | null: El monto exacto que se debe enviar, en la moneda elegida.
network_fee_amountstring: Parte de pay_amount: la comisión de gas que el cliente paga además del precio, en la moneda. 0 si no hay.
network_fee_usdstring: La misma comisión de gas en dólares estadounidenses.
rate_usdstring | null: El precio fijado de una unidad de la moneda elegida, en dólares estadounidenses.
received_amountstring: Cuánto llegó hasta ahora, en la moneda elegida.
received_usdstring: El valor en dólares estadounidenses de lo que llegó.
overpaid_amountstring: Cuánto se pagó por encima de lo que pedía la factura, en la moneda elegida.
refunded_amountstring: Cuánto reembolsaste de este pago con enlaces de reembolso, en la moneda pagada. 0 si no reembolsaste nada.
checkout_urlstring: La página de la factura. Envía a tu cliente aquí para que pague.
redirect_urlstring | null: A dónde puede ir el cliente después de pagar.
expires_atISO 8601: Cuándo vence la factura si no se detecta ningún pago.
paid_atISO 8601 | null: Cuándo se pagó la factura, o null.
created_atISO 8601: Cuándo se creó la factura.

invoice

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Estados de la factura

openAbierta: Creada. El cliente todavía no eligió una moneda.
awaiting_paymentEsperando pago: Se eligió una moneda, se asignó la dirección de depósito y se fijó el tipo de cambio.
confirmingConfirmando: Se detectó un pago en la blockchain y está esperando confirmaciones.
underpaidPago incompleto: Al pago confirmado le falta más que tu tolerancia. El cliente puede pagar el resto o pedir un reembolso.
paidPagada: Pagada y confirmada. El monto, menos la comisión, está en tu saldo. Un reembolso parcial mantiene este estado.
expiredVencida: El tiempo se acabó antes de que se detectara algún pago.
cancelledCancelada: La factura se canceló antes de que se detectara algún pago.
refundedReembolsada: Al cliente se le reembolsó lo que envió en una factura con pago incompleto, o tú reembolsaste todo lo que te quedó de una factura pagada.

Crear una factura

POST/invoices

Crea una factura y devuelve el objeto factura con el estado 201. Envía a tu cliente a su checkout_url.

Parámetros del cuerpo

amountObligatorionumber | string: El precio, como número o cadena decimal. Debe valer al menos 50 centavos de dólar estadounidense.
currencyOpcionalstring: La moneda del precio, por ejemplo, USD. El valor predeterminado es USD.
descriptionOpcionalstring: Lo que paga el cliente, hasta 300 caracteres. Se muestra en la página de la factura.
order_idOpcionalstring: Tu propia referencia de pedido, hasta 120 caracteres, para asociar la factura a un pedido.
customer_emailOpcionalstring: El correo electrónico del cliente. Los pagos se agrupan por cliente en el portal.
customer_nameOpcionalstring: El nombre del cliente, hasta 120 caracteres.
redirect_urlOpcionalstring: Una URL completa a la que el cliente puede ir después de pagar.
metadataOpcionalobject: Cualquier objeto JSON de hasta 4 KB. Se devuelve sin cambios en la factura y en los webhooks.
coinOpcionalstring: Preselecciona una moneda por su ID, por ejemplo, USDT.TRON. Debe ser una de tus monedas aceptadas.

Con una coin preseleccionada, la dirección de depósito se asigna y el tipo de cambio se fija de inmediato, así que pay_address y pay_amount vienen completos y puedes mostrar los datos del pago en tu propia interfaz.

curl

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

Node.js

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

Listar facturas

GET/invoices

Devuelve tus facturas, de la más reciente a la más antigua, una página a la vez.

Parámetros de consulta

statusOpcionalstring: Solo las facturas con este estado, por ejemplo, paid. Debe ser uno de los estados indicados arriba.
limitOpcionalnumber: Cuántas facturas devolver, de 1 a 100. El valor predeterminado es 20.
starting_afterOpcionalstring: Un ID de factura. Devuelve las facturas que vienen después de ella, para la página siguiente.

Las facturas están en data. Cuando has_more es true, pide la página siguiente con starting_after igual al ID de la última factura que recibiste.

curl

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Respuesta

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

Obtener una factura

GET/invoices/{id}

Devuelve una factura por su ID.

curl

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Cancelar una factura

POST/invoices/{id}/cancel

Cancela una factura. Solo funciona mientras la factura no esté pagada y no se haya detectado ningún pago para ella.

curl

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Saldos

GET/balances

Devuelve lo que tu negocio tiene en cada moneda, el total en dólares estadounidenses y tu saldo de gas.

data[].coin: El ID de la moneda, por ejemplo, USDT.TRON.
data[].symbol: El símbolo de la moneda, por ejemplo, USDT.
data[].network: La red en la que está la moneda.
data[].amount: Cuánto tienes de la moneda, como cadena decimal.
data[].usd: Su valor en dólares estadounidenses al precio actual.
total_usd: El valor de todas tus monedas en dólares estadounidenses.
gas_balance_usd: Tu saldo de gas en dólares estadounidenses, que se usa para pagar las comisiones de gas.

curl

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Respuesta

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

Monedas aceptadas

GET/coins

Devuelve las monedas que aceptas en este momento, cada una con su id, symbol, name, network y decimals. Usa el id como coin cuando crees una factura. Por ejemplo:

curl

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Respuesta

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

Crear un enlace de pago

POST/payment-links

Crea un enlace de pago y lo devuelve con el estado 201, incluidos su id y su url para compartir.

Parámetros del cuerpo

titleObligatoriostring: El nombre de lo que paga el cliente, hasta 120 caracteres.
amountOpcionalnumber | string: Un precio fijo. Omítelo para que el cliente ingrese el monto.
currencyOpcionalstring: La moneda del precio. El valor predeterminado es USD.
descriptionOpcionalstring: Más detalles que se muestran al cliente, hasta 300 caracteres.

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

Respuesta

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

Listar enlaces de pago

GET/payment-links

Devuelve tus 100 enlaces de pago más recientes, del más nuevo al más antiguo, en data.

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

El objeto retiro

Los webhooks de retiros (payout.sent y payout.failed) llevan este objeto en data. Los retiros de la parte de un socio de un reparto de ingresos usan el mismo objeto, con partner_share en true.

idstring: ID del retiro.
objectstring: Siempre payout.
coinstring: El ID de la moneda, por ejemplo USDT.TRON.
amountstring: El monto retirado, en esa moneda.
network_feestring: La comisión de gas del envío, en esa moneda.
to_addressstring: La dirección de billetera a la que se envió.
statusstring: queued, running, done o failed.
tx_hashstring | null: El ID de la transacción en la blockchain, una vez enviado.
autoboolean: true si el retiro se hizo automáticamente, sin que lo solicitara una persona.
partner_shareboolean: true si este retiro es la parte de un socio de un reparto de ingresos, enviada a la billetera del socio.
created_atISO 8601: Cuándo se creó el retiro.

payout

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Después, configura los webhooks para que tu servidor se entere de los pagos en el momento en que ocurren.