{"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},"Record_string.string_":{"properties":{},"additionalProperties":{"type":"string"},"type":"object","description":"Construct a type with a set of properties K of type T"},"PostPaymentRequestResponseBody":{"properties":{"paymentRequestId":{"type":"string","description":"ID interno del cobro en ChytaPay (UUID). Se usa para construir las URLs de\npolling y de acciones (`/v1/payments/{id}`) en la API pública del widget."},"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"},"webhookUrl":{"type":"string","description":"URL de webhook propia del cobro, tal como se persistió. Ausente (no `null`)\nsi el cobro no definió una URL per-request. El despacho a esta URL usa un\n`validation-token` vacío.","example":"https://hooks.example.com/pay"},"metadata":{"$ref":"#/components/schemas/Record_string.string_","description":"Integrator-supplied metadata echoed verbatim from the request.\nAbsent (not `null`) when the payment request was created without metadata.","example":{"order_id":"abc-123","tenant":"acme"}},"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"},"webhookUrl":{"type":"string","description":"URL de webhook propia de este cobro. Si se envía, REEMPLAZA por completo la\nURL global de la integración para los eventos de ESTE cobro.\n\nDebe ser HTTPS y de hasta 2048 caracteres. El despacho a esta URL usa un\n`validation-token` vacío (`\"\"`): al proveer tu propia URL controlás el\nrouting y no dependés del token de validación global de la integración.","example":"https://hooks.example.com/pay"},"metadata":{"$ref":"#/components/schemas/Record_string.string_","description":"Arbitrary key-value pairs (string → string) to attach to this payment request.\nReturned in every response and webhook. Max 50 keys; key max 40 chars;\nvalue max 500 chars; total serialized max 8192 bytes.","example":{"order_id":"abc-123","tenant":"acme"}},"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},"PostPaymentRequestBulkResponseBody":{"description":"Respuesta 201 del endpoint bulk. El detalle de cada cobro se consulta con\nGET /payment-request/{referenceId}. El CVU es compartido a nivel batch.","properties":{"batchId":{"type":"string","description":"ID del batch creado."},"total":{"type":"number","format":"double","description":"Cantidad total de cobros solicitados (= paymentRequests.length)."},"created":{"type":"number","format":"double","description":"Cantidad de cobros efectivamente creados."},"sharedCvu":{"type":"string","description":"CVU compartido por todos los cobros del batch."},"accountInfo":{"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 (a nivel batch)."},"paymentRequests":{"items":{"properties":{"state":{"$ref":"#/components/schemas/IntegrationPaymentRequestState","description":"Estado inicial del cobro (pending o draft)."},"referenceId":{"type":"string","description":"El `referenceId` que enviaste para este cobro."}},"required":["state","referenceId"],"type":"object"},"type":"array","description":"Una entrada por cobro creado, en el mismo orden del request."}},"required":["batchId","total","created","sharedCvu","accountInfo","paymentRequests"],"type":"object","additionalProperties":false},"Pick_PostPaymentRequestRequestBody.Exclude_keyofPostPaymentRequestRequestBody.conciliationType-or-customer__":{"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"},"type":{"$ref":"#/components/schemas/IntegrationSurchargeInputType"}},"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"},"webhookUrl":{"type":"string","description":"URL de webhook propia de este cobro. Si se envía, REEMPLAZA por completo la\nURL global de la integración para los eventos de ESTE cobro.\n\nDebe ser HTTPS y de hasta 2048 caracteres. El despacho a esta URL usa un\n`validation-token` vacío (`\"\"`): al proveer tu propia URL controlás el\nrouting y no dependés del token de validación global de la integración.","example":"https://hooks.example.com/pay"},"metadata":{"$ref":"#/components/schemas/Record_string.string_","description":"Arbitrary key-value pairs (string → string) to attach to this payment request.\nReturned in every response and webhook. Max 50 keys; key max 40 chars;\nvalue max 500 chars; total serialized max 8192 bytes.","example":{"order_id":"abc-123","tenant":"acme"}}},"required":["referenceId","description","dueDates","surcharge","sendWhatsappNotification","sendEmailNotification"],"type":"object","description":"From T, pick a set of properties whose keys are in the union K"},"Omit_PostPaymentRequestRequestBody.conciliationType-or-customer_":{"$ref":"#/components/schemas/Pick_PostPaymentRequestRequestBody.Exclude_keyofPostPaymentRequestRequestBody.conciliationType-or-customer__","description":"Construct a type with the properties of T except for those in type K."},"Pick_PostPaymentRequestRequestBody-at-customer.Exclude_keyofPostPaymentRequestRequestBody-at-customer.taxDocument__":{"properties":{"name":{"type":"string","description":"Nombre del pagador. Largo: 2 a 150 caracteres.","example":"Juan Pérez"},"phoneNumber":{"properties":{"number":{"type":"string"},"countryCode":{"type":"string"}},"required":["number","countryCode"],"type":"object"},"email":{"type":"string","description":"Email del pagador.","example":"juan@example.com"}},"required":["name"],"type":"object","description":"From T, pick a set of properties whose keys are in the union K"},"Omit_PostPaymentRequestRequestBody-at-customer.taxDocument_":{"$ref":"#/components/schemas/Pick_PostPaymentRequestRequestBody-at-customer.Exclude_keyofPostPaymentRequestRequestBody-at-customer.taxDocument__","description":"Construct a type with the properties of T except for those in type K."},"PostPaymentRequestBulkItemBody":{"allOf":[{"$ref":"#/components/schemas/Omit_PostPaymentRequestRequestBody.conciliationType-or-customer_"},{"properties":{"customer":{"allOf":[{"$ref":"#/components/schemas/Omit_PostPaymentRequestRequestBody-at-customer.taxDocument_"},{"properties":{"taxDocument":{"type":"string","description":"CUIL (11 dígitos) o DNI (7-8 dígitos) del pagador. Obligatorio.","example":"20304050607"}},"required":["taxDocument"],"type":"object"}]}},"required":["customer"],"type":"object"}],"description":"Item de un request bulk. Es idéntico al body del endpoint single\n(PostPaymentRequestRequestBody) salvo que NO lleva `conciliationType` —el bulk\nes siempre CUIL— y `customer.taxDocument` es OBLIGATORIO."},"PostPaymentRequestBulkRequestBody":{"description":"Body del endpoint `POST /payment-request/bulk`.\nArray de 1 a 100 items; todos se crean de forma atómica (all-or-nothing).","properties":{"paymentRequests":{"items":{"$ref":"#/components/schemas/PostPaymentRequestBulkItemBody"},"type":"array","description":"Lista de cobros a crear (1 a 100). Todos comparten el mismo CVU del batch."}},"required":["paymentRequests"],"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},"PatchPaymentRequestCustomerResponseBody":{"properties":{"referenceId":{"type":"string","description":"El `referenceId` del cobro actualizado."},"customer":{"properties":{"taxDocument":{"type":"string"},"email":{"type":"string"},"phoneNumber":{"properties":{"number":{"type":"string"},"countryCode":{"type":"string"}},"required":["number","countryCode"],"type":"object"},"name":{"type":"string"}},"required":["taxDocument"],"type":"object","description":"Datos del pagador tal como quedaron guardados tras el PATCH."},"CVU":{"type":"string","description":"CVU vigente del cobro después del PATCH."},"cvuChanged":{"type":"boolean","description":"`true` si el documento nuevo colisionaba en el CVU anterior y hubo que mover\nel cobro a otro. Avisale al pagador: el CVU al que tiene que transferir cambió."},"payerChanged":{"type":"boolean","description":"`true` si el cobro quedó apuntando a OTRO pagador (el documento nuevo no\nnormaliza al mismo que tenía). `false` en el caso típico de corrección de\ntipeo sobre la misma persona."},"profileUpdated":{"type":"boolean","description":"`true` si `name`/`phoneNumber`/`email` modificaron el perfil guardado del\npagador. Ese perfil es por persona (no por cobro): si ese pagador tiene otros\ncobros abiertos con este comercio, también los ve actualizados."}},"required":["referenceId","customer","CVU","cvuChanged","payerChanged","profileUpdated"],"type":"object","additionalProperties":false},"PatchPaymentRequestCustomerRequestBody":{"description":"Body de `PATCH /payment-request/{referenceId}/customer`.\n\nPlano a propósito (no envuelto en `customer`): la URL ya dice `/customer` y los\ncampos son idénticos a los del `customer` del POST, así que el integrador reusa\nel mismo objeto. Todo es opcional salvo `taxDocument`: lo que no mandes queda\ncomo estaba.","properties":{"name":{"type":"string","description":"Nombre del pagador. Largo: 2 a 150 caracteres.","example":"Pepe Gomez"},"phoneNumber":{"properties":{"number":{"type":"string","description":"Código de área + número, solo dígitos (6 a 15).","example":"3512345678"},"countryCode":{"type":"string","description":"Código de país con prefijo +.","example":"+54"}},"required":["number","countryCode"],"type":"object"},"email":{"type":"string","description":"Email del pagador.","example":"pepe@example.com"},"taxDocument":{"type":"string","description":"CUIL (11 dígitos) o DNI (7-8 dígitos) del pagador. Obligatorio: es el dato\nque se está corrigiendo y el que define la asignación de CVU.","example":"20273621009"}},"required":["taxDocument"],"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},"GetPayerLookupResponseBody":{"description":"MINIMAL DISCLOSURE by design: only the three fields a \"¿Sos [Nombre]?\"\nconfirmation needs. The padrón also returns domicilio fiscal, condición fiscal\nand activities — none of it is exposed here, and none should ever be added.\n\n`name: null` means ARCA answered and no titular matched (most likely a typo).\nIt never means \"ARCA was down\" — that is a 503.","properties":{"name":{"type":"string","nullable":true,"description":"Razón social (legal person) or \"Nombre Apellido\" (physical person)."},"taxId":{"type":"string","nullable":true,"description":"The CUIL/CUIT the name was resolved under. Null when there is no match."},"taxIdType":{"type":"string","enum":["CUIT","CUIL",null],"nullable":true}},"required":["name","taxId","taxIdType"],"type":"object","additionalProperties":false},"PutTenantResponseBody":{"properties":{"message":{"type":"string"}},"required":["message"],"type":"object","additionalProperties":false},"PutTenantRequestBody":{"properties":{"tenantKey":{"type":"string"}},"required":["tenantKey"],"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\nEsta es una introducción resumida. La guía completa (conceptos, ciclo de vida, crear cobros, conciliación, notificaciones, webhook, cómo probar y preguntas frecuentes) está en la [documentación de Chytapay](https://chytapay.com.ar/api/getting-started).\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## Validar al pagador antes de cobrar\n\nEn modo de conciliación `cuil` el cobro se identifica por el documento del pagador, así que un documento mal tipeado hace que el pago no se concilie. Para evitarlo podés confirmar la identidad **antes** de crear el cobro:\n\n1. El pagador ingresa su CUIL/CUIT o DNI.\n2. `GET /payer-lookup?document=...` — devuelve el nombre que ARCA tiene registrado.\n3. Le mostrás *\"¿Sos Juan Pérez?\"* y confirma.\n4. `POST /payment-request` — recién ahí creás el cobro, con el documento ya validado.\n\nDistinguí los dos casos en que no hay nombre, porque piden decisiones opuestas:\n\n| Respuesta | Significa | Qué conviene hacer |\n| --------- | --------- | ------------------ |\n| `200` con `name: null` | ARCA respondió y no hay titular para ese documento | Probablemente un error de tipeo: pedile al pagador que lo corrija |\n| `503` | No pudimos consultar a ARCA | La identidad quedó sin verificar. Reintentá, o dejá seguir el pago sin validación |\n\nLa respuesta trae únicamente `name`, `taxId` y `taxIdType`.\n\nCada consulta descuenta de un cupo diario propio, separado del de creación de cobros. Un CUIL/CUIT cuesta 1 y un DNI cuesta 2, porque el DNI obliga a probar dos CUIL candidatos contra ARCA. Al agotarlo recibís un `429` con `availableAtUnixSeconds`.\n\n### Corregir un cobro ya creado\n\nSi el cobro se creó con el documento equivocado, `PATCH /payment-request/{referenceId}/customer` lo reasigna al pagador correcto sin cancelarlo. Solo aplica a cobros en modo `cuil` que todavía no recibieron pagos.\n\nMirá `cvuChanged` en la respuesta: si el documento nuevo colisionaba en el CVU anterior, el cobro se movió a otro y **tenés que avisarle al pagador el CVU nuevo**.\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 peticiones.","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/bulk":{"post":{"operationId":"postPaymentRequestBulk","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostPaymentRequestBulkResponseBody"}}}},"400":{"description":"Datos inválidos (estructura del lote: array vacío, más de 100 items, o campos de algún item fuera de contrato).","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"}}}},"422":{"description":"El lote tiene errores de validación. La respuesta incluye `errors: [{ index, referenceId, reason }]` con TODOS los items que fallaron. No se creó ningún cobro."},"429":{"description":"Demasiadas solicitudes — superaste el límite de peticiones.","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 lote de cobros (hasta 100) en una sola llamada, de forma atómica\n(all-or-nothing). Es CUIL-only: cada item requiere `customer.taxDocument` y\ntodos comparten el mismo CVU del lote. Antes de crear nada, se valida el lote\ncompleto; si algún item es inválido (referenceId duplicado o ya existente,\nCUIL sin candidato), se devuelve 422 con la lista COMPLETA de errores y no se\ncrea ningún cobro. El detalle de cada cobro se consulta con\nGET /payment-request/{referenceId}.","tags":["PaymentRequest"],"security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostPaymentRequestBulkRequestBody"}}}}}},"/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}/customer":{"patch":{"operationId":"patchPaymentRequestCustomer","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchPaymentRequestCustomerResponseBody"}}}},"400":{"description":"Datos inválidos (taxDocument con formato o dígito verificador incorrecto, nombre/email/teléfono fuera de contrato).","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, o la integración no tiene grupo de cobro.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"409":{"description":"No se puede cambiar el pagador. `data.reason`: `conciliation_type_not_cuil` (el cobro es modo CVU), `state_not_modifiable` (estado final), `payment_already_received` (ya recibió plata), `no_collision_free_account` (ningún CVU libre para ese documento), `missing_notification_contact` (el pagador nuevo no tiene el contacto que requieren los recordatorios), `incomplete_payment_request_data` (el cobro no tiene pagador asociado) o `concurrent_modification` (alguien lo modificó en paralelo: releé y reintentá).","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":"Corrige los datos del pagador de un cobro abierto creado con\n`conciliationType: 'cuil'` —típicamente cuando el CUIL/DNI enviado estaba mal—.\nEl cuerpo es plano y todos los campos son opcionales salvo `taxDocument`: lo que\nno envíes queda como estaba.\n\nReevalúa la asignación de CVU. Si el documento nuevo no colisiona en el CVU\nactual, el cobro lo conserva; si colisiona, se mueve a otro y la respuesta trae\n`cvuChanged: true` con el CVU nuevo —avisale al pagador—. Si ningún CVU puede\nalojar el documento nuevo, no se cambia nada y se devuelve 409.\n\n`name`, `phoneNumber` y `email` se aplican al perfil del pagador, que es por\npersona y **por comercio**, no por cobro ni por integración: ese registro lo\ncomparten todos los cobros de esa persona en el comercio —los de esta\nintegración, los de las otras integraciones del mismo comercio y los que el\ncomercio administra desde la app—. Todos quedan actualizados\n(`profileUpdated` lo indica). Si sólo querés corregir el documento, no mandes\n`name`: un `name` enviado pisa el nombre que ese pagador ya tenía.","tags":["PaymentRequest"],"security":[{"bearer":[]}],"parameters":[{"description":"El identificador único del cobro cuyo pagador se corrige.","in":"path","name":"referenceId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchPaymentRequestCustomerRequestBody"}}}}}},"/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"}}]}},"/payer-lookup":{"get":{"operationId":"getPayerLookup","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPayerLookupResponseBody"}}}},"400":{"description":"El `document` no tiene formato de CUIL/CUIT (11 dígitos) ni de DNI (7-8 dígitos). No se consultó ARCA ni se consumió cupo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"403":{"description":"Invalid or expired token, or the account is not authorized for this integration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}},"404":{"description":"Tu cuenta no está vinculada a esta integración.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"429":{"description":"Agotaste el cupo diario de consultas al padrón. Se renueva a las 00:00 (hora Argentina).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"503":{"description":"No se pudo consultar el padrón de ARCA (o el servicio de cupos está degradado). La identidad del pagador NO fue verificada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}}},"description":"Devuelve el nombre que ARCA tiene registrado para un documento, para que\npuedas confirmarlo con el pagador (\"¿Sos Juan Pérez?\") antes de crear el cobro.\n\nEstá pensado para validar el documento ANTES de cobrar: si el pagador se\nequivoca al tipear, te enterás acá y no después de haber creado el cobro con\nun documento incorrecto.\n\nLa respuesta es el mínimo indispensable —`name`, `taxId` y `taxIdType`—;\nnunca devuelve domicilio ni datos fiscales.\n\nDistinguí los dos \"no hay nombre\": un **200** con `name: null` significa que\nARCA respondió y no hay titular para ese documento (probablemente un error\nde tipeo, conviene que el pagador lo corrija). Un **503** significa que no\npudimos consultar a ARCA: la identidad quedó sin verificar y vos decidís si\nreintentar o dejar seguir el pago sin validación.\n\nConsumo: cada consulta descuenta de un cupo diario propio (separado del de\ncreación de cobros). Un DNI cuesta 2 y un CUIL/CUIT cuesta 1, porque el DNI\nobliga a probar dos CUIL candidatos contra ARCA.","tags":["PayerLookup"],"security":[{"bearer":[]}],"parameters":[{"description":"CUIL/CUIT (11 dígitos) o DNI (7-8 dígitos) del pagador.","in":"query","name":"document","required":true,"schema":{"type":"string"}}]}},"/my-integration/tenant":{"put":{"operationId":"putTenant","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutTenantResponseBody"}}}},"400":{"description":"Invalid data. The tenantKey field is required and cannot be empty.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"},"examples":{"Example 1":{}}}}},"403":{"description":"Invalid or expired token, or the account is not authorized for this integration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}},"404":{"description":"The specified tenant does not exist, was deleted, or does not belong to your integration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChytaError"}}}}},"description":"Binds the authenticated user's commerce account to an integration tenant\nidentified by `tenantKey`. The tenant must exist and belong to the same\nintegration client as the token.\n\nThe operation is idempotent: calling it repeatedly with the same `tenantKey`\nreturns 200 with no further changes. To switch tenants, send a different\n`tenantKey` — the FK is updated.\n\n`userId` and `integrationClientId` are derived exclusively from the token\nheaders (anti-IDOR): they are never accepted from the body or the path.","tags":["Tenant"],"security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutTenantRequestBody"}}}}}}},"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"}]}