Pagos

Intentos de pago de los pedidos y su resultado. Aquí se confirman los pagos manuales que esperan el dinero.

Cargando el índice de búsqueda…

Pagos

Objetos

Payment

  • idintegerobligatorio

    ID del registro, único entre los registros de su tipo en la tienda.

  • order_idintegerobligatorio

    ID del pedido.

  • pos_shift_idinteger o nullobligatorio

    ID del turno de caja (/v1/pos-shifts) que recibió el dinero: el informe Z asigna el pago a ese turno. null — no es un pago de caja.

  • legal_entity_idinteger o nullobligatorio

    Razón social que recibe el dinero (/v1/legal-entities), la del pedido; null — la venta no está repartida entre razones sociales, y el dinero lo recibe la razón social predeterminada de la tienda.

  • methodstringobligatorio

    Medio de pago. manual — un medio manual de la tienda (manual_payment_method_id); balance — el saldo del cliente; on_account — a cuenta, el cliente debe el importe; gift_card — una tarjeta de regalo; los demás valores nombran al proveedor de pagos o el tipo de pago.

    Valores:
    cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_package
  • manual_payment_method_idinteger o nullobligatorio

    Medio de pago manual de la tienda (/v1/manual-payment-methods) cuando method es manual; si no, null.

  • statusstringobligatorio

    pending — esperando el dinero; processing — el proveedor lo procesa; succeeded — pagado; failed — fallido; partially_refunded — reembolsado en parte; refunded — reembolsado; expired — el link de pago venció; voided — anulado antes de que llegara el dinero.

    Valores:
    pendingprocessingsucceededfailedpartially_refundedrefundedexpiredvoided
  • currencystringobligatorio

    Moneda de los importes, código ISO 4217: la moneda de la tienda.

  • amountintegerobligatorio

    Importe a pagar con este pago.

  • received_amountinteger o nullobligatorio

    Importe realmente recibido; null mientras el dinero no llegó. Lo recibido por el pedido es received_amount menos refunded_amount de sus pagos.

  • refunded_amountintegerobligatorio

    Reembolsado de lo recibido.

  • tip_amountintegerobligatorio

    Propina por encima del importe del pedido.

  • refunded_tip_amountintegerobligatorio

    Reembolsado de la propina.

  • surcharge_amountintegerobligatorio

    Recargo por pagar en cuotas, por encima del importe del pedido.

  • refunded_surcharge_amountintegerobligatorio

    Reembolsado del recargo.

  • provider_fee_amountinteger o nullobligatorio

    Comisión que el proveedor de pagos descontó del pago antes de liquidarlo a la tienda. null — el proveedor no informa cargos: efectivo, medio manual o un pago que no se cobró.

  • refunded_provider_fee_amountinteger o nullobligatorio

    Parte de la comisión que el proveedor devolvió al reembolsar al comprador, según sus datos y no en proporción a refunded_amount: un reembolso por fuera del proveedor no devuelve la comisión.

  • provider_withheld_tax_amountinteger o nullobligatorio

    Impuesto que el proveedor retuvo del pago como agente de recaudación (Ingresos Brutos en MercadoPago). La retención con su jurisdicción está en el registro impositivo de la tienda.

  • refunded_provider_withheld_tax_amountinteger o nullobligatorio

    Parte del impuesto retenido que el proveedor devolvió.

  • tenderobject o nullobligatorio

    Pago en una moneda distinta de la de la tienda: una factura en USDT, una transferencia en dólares, efectivo en moneda extranjera. null — el pago es en la moneda de la tienda. Los montos del pago (amount y los demás) quedan en la moneda de la tienda, y la contabilidad se lleva con ellos.

    Campos · 5
    • currencystringobligatorio

      Moneda del medio de pago: código ISO 4217 o código de un criptoactivo, por ejemplo USDT.

    • amountstringobligatorio

      Monto de la factura en la moneda del medio, como cadena decimal: cubre amount junto con la propina y el recargo. Multiplicado por la cotización puede no coincidir con amount por el redondeo y por la parte de la factura cotizada en la moneda del medio directamente desde la lista de precios.

    • received_amountstring o nullobligatorio

      Recibido en la moneda del medio, como cadena decimal; null — lo recibido se lleva solo en la moneda de la tienda (received_amount) o llegó otra moneda (received_asset).

    • tendered_amountstring o nullobligatorio

      Efectivo en moneda extranjera: cuántos billetes se entregaron, como cadena decimal. El vuelto se da en la moneda de la tienda. null en los demás medios.

    • exchange_rateobject o nullobligatorio

      Cotización con la que el monto en la moneda del medio pasó a ser el monto del pago, tomada al emitir el pago; null si no hay cotización.

      Campos · 6
      • ratestringobligatorio

        Cotización como cadena decimal: 1 unidad de la moneda del medio = rate unidades de la moneda de la tienda.

      • modestring o nullobligatorio

        Cómo se obtuvo la cotización: auto — la cotización de mercado de la fuente más el recargo de la tienda; fixed — la cotización fijada por la tienda; pegged — la tienda vinculó la moneda del medio a otra moneda (peg), y la cotización es la de esa moneda por el coeficiente de vinculación. null en facturas emitidas antes de las reglas de cotización.

        Valores:
        autofixedpeggednull
      • sourcestring o nullobligatorio

        Fuente de la cotización de mercado: coingecko — precio agregado de CoinGecko; criptoya_p2p — mediana de los mercados P2P; ar_oficial, ar_blue, ar_mep, ar_ccl, ar_mayorista — cotizaciones del dólar en Argentina; cbr — Banco de Rusia. null si no se registró la fuente.

        Valores:
        coingeckocriptoya_p2par_oficialar_bluear_mepar_cclar_mayoristacbrnull
      • basestring o nullobligatorio

        Cotización de mercado de la fuente antes del recargo de la tienda, como cadena decimal; null si no hay base de mercado.

      • markup_bpsinteger o nullobligatorio

        Recargo de la tienda sobre la cotización de mercado en puntos básicos (100 es 1 %); puede ser negativo. null con una cotización fijada por la tienda y en facturas emitidas antes de las reglas de cotización.

      • pegobject o nullobligatorio

        Vinculación de la moneda del medio a otra moneda: 1 unidad de la moneda del medio = peg.rate unidades de peg.currency (por ejemplo, 1 USDT = 1 USD). Los precios fijados en esa moneda entran en la factura tal cual. null si la cotización no está vinculada.

        Campos · 2
        • currencystringobligatorio

          Moneda a la que está vinculada la moneda del medio (ISO 4217).

        • ratestringobligatorio

          Coeficiente de vinculación como cadena decimal: cuántas unidades de peg.currency vale una unidad de la moneda del medio.

  • received_assetobject o nullobligatorio

    Moneda que llegó de verdad cuando el comprador transfirió algo distinto de lo facturado y se la valuó aparte; null — llegó lo facturado.

    Campos · 6
    • assetstringobligatorio

      Código de la moneda, por ejemplo USDC.

    • amountstringobligatorio

      Cuántas monedas llegaron, como cadena decimal.

    • ratestringobligatorio

      Cotización de acreditación como cadena decimal: 1 moneda = rate unidades de la moneda de la tienda.

    • rate_sourcestring o nullobligatorio

      Fuente de la cotización de acreditación; manual — cotización cargada a mano.

    • rate_as_ofstring o nullobligatorio

      Momento de la cotización o de la versión de la cotización manual.

    • tx_idstring o nullobligatorio

      ID de la transferencia en la blockchain o en el exchange, para conciliar.

  • provider_payment_idstring o nullobligatorio

    ID de la operación en el proveedor de pagos, para conciliar con su resumen; null si no hay proveedor.

  • payment_urlstring o nullobligatorio

    Página de pago del proveedor mientras el pago espera el dinero: el link se puede enviar al cliente. null en un pago pagado o anulado y en un medio manual.

  • confirmablebooleanobligatorio

    El pago se puede confirmar a mano ahora (POST /v1/payments/{payment}/confirm): espera dinero cuya llegada confirma una persona, no el proveedor.

  • replaces_payment_idinteger o nullobligatorio

    El pago que este reemplazó al corregir el medio de pago; si no, null.

  • confirmed_atstring (date-time) o nullobligatorio

    Cuándo se recibió el dinero; null mientras no se recibió.

  • created_atstring (date-time)obligatorio

    Cuándo se creó el registro.

  • updated_atstring (date-time)obligatorio

    Cuándo cambió el registro por última vez.

