Conciliación

Cómo Chytapay imputa cada transferencia a su cobro: por CUIL, el camino recomendado, o por CVU.

Al terminar vas a saber cómo identificar al pagador, cómo Chytapay imputa cada transferencia a su cobro y qué hacer con un pago que queda sin imputar. Necesitás una cuenta de comercio conectada y su id_token: consultá Conectar comercios.

Conciliá por CUIL

Conciliar es imputar una transferencia a su cobro. Recomendamos el CUIL de quien paga: el pago se imputa por quién transfiere, así no termina en el cobro de otro pagador, y es el modo de checkout y de los cobros por lote.

Los dos modos

Se elige por cobro con conciliationType en POST /payment-request. Si no lo mandás, la API usa cvu.

Checkout y los cobros por lote son siempre cuil y no llevan conciliationType.

Usá cuil siempre que puedas pedir CUIL, CUIT o DNI (cuotas, facturas, reservas), y cvu solo si no es viable.

1Validá al pagador antes de crear el cobro

Un documento mal tipeado deja el pago sin imputar. GET /payer-lookup devuelve el nombre registrado en ARCA para confirmarlo. Hacelo siempre:

En tu backend, consultá el documento en Sandbox:

curl "https://integration-api.test.chytapay.com.ar/payer-lookup?document=20000000001" \
  -H "Authorization: Bearer $ID_TOKEN"

{ "name": null, "taxId": null, "taxIdType": null }

Si ARCA encuentra al titular, trae name (nombre y apellido, o razón social), taxId (el CUIL o CUIT) y taxIdType (CUIL o CUIT). Nunca trae domicilio ni datos fiscales. Los dos casos sin nombre piden decisiones opuestas:

Tiene su propia cuota diaria. Consultá la cuota, el 429 y los demás errores en Operación y errores.

2Creá el cobro por CUIL

Mandá conciliationType: "cuil" y el documento en customer.taxDocument. El resto es igual a cualquier cobro: consultá los campos en Crear cobros.

La respuesta trae el CVU al que transfiere el pagador y customer.taxDocument tal como lo mandaste. Sobre customer.taxDocument:

• CUIL o CUIT de 11 dígitos, o DNI de 7 u 8. Un dígito verificador mal da 400.
• Preferí el CUIL o CUIT: identifica a una sola persona. Con un DNI, el pago se imputa si el CUIL de quien transfiere corresponde a ese DNI.
• Es el del titular de la cuenta de origen: si paga otra persona o una empresa, cargá su CUIL o CUIT.

Un pagador con varios cobros abiertos recibe un CVU distinto en cada uno, así cada pago va a su cobro.

3Recibí los datos del pagador

payment_request.payment_received trae la cuenta de origen de la transferencia:

Cada campo se omite si la transferencia no lo informa. reconciledPayerCuil también se omite si el CUIT de origen es el de la cuenta de comercio: para probar, usá un CUIL de pagador distinto.

Checkout: el pagador se identifica en el widget

Un cobro type: "checkout" nace sin CVU (el create no trae CVU ni bankAccountInfo): lo recibe cuando el pagador ingresa su documento en el widget, y desde ahí es un cobro por CUIL más. Consultá el cobro de checkout.

Cobros por lote: enviá el documento de cada pagador

POST /payment-request/bulk siempre concilia por CUIL: cada ítem necesita customer.taxDocument, y el mismo documento dos veces en el lote da 422. Antes de mandarlo, validá cada documento. Consultá cómo crear cobros por lote.

Corregí el pagador de un cobro creado

PATCH /payment-request/{referenceId}/customer reasigna el cobro al pagador correcto sin cancelarlo. Solo si el cobro es conciliationType: "cuil", está en draft o pending y no recibió pagos.

El cuerpo es plano, con los campos del customer del create: taxDocument obligatorio; name, email y phoneNumber opcionales (lo que no mandes queda igual).

En tu backend, corregí el documento:

curl -X PATCH https://integration-api.test.chytapay.com.ar/payment-request/factura-1001/customer \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "taxDocument": "27000000006" }'

