Transacciones sin bandera
On Us API te permite procesar transacciones con tarjeta directamente a través de nuestra red, sin pasar por una marca (Visa, Mastercard, etc.).
Qué puedes hacer
| Recurso | Operaciones |
|---|---|
| Transacciones | Iniciar una transacción, reversar por ID de transacción, reversar por ID externo |
| Presentaciones | Enviar clearing, reversar una presentación |
Idempotencia
Todos los endpoints de escritura requieren el header X-Idempotency-Key — un UUID v4 que generas por cada operación lógica.
X-Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Si envias la misma clave mientras el request original todavía está procesándose, la API devuelve 409 Conflict. Una vez que el request original completa, reintentar con la misma clave devuelve la respuesta original.
Montos
Los valores monetarios se representan siempre como strings con hasta 2 decimales, acompañados de un código de moneda ISO 4217:
{ "amount": "1000.00", "currency": "ARS" }
{ "amount": "1000", "currency": "CLP" }
Cada request maneja tres contextos de monto:
| Campo | Significado |
|---|---|
transaction | Monto en la moneda de la transacción (ej. moneda local en el comercio) |
transaction_details | Desglose itemizado (monto base, comisiones, impuestos, etc.) |
Instrumentos
Un instrumento referencia al elemento que se usa para la transacción, actualmente solo se soporta CARD con ID.
| Tipo | Descripción |
|---|---|
CARD | Referencia una tarjeta Pomelo por ID (sin datos crudos de tarjeta) |
Transacciones (autorización)
Las transacciones se procesan de forma síncrona. Pomelo se encarga de recibir la solicitud y la enruta al emisor esperando el resultado de su estado.
La API responde con 200 OK y con información de la operación, incluyendo su estado APPROVED o REJECTED.
Si la transacción es rechazada, el campo status_detail indica el motivo, por ejemplo INSUFFICIENT_FUNDS o TRANSACTION_NOT_PERMITTED.
Tipos de transacciones soportadas:
type | Caso de uso |
|---|---|
PURCHASE | Compra en comercio (POS o e-commerce) |
WITHDRAWAL | Retiro de efectivo en cajero u oficina |
REFUND | Devolución de una compra |
BILL_PAYMENT | Pago de servicios o facturas |
Presentaciones (clearing)
Las presentaciones se procesan de forma asíncrona. La API responde con 202 Accepted y un estado PENDING de inmediato. El resultado final se entrega por webhook.
Se soportan un tipo de presentación:
type | Caso de uso |
|---|---|
PRESENTMENT | Clearing estándar único para una transacción |
Formato de error
Todas las respuestas de error siguen un envelope unificado:
{
"error": {
"error_code": "BAD_REQUEST",
"details": [
{
"code": "REQUIRED_FIELD_MISSING",
"message": "The 'transaction.type' field is required."
}
]
}
}
| HTTP code | error_code | Cuándo |
|---|---|---|
400 | BAD_REQUEST | Sintaxis inválida o campo requerido faltante |
401 | INVALID_TOKEN | Token ausente o expirado |
403 | FORBIDDEN | Acceso denegado |
404 | NOT_FOUND | Not found |
409 | IDEMPOTENCY_KEY_IN_USE | La idempotency key está siendo procesada |
500 | INTERNAL_SERVER_ERROR | Error inesperado del servidor |
Estado de la transacción
Las respuestas de autorización y reversa son sincrónicas. El campo status indica el resultado:
status | Significado |
|---|---|
APPROVED | La transacción fue aceptada |
REJECTED | La transacción fue rechazada — consulta status_detail y extra_detail para el motivo |
Valores comunes de status_detail en rechazos: INSUFFICIENT_FUNDS, TRANSACTION_NOT_PERMITTED, INVALID_CARD, LIMIT_EXCEEDED.