Endpoints

Listar los pagos de pedidos cambiados desde un momento dado

get/payments

Scope: payments:read

Parámetros

Query

  • limitinteger

    Tamaño de página: hasta 250 registros; 50 por defecto.

    Mínimo:
    1
    Máximo:
    250
  • cursorstring

    Cursor opaco: next_cursor de la página anterior, o sync_cursor de la última página guardado por la sincronización anterior. El listado va en orden de confirmación, así que el cursor de sincronización devuelve luego solo lo que cambió después de él.

    Largo máximo:
    4096
  • updated_sincestring (date-time)

    Solo los registros cambiados después de este momento, ISO 8601 con zona horaria. Un filtro de la primera sincronización; después se sigue con el cursor.

    Patrón:
    ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
  • include_deletedboolean

    true — devolver también los registros eliminados: los archivados con deleted_at y los borrados de la base como marcas de eliminación {id, deleted_at} en la continuación por el cursor de sincronización. Activalo para sincronizar.

  • order_idinteger

    Solo los registros de este pedido.

    Mínimo:
    1
  • pos_shift_idinteger

    Solo los registros que recibió este turno de caja.

    Mínimo:
    1

Respuestas

200Éxito

application/json

  • dataarray de Paymentobligatorio

    Registros de la página.

  • deletedarray de objectobligatorio

    Registros borrados de la base desde el cursor, como marcas de eliminación: solo con include_deleted=true en la continuación por el cursor de sincronización.

    Campos · 2
    • idintegerobligatorio

      ID del registro borrado.

    • deleted_atstring (date-time)obligatorio

      Cuándo se borró el registro.

  • next_cursorstring o nullobligatorio

    Cursor de la página siguiente; null en la última.

  • has_morebooleanobligatorio

    true si hay una página siguiente.

  • sync_cursorstring o nullobligatorio

    En la última página — el cursor desde el que continuar más tarde: con él llega solo lo que cambió después de esta página. null en las demás.

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