Si la plata ya había entrado sin imputar por no_cuil_match o no_pending, corregir el pagador con el documento de quien transfirió la imputa al cobro y llega payment_request.payment_received. Para eso la transferencia tiene que haber llegado al CVU que el cobro tiene después de la corrección (si cvuChanged es true, la del CVU anterior no se toma), después de crear el cobro y dentro de su plazo. Además tiene que ser la única de ese CUIL sin imputar, y el CUIL no puede ser de otro pagador con un cobro abierto en el comercio. Si falta alguna condición, la gestión va por soporte de Chytapay.

Si no se puede corregir, da 409 con el motivo en data.reason; un documento inválido da 400 y un referenceId inexistente, 404. Consultá los motivos del 409.

Gestioná un pago sin imputar

Un pago sin imputar se acredita en la cuenta del comercio, sin cambiar un cobro. payment.unmatched informa el motivo. El comercio puede asignarlo desde su cuenta a un cobro, aunque venga de otro CVU suyo: el cobro cambia de estado (incluso si estaba vencido) y llega payment_request.payment_received.

Por API, corregir el pagador puede imputar un no_cuil_match o no_pending con las condiciones indicadas. También puede hacerlo el pagador con Pagar con otro DNI si hay una sola transferencia de ese CUIL, al CVU del cobro y dentro de su plazo. No vuelvas a cobrar ni devuelvas de forma automática: consultá el cobro antes. Si no se puede imputar, contactá a soporte.

Si paga un tercero

Si transfiere un familiar, un socio o la empresa del pagador, el CUIL de origen no coincide y el pago queda sin imputar (no_cuil_match). El cobro sigue pendiente.

Para evitarlo, cargá el documento del titular de la cuenta desde la que va a transferir, o corregí el pagador antes del pago. El evento trae amount, payerCuil y payerName de quien transfirió. Si la plata ya entró, corregir el pagador con el documento de quien transfirió la imputa al cobro, con las condiciones que se explican ahí.

Si transfiere el propio comercio

Para probar el flujo, transferí desde otro CUIT. Según en qué CVU quede el cobro, una transferencia desde el CUIT del propio comercio puede tomarse como carga de saldo: no se imputa y no genera webhook.

Pagos tardíos

Un pago que llega después de que su cobro se cerró (pagado, vencido o cancelado) no se imputa a ese cobro:

• Si el CVU ya es de otro cobro en modo CVU: se imputa a ese cobro, aunque sea de otro pagador, y llega su payment_request.payment_received. Por CUIL no pasa.
• Si hay cobros por CUIL abiertos en ese CVU: se busca por el CUIL de quien transfiere.
• Si no hay a qué imputarlo: llega payment.unmatched. Si el cobro se cerró en las últimas 24 h, puede traer paymentRequest y reason expired, already_paid o canceled; en modo CUIL, solo si pagó el mismo pagador. Sin atribución: no_cuil_match si quedan cobros CUIL abiertos en ese CVU, no_pending si no hay ninguno, o ambiguous si hay varios candidatos. Ver los motivos. already_paid se atribuye por CVU (en modo CUIL, también por pagador), no por monto: no prueba que el pago sea de ese cobro.

Conciliación por CVU: limitaciones

El modo cvu no pide documento, pero tiene estas limitaciones. Si alguna te afecta, pasate a CUIL.

El CVU acredita a quien sea que pague

Mientras el cobro está abierto, Chytapay no mira quién transfiere.

El CVU de un cobro cerrado puede pasar a otro cobro

Pagado, vencido o cancelado el cobro, su CVU puede asignarse a otro. Una transferencia posterior se imputa al cobro nuevo, aunque sea de otro pagador: mostrá el CVU de cada cobro y no lo publiques como dato fijo.

Transferencias a un CVU guardado

Un pagador puede reusar el CVU guardado de una compra anterior. En modo CVU es un pago tardío: si el CVU ya es de otro cobro CVU abierto, ese figura pagado y el de quien pagó sigue pendiente. Para evitarlo, conciliá por CUIL y pedí que usen el CVU de cada cobro.

Si no hay un CVU disponible

La cantidad de CVUs por cuenta de comercio es limitada, y cada cobro en modo CVU ocupa uno exclusivo mientras está abierto. Sin uno disponible, el create y el bulk dan 400 InsufficientActiveAccountsError, también para cobros por CUIL: reintentá más tarde. Con muchos cobros CVU abiertos pasa antes, otra razón para preferir CUIL. Consultá el límite en Operación y errores.

Seguí por acá