{"openapi":"3.0.0","components":{"examples":{},"headers":{},"parameters":{},"requestBodies":{},"responses":{},"schemas":{"ChytaError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"id":{"type":"string"},"cause":{"type":"string"}},"required":["code","message","id"],"type":"object","additionalProperties":false},"IntegrationPaymentRequestState":{"enum":["draft","pending","total_payment","canceled","overdue","partial_payment","partial_overdue"],"type":"string"},"GetAllPaymentRequestsResponseBody":{"properties":{"paymentRequestId":{"type":"string","description":"ID interno del cobro en ChytaPay."},"referenceId":{"type":"string","description":"El `referenceId` que asignaste al crear el cobro."},"amount":{"type":"number","format":"double","description":"Monto del cobro."},"paidAmount":{"type":"number","format":"double","description":"Monto pagado acumulado."},"dueDate":{"type":"string","description":"Vencimiento del cobro en formato YYYY-MM-DD.","format":"date"},"status":{"$ref":"#/components/schemas/IntegrationPaymentRequestState","description":"Estado actual del cobro."},"customer":{"properties":{"email":{"type":"string"},"phoneNumber":{"type":"string"},"name":{"type":"string"}},"required":["name"],"type":"object","description":"Datos del pagador."},"createdAt":{"type":"string","description":"Fecha de creación del cobro (ISO).","format":"date-time"}},"required":["paymentRequestId","referenceId","amount","paidAmount","dueDate","status","customer","createdAt"],"type":"object","additionalProperties":false},"PostPaymentRequestResponseBody":{"properties":{"referenceId":{"type":"string","description":"El mismo `referenceId` que enviaste en el request."},"amount":{"type":"number","format":"double","description":"Monto del cobro (ausente si se creó en borrador sin monto)."},"description":{"type":"string","description":"Descripción del cobro."},"dueDates":{"items":{"type":"string"},"type":"array","description":"Fechas de vencimiento en formato YYYY-MM-DD.","format":"date"},"state":{"$ref":"#/components/schemas/IntegrationPaymentRequestState","description":"Estado del cobro (pendiente, parcial, pagado, borrador, etc.)."},"surcharge":{"properties":{"value":{"type":"number","format":"double"},"type":{"type":"string","enum":["percentage","fixed"]}},"required":["value","type"],"type":"object","description":"Recargo configurado, presente solo si se envió más de un vencimiento."},"calculatedAmounts":{"items":{"properties":{"isOriginalAmount":{"type":"boolean","description":"True si es el monto original sin recargo (primer vencimiento)."},"surchargeApplied":{"type":"number","format":"double","description":"Monto del recargo aplicado (solo presente si hay surcharge)."},"amount":{"type":"number","format":"double","description":"Monto total a pagar en ese vencimiento."},"dueDate":{"type":"string","format":"date"}},"required":["amount","dueDate"],"type":"object"},"type":"array","description":"Monto calculado para cada vencimiento (incluye el recargo aplicado al segundo)."},"sendWhatsappNotification":{"type":"boolean","description":"Canal WhatsApp habilitado para las notificaciones de este cobro."},"sendEmailNotification":{"type":"boolean","description":"Canal email habilitado para las notificaciones de este cobro."},"reminderNotificationDate":{"type":"string","description":"Fecha del recordatorio de pago configurado (si se envió).","format":"date"},"deferredInitialNotificationDate":{"type":"string","description":"Fecha de la notificación inicial diferida (si se envió).","format":"date"},"customer":{"properties":{"taxDocument":{"type":"string","description":"CUIL/DNI del pagador. Presente solo cuando `conciliationType` es 'cuil'."},"email":{"type":"string"},"phoneNumber":{"properties":{"number":{"type":"string"},"countryCode":{"type":"string"}},"required":["number","countryCode"],"type":"object"},"name":{"type":"string"}},"required":["name"],"type":"object","description":"Datos del pagador, tal como se enviaron en el request."},"CVU":{"type":"string","description":"CVU donde el pagador debe transferir para pagar este cobro."},"bankAccountInfo":{"properties":{"bankName":{"type":"string","description":"Nombre del banco."},"accountHolderTaxId":{"type":"string","description":"CUIT del titular de la cuenta."},"accountHolderName":{"type":"string","description":"Nombre del titular de la cuenta."}},"required":["bankName","accountHolderTaxId","accountHolderName"],"type":"object","description":"Datos bancarios del titular de la cuenta de cobro (la sede/comercio que recibe el dinero)."}},"required":["referenceId","description","dueDates","state","sendWhatsappNotification","sendEmailNotification","customer","CVU","bankAccountInfo"],"type":"object","additionalProperties":false},"IntegrationSurchargeInputType":{"type":"string","enum":["percentage","fixed","none"],"description":"Surcharge type accepted from external integrators on input.\n\"percentage\" is the canonical public value. Internal code stores \"%\" —\nsee paymentRequest.surchargeMapper for the boundary translation."},"ConciliationMode":{"enum":["cvu","cuil"],"type":"string"},"PostPaymentRequestRequestBody":{"properties":{"referenceId":{"type":"string","description":"ID de referencia único, generado por tu sistema, para identificar este cobro.\nEl mismo valor se devuelve en el webhook y en las consultas, así podés vincular\nel evento con la entidad de tu sistema (factura, pedido, socio, etc.).\n\nSi operás varias cuentas/sedes bajo la misma integración, podés prefijar un\nidentificador en este campo —debe seguir siendo único por cobro—, por ejemplo\n\"SEDE01-FACT00123\".\n\nLargo: 8 a 100 caracteres. Solo letras, números, guion (-) y guion bajo (_).","example":"SEDE01-FACT00123"},"amount":{"type":"number","format":"double","description":"Monto del cobro en pesos, con hasta 2 decimales (máximo 10.000.000).\n\nOPCIONAL. Si se omite, el cobro se crea en estado borrador (DRAFT): no se envían\nnotificaciones y solo se admite 1 vencimiento. El monto se completa después con\nPATCH /payment-request/{referenceId}.","example":15000.5},"description":{"type":"string","description":"Descripción del cobro que ve el pagador. Largo: 3 a 500 caracteres.","example":"Cuota mes de marzo"},"dueDates":{"items":{"type":"string"},"type":"array","description":"Fechas de vencimiento en formato YYYY-MM-DD. El primer elemento es el PRIMER\nvencimiento; el segundo (opcional) es el SEGUNDO vencimiento.\n\nReglas:\n- 1 o 2 fechas (solo 1 si no se envía `amount`, estado borrador).\n- Cada fecha debe ser posterior a hoy y como máximo a 35 días de hoy.\n- El recargo (`surcharge`) se aplica sobre el segundo vencimiento.","example":["2025-03-01","2025-03-15"],"format":"date"},"surcharge":{"properties":{"value":{"type":"number","format":"double","description":"Valor del recargo: monto en pesos si es 'fixed', porcentaje 0-100 si es 'percentage', 0 si es 'none'."},"type":{"$ref":"#/components/schemas/IntegrationSurchargeInputType","description":"Tipo de recargo: 'fixed' (monto fijo en pesos), 'percentage' (porcentaje 0-100), 'none' (sin recargo)."}},"required":["value","type"],"type":"object","description":"Recargo que se aplica al segundo vencimiento (cuando se envían 2 fechas).\n- Obligatorio si hay `amount` y 2 vencimientos.\n- No debe enviarse si no hay `amount` (estado borrador).","example":{"type":"fixed","value":100}},"sendWhatsappNotification":{"type":"boolean","description":"Enviar la solicitud de cobro y sus recordatorios por WhatsApp.\nObligatorio si se envía `amount`; requiere `customer.phoneNumber`.\nDebe ser false (o omitirse) cuando no hay `amount`."},"sendEmailNotification":{"type":"boolean","description":"Enviar la solicitud de cobro y sus recordatorios por email.\nObligatorio si se envía `amount`; requiere `customer.email`.\nDebe ser false (o omitirse) cuando no hay `amount`."},"reminderNotificationDate":{"type":"string","description":"Fecha (YYYY-MM-DD) del recordatorio de pago. Si se omite, se usa el default\n(1 día antes del vencimiento). Debe ser posterior a hoy, anterior al primer\nvencimiento y —si hay notificación diferida— posterior a esa fecha.\nSolo válido cuando se envía `amount`.","example":"2025-02-27","format":"date"},"deferredInitialNotificationDate":{"type":"string","description":"Fecha (YYYY-MM-DD) para diferir el envío de la notificación INICIAL del cobro,\nen vez de enviarla al crearlo. Debe ser posterior a hoy y anterior al primer\nvencimiento. Solo válido cuando se envía `amount`.","example":"2025-02-20","format":"date"},"conciliationType":{"$ref":"#/components/schemas/ConciliationMode","description":"Modo de conciliación del cobro:\n- 'cvu' (default): el pagador transfiere al CVU del cobro; se concilia por la transferencia.\n- 'cuil': se concilia por el CUIL/DNI del pagador; requiere `customer.taxDocument`.","example":"cvu"},"customer":{"properties":{"taxDocument":{"type":"string","description":"CUIL (11 dígitos) o DNI (7-8 dígitos) del pagador.\nObligatorio cuando `conciliationType` es 'cuil'; ignorado en modo 'cvu'.","example":"20304050607"},"email":{"type":"string","description":"Email del pagador.","example":"juan@example.com"},"phoneNumber":{"properties":{"number":{"type":"string","description":"Código de área + número, solo dígitos (6 a 15).","example":"1112345678"},"countryCode":{"type":"string","description":"Código de país con prefijo +.","example":"+54"}},"required":["number","countryCode"],"type":"object"},"name":{"type":"string","description":"Nombre del pagador. Largo: 2 a 150 caracteres.","example":"Juan Pérez"}},"required":["name"],"type":"object","description":"Datos del pagador. `phoneNumber` es obligatorio si `sendWhatsappNotification`\nes true; `email` es obligatorio si `sendEmailNotification` es true;\n`taxDocument` es obligatorio si `conciliationType` es 'cuil'."}},"required":["referenceId","description","dueDates","surcharge","sendWhatsappNotification","sendEmailNotification","customer"],"type":"object","additionalProperties":false},"GetPaymentRequestResponseBody":{"$ref":"#/components/schemas/PostPaymentRequestResponseBody"},"PatchPaymentRequestResponseBody":{"properties":{"referenceId":{"type":"string","description":"El `referenceId` del cobro actualizado."},"previousAmount":{"type":"number","format":"double","nullable":true,"description":"Monto que tenía el cobro antes del PATCH (null si era un borrador sin monto)."},"amount":{"type":"number","format":"double","description":"Nuevo monto del cobro."},"description":{"type":"string","description":"Descripción del cobro."},"state":{"$ref":"#/components/schemas/IntegrationPaymentRequestState","description":"Estado del cobro tras la actualización."},"dueDates":{"items":{"type":"string"},"type":"array","description":"Fechas de vencimiento en formato YYYY-MM-DD.","format":"date"},"surcharge":{"properties":{"value":{"type":"number","format":"double"},"type":{"type":"string","enum":["percentage","fixed"]}},"required":["value","type"],"type":"object","description":"Recargo configurado, si aplica."},"calculatedAmounts":{"items":{"properties":{"isOriginalAmount":{"type":"boolean"},"surchargeApplied":{"type":"number","format":"double"},"amount":{"type":"number","format":"double"},"dueDate":{"type":"string","format":"date"}},"required":["amount","dueDate"],"type":"object"},"type":"array","description":"Monto calculado por vencimiento (incluye el recargo aplicado al segundo)."}},"required":["referenceId","previousAmount","amount","description","state","dueDates"],"type":"object","additionalProperties":false},"PatchPaymentRequestRequestBody":{"properties":{"amount":{"type":"number","format":"double","description":"Monto a asignar al cobro (en pesos, hasta 2 decimales, máximo 10.000.000).\nSe usa para completar un cobro creado en borrador (sin monto).","example":15000.5}},"required":["amount"],"type":"object","additionalProperties":false},"CancelPaymentRequestResponseBody":{"properties":{"referenceId":{"type":"string","description":"El `referenceId` del cobro cancelado."},"state":{"$ref":"#/components/schemas/IntegrationPaymentRequestState","description":"Estado del cobro tras la cancelación (siempre \"canceled\")."}},"required":["referenceId","state"],"type":"object","additionalProperties":false}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"ID Token obtenido mediante OAuth2"}}},"info":{"title":"Chytapay Integration API","version":"1.0.0","description":"API para crear y gestionar solicitudes de pago (cobros) en nombre de las cuentas de comercio conectadas a tu integración.\n\n## Conceptos\n\n- **Integración**: la conexión entre tu plataforma y ChytaPay. Tiene sus propias credenciales OAuth (`clientId` / `clientSecret`) y un **webhook** donde recibís los eventos de pago. Una misma integración puede operar sobre **varias cuentas de comercio**.\n- **Cuenta de comercio**: cada comercio (o sede) que cobra. Tiene su propio CVU; el dinero de cada cobro se acredita en su cuenta. Se vincula a tu integración mediante OAuth.\n- **Cobro (payment request)**: la solicitud de pago que generás para un pagador.\n- **`referenceId`**: identificador único que **vos** asignás a cada cobro. Vuelve idéntico en el webhook y en las consultas — es tu llave para reconciliar el evento con la entidad de tu sistema (factura, inscripción, socio, etc.).\n\n## Autenticación (OAuth2)\n\nTodos los endpoints requieren un **Bearer token** obtenido por OAuth2 (Authorization Code). El flujo se hace contra la **Auth API** y tiene 3 pasos:\n\n1. `GET /integration/oauth2/authorize` — parámetros: `clientId`, `redirectUri`, `responseType=code`, `scope`, `state`. Redirige al login de ChytaPay, donde el dueño de la cuenta de comercio autoriza el acceso.\n2. `POST /integration/oauth2/complete-login` — la cuenta de comercio se autentica; se genera un `code` y se redirige a tu `redirectUri` con `?code=...`.\n3. `POST /integration/oauth2/token` — intercambiás `code` + `clientId` + `clientSecret` + `redirectUri` por los tokens.\n\nAl completar el intercambio, la cuenta de comercio queda **vinculada a tu integración** y ya podés crear cobros en su nombre. Repetís el flujo una vez por cada cuenta de comercio que se suma.\n\nEnviá el token en cada request:\n\n```\nAuthorization: Bearer <id_token>\n```\n\n## Webhook\n\nCuando cambia el estado de un cobro, ChytaPay hace un `POST` a la URL de webhook de tu integración, con el `referenceId` y los montos/estado del cobro.\n\nEl webhook se configura **a nivel de la integración** (un webhook por integración) desde el portal de administración. El payload **no incluye** un identificador de cuenta de comercio: para distinguir a qué cuenta o entidad corresponde cada evento, usá el `referenceId` que asignaste al crear el cobro.\n\nCampos de monto del payload:\n\n- **`requestedAmount`**: monto original solicitado (sin recargos).\n- **`paidAmount`**: monto pagado **acumulado** del cobro (suma de todos los pagos recibidos).\n- **`thisPaymentAmount`**: monto de **este** pago puntual — la transacción que disparó este evento. Te permite registrar el pago individual sin tener que restarlo contra el acumulado anterior. Ausente si el evento no corresponde a un pago.\n- **`remainingAmount`**: saldo restante por pagar sobre el vencimiento activo.\n\n## Notificaciones al pagador\n\nAl crear un cobro **con monto** podés habilitar avisos por WhatsApp y/o email (`sendWhatsappNotification` / `sendEmailNotification`). Los recordatorios se programan **automáticamente según las fechas de vencimiento** (`dueDates`):\n\n- **Primer vencimiento**: aviso el día del vencimiento + uno 1 día antes (por defecto).\n- **Segundo vencimiento** (si lo cargás): aviso el día del 2do vencimiento + uno cuando vence el primero.\n\nOpcionalmente ajustás una fecha de recordatorio propia (`reminderNotificationDate`) o diferís el aviso inicial del cobro (`deferredInitialNotificationDate`).\n\n## Conciliación\n\nEl campo `conciliationType` define cómo se concilia el pago:\n\n- **`cvu`** (default): el pagador transfiere al CVU del cobro; se concilia por la transferencia.\n- **`cuil`**: se concilia por el CUIL/DNI del pagador (`customer.taxDocument`, obligatorio en este modo).\n\n## Estado borrador (DRAFT)\n\nSi creás un cobro **sin `amount`**, queda en estado borrador: no se envían notificaciones y solo se admite 1 vencimiento. El monto se completa después con `PATCH /payment-request/{referenceId}`.\n","license":{"name":"ISC"},"contact":{"name":"Chytapay Support","email":"contacto@chytapay.com.ar","url":"https://chytapay.com.ar/api/getting-started"}},"paths":{"/payment-request":{"get":{"operationId":"getAllPaymentRequests","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/GetAllPaymentRequestsResponseBody"},"type":"array"}}}},"403":{"description":"Token inválido, vencido, o la cuenta no está autorizada para esta integración.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}},"404":{"description":"No existe un cobro con ese referenceId para tu integración.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}},"500":{"description":"Error interno del servidor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}}},"description":"Lista los cobros (payment requests) creados a través de tu integración para la\ncuenta de comercio autenticada. Opcionalmente podés filtrar por rango de fechas\nde creación.","tags":["PaymentRequest"],"security":[{"bearer":[]}],"parameters":[{"description":"Filtra cobros creados desde esta fecha, inclusive. Formato YYYY-MM-DD (ej. \"2025-03-01\").","in":"query","name":"startDate","required":false,"schema":{"type":"string"}},{"description":"Filtra cobros creados hasta esta fecha, inclusive. Formato YYYY-MM-DD (ej. \"2025-03-31\").","in":"query","name":"endDate","required":false,"schema":{"type":"string"}}]},"post":{"operationId":"postPaymentRequest","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostPaymentRequestResponseBody"}}}},"400":{"description":"Datos inválidos. Revisá el detalle de validación en el cuerpo del error (campos faltantes, fechas fuera de rango, monto inválido, etc.).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"403":{"description":"Token inválido, vencido, o la cuenta no está autorizada para esta integración.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}},"404":{"description":"No existe un cobro con ese referenceId para tu integración.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}},"429":{"description":"Demasiadas solicitudes — superaste el límite de rate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"500":{"description":"Error interno del servidor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}}},"description":"Crea un nuevo cobro (payment request) en nombre de la cuenta de comercio\nautenticada. El `referenceId` que envíes te volverá idéntico en el webhook para\nque puedas reconciliar el pago con tu sistema. Si omitís `amount`, el cobro se\ncrea en estado borrador (DRAFT) y se completa luego con PATCH.","tags":["PaymentRequest"],"security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostPaymentRequestRequestBody"}}}}}},"/payment-request/{referenceId}":{"get":{"operationId":"getPaymentRequestByReferenceId","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPaymentRequestResponseBody"}}}},"403":{"description":"Token inválido, vencido, o la cuenta no está autorizada para esta integración.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}},"404":{"description":"No existe un cobro con ese referenceId para tu integración.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"500":{"description":"Error interno del servidor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}}},"description":"Obtiene un cobro puntual por el `referenceId` que asignaste al crearlo.","tags":["PaymentRequest"],"security":[{"bearer":[]}],"parameters":[{"description":"El identificador único que asignaste al crear el cobro.","in":"path","name":"referenceId","required":true,"schema":{"type":"string"}}]},"patch":{"operationId":"patchPaymentRequest","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchPaymentRequestResponseBody"}}}},"400":{"description":"Monto inválido (debe ser positivo, hasta 2 decimales, máximo 10.000.000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"403":{"description":"Token inválido, vencido, o la cuenta no está autorizada para esta integración.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}},"404":{"description":"No existe un cobro con ese referenceId para tu integración.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"409":{"description":"El cobro no se puede modificar en su estado actual (por ejemplo, ya fue pagado).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"500":{"description":"Error interno del servidor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}}},"description":"Completa o actualiza el monto de un cobro existente —por ejemplo, para asignar\nel monto a un cobro creado en estado borrador (DRAFT)—. Se identifica por su\n`referenceId`.","tags":["PaymentRequest"],"security":[{"bearer":[]}],"parameters":[{"description":"El identificador único del cobro a actualizar.","in":"path","name":"referenceId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchPaymentRequestRequestBody"}}}}}},"/payment-request/{referenceId}/cancel":{"post":{"operationId":"cancelPaymentRequest","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelPaymentRequestResponseBody"}}}},"403":{"description":"Token inválido, vencido, o la cuenta no está autorizada para esta integración.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}},"404":{"description":"No existe un cobro con ese referenceId para tu integración.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"409":{"description":"El cobro no puede cancelarse en su estado actual (pago parcial, pagado, vencido o ya cancelado).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"500":{"description":"Error interno del servidor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}}},"description":"Cancela un cobro existente por su `referenceId`.\nSolo se pueden cancelar cobros en estado borrador (DRAFT) o pendiente (PENDING).\nCobros con pagos parciales, pagados, vencidos o ya cancelados no pueden cancelarse.","tags":["PaymentRequest"],"security":[{"bearer":[]}],"parameters":[{"description":"El identificador único del cobro a cancelar.","in":"path","name":"referenceId","required":true,"schema":{"type":"string"}}]}}},"servers":[{"url":"https://integration-api.chytapay.com.ar","description":"PROD"},{"url":"https://integration-api.test.chytapay.com.ar","description":"TEST"},{"url":"https://integration-api.dev.chytapay.com.ar","description":"DEV"}]}