410El cursor de sincronización supera el plazo de conservación de eliminaciones o se emitió antes de restaurar la base de datos

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl "https://api.saleya.app/v1/payments" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "data": [
    {
      "id": 0,
      "order_id": 0,
      "pos_shift_id": 0,
      "legal_entity_id": 0,
      "method": "cash",
      "manual_payment_method_id": 0,
      "status": "pending",
      "currency": "string",
      "amount": 0,
      "received_amount": 0,
      "refunded_amount": 0,
      "tip_amount": 0,
      "refunded_tip_amount": 0,
      "surcharge_amount": 0,
      "refunded_surcharge_amount": 0,
      "provider_fee_amount": 0,
      "refunded_provider_fee_amount": 0,
      "provider_withheld_tax_amount": 0,
      "refunded_provider_withheld_tax_amount": 0,
      "tender": {
        "currency": "string",
        "amount": "string",
        "received_amount": "string",
        "tendered_amount": "string",
        "exchange_rate": {
          "rate": "string",
          "mode": "auto",
          "source": "coingecko",
          "base": "string",
          "markup_bps": 0,
          "peg": {
            "currency": "string",
            "rate": "string"
          }
        }
      },
      "received_asset": {
        "asset": "string",
        "amount": "string",
        "rate": "string",
        "rate_source": "string",
        "rate_as_of": "string",
        "tx_id": "string"
      },
      "provider_payment_id": "string",
      "payment_url": "string",
      "confirmable": true,
      "replaces_payment_id": 0,
      "confirmed_at": "2026-01-15T12:00:00Z",
      "created_at": "2026-01-15T12:00:00Z",
      "updated_at": "2026-01-15T12:00:00Z"
    }
  ],
  "deleted": [
    {
      "id": 0,
      "deleted_at": "2026-01-15T12:00:00Z"
    }
  ],
  "next_cursor": "string",
  "has_more": true,
  "sync_cursor": "string"
}

