Reconciliation

How Chytapay matches each transfer to its charge: by CUIL, the recommended path, or by CVU.

By the end you'll know how to identify the payer, how Chytapay matches each transfer to its charge and what to do with a payment that stays unmatched. You need a connected merchant account and its id_token: see Connect merchant accounts.

Reconcile by CUIL

Reconciling means matching a transfer to its charge. We recommend the payer's CUIL: the payment is matched by who sends it, so it never ends up on another payer's charge, and it's the mode checkout and bulk charges use.

The two modes

You pick it per charge with conciliationType on POST /payment-request. If you omit it, the API uses cvu.

Checkout and bulk charges are always cuil and don't take conciliationType.

Use cuil whenever you can ask for a CUIL, CUIT or DNI (installments, invoices, bookings), and cvu only when you can't.

1Validate the payer before creating the charge

A mistyped ID number leaves the payment unmatched. GET /payer-lookup returns the name ARCA has on record so you can confirm it. Always do it:

In your backend, query the ID number in Sandbox:

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

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

If ARCA finds the holder, you get name (full or company name), taxId (the CUIL or CUIT) and taxIdType (CUIL or CUIT). Never an address or tax details. The two no-name cases call for opposite decisions:

It has its own daily quota. See the quota, the 429 and the other errors in Operations and errors.

2Create the charge by CUIL

Send conciliationType: "cuil" and the ID number in customer.taxDocument. Everything else is like any charge: see the fields in Create charges.

The response includes the CVU the payer transfers to and customer.taxDocument as you sent it. About customer.taxDocument:

• 11-digit CUIL or CUIT, or 7- or 8-digit DNI. A wrong check digit returns 400.
• Prefer the CUIL or CUIT: it identifies a single person. With a DNI, the payment is matched if the sender's CUIL belongs to that DNI.
• It's the sending account holder's: if another person or a company pays, enter their CUIL or CUIT.

A payer with several open charges gets a different CVU on each, so each payment goes to its own charge.

3Receive the payer data

payment_request.payment_received carries the transfer's sending account:

Each field is omitted if the transfer doesn't report it. reconciledPayerCuil is also omitted when the sending CUIT is the merchant account's: to test, use a different payer CUIL.

Checkout: the payer identifies themselves in the widget

A type: "checkout" charge starts without a CVU (create returns no CVU or bankAccountInfo): it gets one when the payer enters their ID number in the widget, and from then on it's a regular CUIL charge. See the checkout charge.

Bulk charges: send each payer's ID number

POST /payment-request/bulk always reconciles by CUIL: each item needs customer.taxDocument, and the same ID number twice in the batch returns 422. Before sending it, validate each ID number. See how to create charges in bulk.

Correct the payer of an existing charge

PATCH /payment-request/{referenceId}/customer reassigns the charge to the right payer without canceling it. Only if the charge is conciliationType: "cuil", in draft or pending, and hasn't received payments.

The body is flat, with the create's customer fields: taxDocument required; name, email and phoneNumber optional (what you don't send stays).

In your backend, correct the ID number:

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

If it can't be corrected, you get 409 with the reason in data.reason; an invalid ID number returns 400 and an unknown referenceId, 404. See the 409 reasons.

Handle an unmatched payment

An unmatched payment is still credited to the merchant account, but no charge changes state. You find out through payment.unmatched, which carries the cause in reason.

Through the API, no later change matches that money. Don't expect a payment_request.payment_received, and don't charge again or refund automatically. Handling that payment goes through Chytapay support.

If a third party pays

If a relative, a partner or the payer's company sends the money, the sending CUIL doesn't match and the payment is unmatched (no_cuil_match). The charge stays pending.

To avoid it, enter the ID number of the account the payer will transfer from, or correct the payer before they pay. The event carries the sender's amount, payerCuil and payerName. Correcting the payer afterwards doesn't match that money.

Late payments

A payment that arrives after its charge closed (paid, expired or canceled) isn't matched to that charge:

• If the CVU now belongs to another CVU-mode charge: it's matched to that charge, even another payer's, and its payment_request.payment_received arrives. This doesn't happen with CUIL.
• If there are open CUIL charges on that CVU: it's matched by the sender's CUIL.
• If there is nothing to match it to: payment.unmatched arrives, in both modes. If the charge closed within the previous 24 h, it carries paymentRequest and reason expired, already_paid or canceled. Otherwise, no_pending, without paymentRequest.

CVU reconciliation: limitations

cvu mode needs no ID number, but it has these limitations. If any affects you, switch to CUIL.

The CVU credits whoever pays

While the charge is open, Chytapay doesn't check who transfers.

A closed charge's CVU can go to another charge

Once the charge is paid, expired or canceled, its CVU can be assigned to another one. A later transfer is matched to the new charge, even another payer's: show each charge's CVU and don't publish it as a fixed detail.

Transfers to a saved CVU

A payer may reuse a CVU saved from a previous purchase. In CVU mode that's a late payment: if the CVU now belongs to another open CVU charge, that one shows as paid and the sender's stays pending. To avoid it, reconcile by CUIL and ask payers to use each charge's CVU.

If no CVU is available

The number of CVUs per merchant account is limited, and each CVU-mode charge takes an exclusive one while it's open. With none available, create and bulk return 400 InsufficientActiveAccountsError, for CUIL charges too: retry later. With many open CVU charges it happens sooner, one more reason to prefer CUIL. See the limit in Operations and errors.

Next steps