Pagos
Intentos de pago de los pedidos y su resultado. Aquí se confirman los pagos manuales que esperan el dinero.
Pagos
Objetos
Payment
idintegerobligatorioID del registro, único entre los registros de su tipo en la tienda.
order_idintegerobligatorioID del pedido.
pos_shift_idinteger o nullobligatorioID 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 nullobligatorioRazó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.
methodstringobligatorioMedio 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 nullobligatorioMedio de pago manual de la tienda (/v1/manual-payment-methods) cuando method es manual; si no, null.
statusstringobligatoriopending — 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
currencystringobligatorioMoneda de los importes, código ISO 4217: la moneda de la tienda.
amountintegerobligatorioImporte a pagar con este pago.
received_amountinteger o nullobligatorioImporte realmente recibido; null mientras el dinero no llegó. Lo recibido por el pedido es received_amount menos refunded_amount de sus pagos.
refunded_amountintegerobligatorioReembolsado de lo recibido.
tip_amountintegerobligatorioPropina por encima del importe del pedido.
refunded_tip_amountintegerobligatorioReembolsado de la propina.
surcharge_amountintegerobligatorioRecargo por pagar en cuotas, por encima del importe del pedido.
refunded_surcharge_amountintegerobligatorioReembolsado del recargo.
provider_fee_amountinteger o nullobligatorioComisió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 nullobligatorioParte 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 nullobligatorioImpuesto 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 nullobligatorioParte del impuesto retenido que el proveedor devolvió.
tenderobject o nullobligatorioPago 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
currencystringobligatorioMoneda del medio de pago: código ISO 4217 o código de un criptoactivo, por ejemplo USDT.
amountstringobligatorioMonto 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 nullobligatorioRecibido 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 nullobligatorioEfectivo 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 nullobligatorioCotizació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
ratestringobligatorioCotización como cadena decimal: 1 unidad de la moneda del medio = rate unidades de la moneda de la tienda.
modestring o nullobligatorioCó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 nullobligatorioFuente 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 nullobligatorioCotizació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 nullobligatorioRecargo 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 nullobligatorioVinculació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
currencystringobligatorioMoneda a la que está vinculada la moneda del medio (ISO 4217).
ratestringobligatorioCoeficiente de vinculación como cadena decimal: cuántas unidades de peg.currency vale una unidad de la moneda del medio.
received_assetobject o nullobligatorioMoneda que llegó de verdad cuando el comprador transfirió algo distinto de lo facturado y se la valuó aparte; null — llegó lo facturado.
Campos · 6
assetstringobligatorioCódigo de la moneda, por ejemplo USDC.
amountstringobligatorioCuántas monedas llegaron, como cadena decimal.
ratestringobligatorioCotización de acreditación como cadena decimal: 1 moneda = rate unidades de la moneda de la tienda.
rate_sourcestring o nullobligatorioFuente de la cotización de acreditación; manual — cotización cargada a mano.
rate_as_ofstring o nullobligatorioMomento de la cotización o de la versión de la cotización manual.
tx_idstring o nullobligatorioID de la transferencia en la blockchain o en el exchange, para conciliar.
provider_payment_idstring o nullobligatorioID de la operación en el proveedor de pagos, para conciliar con su resumen; null si no hay proveedor.
payment_urlstring o nullobligatorioPá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.
confirmablebooleanobligatorioEl 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 nullobligatorioEl pago que este reemplazó al corregir el medio de pago; si no, null.
confirmed_atstring (date-time) o nullobligatorioCuándo se recibió el dinero; null mientras no se recibió.
created_atstring (date-time)obligatorioCuándo se creó el registro.
updated_atstring (date-time)obligatorioCuá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
limitintegerTamaño de página: hasta 250 registros; 50 por defecto.
- Mínimo:
- 1
- Máximo:
- 250
cursorstringCursor 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_deletedbooleantrue — 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_idintegerSolo los registros de este pedido.
- Mínimo:
- 1
pos_shift_idintegerSolo los registros que recibió este turno de caja.
- Mínimo:
- 1
Respuestas
200Éxito
application/json
Registros de la página.
deletedarray de objectobligatorioRegistros 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
idintegerobligatorioID del registro borrado.
deleted_atstring (date-time)obligatorioCuándo se borró el registro.
next_cursorstring o nullobligatorioCursor de la página siguiente; null en la última.
has_morebooleanobligatoriotrue si hay una página siguiente.
sync_cursorstring o nullobligatorioEn 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-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos 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
curl "https://api.saleya.app/v1/payments" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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
paymentintegerobligatorioID del pago.
Respuestas
200Éxito
application/json
Devuelve Payment
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos 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
curl "https://api.saleya.app/v1/payments/{payment}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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
paymentintegerobligatorioID del pago.
Encabezado
Idempotency-KeystringClave ú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 nullComentario de la confirmación, queda en el historial del pedido.
- Largo máximo:
- 500
Respuestas
200Éxito
Encabezados
Idempotent-Replayedstringtrue 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-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerSegundos 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 409
payment_not_confirmableEl pago no se puede confirmar - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida
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
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{
"comment": "string"
}{
"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"
}