Obtener un pago de un pedido

get/payments/{payment}

Scope: payments:read

Parámetros

Ruta

  • paymentintegerobligatorio

    ID del pago.

Respuestas

200Éxito

application/json

Devuelve Payment

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

404El objeto no existe o no está disponible para la aplicación

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl "https://api.saleya.app/v1/payments/{payment}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "id": 0,
  "order_id": 0,
  "pos_shift_id": 0,
  "legal_entity_id": 0,
  "method": "cash",
  "manual_payment_method_id": 0,
  "status": "pending",
  "currency": "string",
  "amount": 0,
  "received_amount": 0,
  "refunded_amount": 0,
  "tip_amount": 0,
  "refunded_tip_amount": 0,
  "surcharge_amount": 0,
  "refunded_surcharge_amount": 0,
  "provider_fee_amount": 0,
  "refunded_provider_fee_amount": 0,
  "provider_withheld_tax_amount": 0,
  "refunded_provider_withheld_tax_amount": 0,
  "tender": {
    "currency": "string",
    "amount": "string",
    "received_amount": "string",
    "tendered_amount": "string",
    "exchange_rate": {
      "rate": "string",
      "mode": "auto",
      "source": "coingecko",
      "base": "string",
      "markup_bps": 0,
      "peg": {
        "currency": "string",
        "rate": "string"
      }
    }
  },
  "received_asset": {
    "asset": "string",
    "amount": "string",
    "rate": "string",
    "rate_source": "string",
    "rate_as_of": "string",
    "tx_id": "string"
  },
  "provider_payment_id": "string",
  "payment_url": "string",
  "confirmable": true,
  "replaces_payment_id": 0,
  "confirmed_at": "2026-01-15T12:00:00Z",
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Confirmar que se recibió el dinero de un cobro pendiente

post/payments/{payment}/confirm

Scope: payments:write

Parámetros

Ruta

  • paymentintegerobligatorio

    ID del pago.

Encabezado

  • Idempotency-Keystring

    Clave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.

    Largo mínimo:
    1
    Largo máximo:
    255
    Ejemplo:
    8e03978e-40d5-43e8-bc93-6894a57f9324

Cuerpo de la solicitud application/json

  • commentstring o null

    Comentario de la confirmación, queda en el historial del pedido.

    Largo máximo:
    500

Respuestas

200Éxito

Encabezados

  • Idempotent-Replayedstring

    true cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.

    Valores:
    true

application/json

Devuelve Payment

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

404El objeto no existe o no está disponible para la aplicación

application/problem+json

Devuelve Problem

409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve ConflictProblem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl -X POST "https://api.saleya.app/v1/payments/{payment}/confirm" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "comment": "string"
}
Ejemplo de respuesta · 200
{
  "id": 0,
  "order_id": 0,
  "pos_shift_id": 0,
  "legal_entity_id": 0,
  "method": "cash",
  "manual_payment_method_id": 0,
  "status": "pending",
  "currency": "string",
  "amount": 0,
  "received_amount": 0,
  "refunded_amount": 0,
  "tip_amount": 0,
  "refunded_tip_amount": 0,
  "surcharge_amount": 0,
  "refunded_surcharge_amount": 0,
  "provider_fee_amount": 0,
  "refunded_provider_fee_amount": 0,
  "provider_withheld_tax_amount": 0,
  "refunded_provider_withheld_tax_amount": 0,
  "tender": {
    "currency": "string",
    "amount": "string",
    "received_amount": "string",
    "tendered_amount": "string",
    "exchange_rate": {
      "rate": "string",
      "mode": "auto",
      "source": "coingecko",
      "base": "string",
      "markup_bps": 0,
      "peg": {
        "currency": "string",
        "rate": "string"
      }
    }
  },
  "received_asset": {
    "asset": "string",
    "amount": "string",
    "rate": "string",
    "rate_source": "string",
    "rate_as_of": "string",
    "tx_id": "string"
  },
  "provider_payment_id": "string",
  "payment_url": "string",
  "confirmable": true,
  "replaces_payment_id": 0,
  "confirmed_at": "2026-01-15T12:00:00Z",
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}