Obtener

Clave de API: Payment

Devuelve el estado actual de una factura. Usa el mismo contrato de respuesta que la creación de facturas; el objeto payment aparece en cuanto se eligen token y red.

Respuesta (200 OK)

{
  "invoice_id": "inv_5CcyDYmMUGtzYL10q0Iimr",
  "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
  "status": "paid",
  "is_final": true,
  "is_test": false,
  "payment_url": "https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr",
  "order": {
    "external_id": "order-12345",
    "client_id": "customer-67890",
    "amount": "50.00",
    "currency": "USDT",
    "network": "TRC20"
  },
  "payment": {
    "currency": "USDT",
    "network": "TRC20",
    "chain_id": 728126428,
    "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "expected": "50.00",
    "address": "TLfGqSVPbET2KFczh3xb12Ja2RKfMCBPgp",
    "exchange_rate": "1.000000",
    "paid": "50.00",
    "remaining": "0",
    "fee": "0.50",
    "net": "49.50",
    "transfers": [
      {
        "tx_hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "amount": "50.00",
        "status": "confirmed",
        "created_at": 1739280712,
        "confirmed_at": 1739280912,
        "required_confirmations": 19,
        "estimated_confirmation_at": 1739280772,
        "explorer_url": "https://tronscan.org/#/transaction/abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
      }
    ]
  },
  "created_at": 1739280600,
  "updated_at": 1739280912,
  "expires_at": 1739284200,
  "completed_at": 1739280912
}

Campos de pago

Cuando payment está presente, contiene:

Campo	Tipo	Descripción
payment.currency	string	Símbolo del activo cripto elegido para pagar (por ejemplo, USDT, USDC)
payment.network	string	Código de la red blockchain (por ejemplo, ERC20, TRC20, BEP20, POLYGON, BASE, TON, SOL)
payment.chain_id	integer	Identificador numérico de cadena según las convenciones de EIP-155, TRON o TON (por ejemplo, 1 para la red principal de Ethereum, 728126428 para Tron)
payment.contract_address	string?	Identificador del token en cadena: dirección de contrato en EVM y Tron, jetton master en TON, SPL mint en Solana. Es opcional en el esquema porque una moneda nativa no tiene ese identificador; ninguna moneda nativa figura entre los activos aceptados, así que en una factura real el campo siempre trae valor. GET /v1/payment-channel-deposits/:id enuncia la misma regla para su propio contract_address
payment.expected	string	Importe en cripto que el cliente debe enviar
payment.address	string?	Dirección de depósito a la que paga el cliente. Mientras la factura sigue en awaiting_client el objeto payment entero no está en la respuesta, así que este campo nunca llega como null en una factura pendiente: sencillamente todavía no hay payment que leer
payment.exchange_rate	string?	Tipo de cambio de fiat a cripto con el que se calculó expected
payment.paid	string?	Suma de las transferencias entrantes confirmadas
payment.remaining	string?	Importe pendiente que el cliente todavía debe enviar (expected - paid, nunca negativo). Solo aparece cuando se ha confirmado al menos una transferencia
payment.fee	string?	Comisión de la plataforma descontada de paid
payment.net	string?	Importe que corresponde al comercio (paid - fee)
payment.transfers	array?	Detalle de cada transferencia; aparece cuando se ha detectado al menos una transferencia en cadena. Mira más abajo.

Campos de una transferencia

Cada entrada de payment.transfers[]:

Campo	Tipo	Descripción
tx_hash	string	Hash de la transacción en cadena (formato propio de cada red)
amount	string	Importe transferido en cripto
status	string	confirming (a la espera de confirmaciones) o confirmed
created_at	unix timestamp	Momento en que nuestro procesador vio la transferencia por primera vez en un bloque procesado. Es la hora del reloj de nuestro servidor, no la marca temporal del bloque en cadena: divergen si el procesamiento iba con retraso. Usa este campo (y no el created_at de primer nivel de la factura) en la fórmula de «segundos restantes» de más abajo.
confirmed_at	unix timestamp?	Momento en que la transferencia alcanzó el número de confirmaciones requerido. null mientras siga pendiente
required_confirmations	integer?	Confirmaciones que esta transferencia necesita para llegar a confirmed, según el tramo de valor en USD de su importe. null en toda red que se asiente con el compromiso finalized de la propia cadena en lugar de con un recuento de bloques: hoy BNB Smart Chain, Polygon, Solana, Avalanche y Plasma. Ramifica por el null, no por una lista de redes: qué cadenas confirman por finalidad es un parámetro operativo y puede cambiar
estimated_confirmation_at	unix timestamp?	Momento en que se espera que la transferencia quede liquidada. En las redes que cuentan bloques se calcula al detectarla como transfer.created_at + required_confirmations × network_block_time; en las redes de finalidad, donde no hay recuento de bloques, es transfer.created_at más la finalidad típica de esa cadena, para que la espera se pueda pintar igual. Es un valor fijo: NO se desplaza entre peticiones, devuelve lo mismo en cada consulta hasta que la transferencia se confirma (o hasta que cambia su tramo en USD). Para los «segundos restantes», calcula en el cliente max(0, estimated_confirmation_at − now).
explorer_url	string?	Enlace directo a esta transacción en el explorador de bloques de la red (Tronscan, Etherscan, Tonviewer, etc.). null si la red no tiene explorador público configurado. Puedes mostrarlo tal cual como enlace pulsable, sin transformación alguna.

Estados de la factura

Toda factura informa de un status en forma de cadena. Ese mismo valor alimenta la respuesta de la Merchant API, el flujo SSE de la página de pago y el contenido del webhook: hay una sola fuente de verdad. La tabla siguiente es la referencia por estado: cuándo aparece el valor, si es final y cuál es la condición exacta que lo produce. Para el diagrama de transiciones y las dos formas de crear una factura, consulta Flujo de pago.

Un estado final es definitivo: la factura se queda ahí y ya no vuelve a moverse. Cinco estados son finales: paid, paid_over, underpaid, expired y cancelled.

Estado	Final	Cuándo se aplica
awaiting_client	No	Estado inicial de toda factura. Todavía no se ha elegido token ni red, así que no existe dirección de depósito. La cancelación solo se permite aquí
awaiting_payment	No	Token, red y dirección de depósito quedan fijados. Paymos vigila la dirección a la espera de una transferencia entrante
confirming	No	Una transferencia ha llegado a la cadena y acumula las confirmaciones que exige su tramo de importe
underpaid_waiting	No	Ha entrado menos del importe esperado y la factura sigue abierta esperando el resto. Solo se alcanza cuando allow_multiple_payments vale true
paid	Sí	El importe esperado entró íntegro (o dentro de la tolerancia de pago insuficiente del proyecto)
paid_over	Sí	Entró más del importe esperado; la transferencia se abona completa
underpaid	Sí	La factura se cerró con menos de lo debido: o venció por debajo del importe esperado, o un único pago se quedó corto con allow_multiple_payments en false
expired	Sí	El plazo venció sin recibir nada, o en el flujo fiat se agotó la ventana de selección de token antes de elegir uno
cancelled	Sí	El comercio canceló la factura mientras seguía en awaiting_client

Errores

Consulta Códigos de error para el catálogo completo. La URI de type en cada respuesta de error enlaza directamente con la fila correspondiente.