Create charges

How to create charges one by one or in bulk, with due dates, surcharge, states, payer notifications and safe retries.

This page covers how to create, track and cancel charges, one at a time or up to 100 per call. You need a connected merchant account and its id_token in Authorization: Bearer: see Connect merchant accounts.

1Create a charge

You identify each charge with your own referenceId, which comes back in every response and event.

From your backend, create the charge in Sandbox:

curl -X POST https://integration-api.test.chytapay.com.ar/payment-request \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "invoice-1001",
    "amount": 25000,
    "description": "October installment",
    "dueDates": ["2026-10-15", "2026-10-25"],
    "surcharge": { "type": "percentage", "value": 10 },
    "conciliationType": "cuil",
    "sendWhatsappNotification": false,
    "sendEmailNotification": true,
    "customer": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "taxDocument": "20000000001"
    },
    "metadata": { "order": "1001" }
  }'

const BASE = 'https://integration-api.test.chytapay.com.ar';

const res = await fetch(`${BASE}/payment-request`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${idToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    referenceId: 'invoice-1001',
    amount: 25000,
    description: 'October installment',
    dueDates: ['2026-10-15', '2026-10-25'],
    surcharge: { type: 'percentage', value: 10 },
    conciliationType: 'cuil',
    sendWhatsappNotification: false,
    sendEmailNotification: true,
    customer: {
      name: 'Jane Doe',
      email: '[email protected]',
      taxDocument: '20000000001',
    },
    metadata: { order: '1001' },
  }),
});
const charge = await res.json(); // 201

import requests

BASE = "https://integration-api.test.chytapay.com.ar"

res = requests.post(
    f"{BASE}/payment-request",
    headers={"Authorization": f"Bearer {id_token}"},
    json={
        "referenceId": "invoice-1001",
        "amount": 25000,
        "description": "October installment",
        "dueDates": ["2026-10-15", "2026-10-25"],
        "surcharge": {"type": "percentage", "value": 10},
        "conciliationType": "cuil",
        "sendWhatsappNotification": False,
        "sendEmailNotification": True,
        "customer": {
            "name": "Jane Doe",
            "email": "[email protected]",
            "taxDocument": "20000000001",
        },
        "metadata": {"order": "1001"},
    },
)
charge = res.json()  # 201

{
  "type": "standard",
  "paymentRequestId": "<charge uuid>",
  "referenceId": "invoice-1001",
  "amount": 25000,
  "description": "October installment",
  "dueDates": ["2026-10-15", "2026-10-25"],
  "state": "pending",
  "surcharge": { "type": "percentage", "value": 10 },
  "calculatedAmounts": [
    { "dueDate": "2026-10-15", "amount": 25000, "isOriginalAmount": true },
    { "dueDate": "2026-10-25", "amount": 27500, "surchargeApplied": 2500 }
  ],
  "sendWhatsappNotification": false,
  "sendEmailNotification": true,
  "metadata": { "order": "1001" },
  "customer": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "taxDocument": "20000000001"
  },
  "CVU": "<22-digit CVU>",
  "bankAccountInfo": {
    "accountHolderName": "<merchant account holder>",
    "accountHolderTaxId": "<holder's CUIT>",
    "bankName": "<bank>"
  }
}

Use dates within the next 35 days. The example reconciles by CUIL, the recommended mode: first, validate the document.

What it returns

201 with paymentRequestId, state (pending, or draft without an amount), CVU and bankAccountInfo (where the payer transfers) and, with an amount and 2 dates, calculatedAmounts (each due date with surcharge). It also returns what you sent, except customer.taxDocument in CVU mode.

2Retrieve a charge

Request it with GET /payment-request/{referenceId}:

curl https://integration-api.test.chytapay.com.ar/payment-request/invoice-1001 \
  -H "Authorization: Bearer $ID_TOKEN"

Same shape as the create response, with an updated state. If it doesn't exist for the merchant account, 404. To list the charges created in a range, use GET /payment-request?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD, both dates optional.

3Duplicates and retries

There's no idempotency key: the referenceId is unique per integration and merchant account, canceled charges included. Repeating it returns 409 without the existing charge:

{
  "error": "ReferenceIdAlreadyExists",
  "message": "The provided reference ID already exists for this client",
  "referenceId": "invoice-1001"
}

Use your entity's id (invoice, order, installment), not one per attempt. If a create times out:

If the charge from the GET doesn't match what you meant to create, you reused an old referenceId by mistake.

4Cancel a charge

Call POST /payment-request/{referenceId}/cancel with no body:

curl -X POST https://integration-api.test.chytapay.com.ar/payment-request/invoice-1001/cancel \
  -H "Authorization: Bearer $ID_TOKEN"

{ "referenceId": "invoice-1001", "state": "canceled" }

Only charges in draft or pending with no payments can be canceled: otherwise, 409 PaymentRequestCannotBeCanceled. It generates no event: the 200 response is the confirmation. If a transfer comes in later, you get payment.unmatched with reason: "canceled", which is opt-in.

Fields

The fields of a standard charge. Omit the optional fields you don't use; don't send null.

Outside these rules, 400 with the details: see the errors.

Due dates and surcharge

dueDates takes 1 or 2 dates, after today and no more than 35 days out:

With a time, the charge is short-lived. With 2 dates, the second element of dueDates carries surcharge, required with an amount (Chytapay doesn't reorder them). The payer owes amount up to the first due date and amount plus the surcharge from the day after.

type is percentage (0 to 100, on the amount), fixed (pesos, up to 200,000,000) or none (value: 0). With amount: 25000 and { "type": "percentage", "value": 10 }, the second due date is 27,500, in calculatedAmounts.

Short-lived charges

For reservations, tickets or any charge that has to close at a set time, send the due date with a time: "2026-10-15T18:30". It changes several things compared to a date alone:

If the charge is paid in the widget, the checkout charge expires between 3 and 60 minutes.

Draft without an amount

Without amount, the charge starts in draft, with one due date, no surcharge and no notifications (flags only false, notification dates not allowed). Complete it with PATCH /payment-request/{referenceId}:

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

{
  "referenceId": "invoice-1002",
  "previousAmount": null,
  "amount": 18000,
  "description": "Enrollment",
  "state": "pending",
  "dueDates": ["2026-10-20"]
}

• Only in draft with no payments; otherwise, 409.
• It moves to pending. A draft never sends notifications, not even after the PATCH.
• If you don't complete it, Chytapay discards it after a few hours.

States

Create, GET, cancel, PATCH and bulk return state, and payment_request.* events return stateType. There's no PAID: it's total_payment.

With 2 dates, the charge stays open until the second due date. A day-only date expires at 00:00 Argentina time, with no event; one with a time expires at that minute with payment_request.expired. See the events in Webhooks.

Payer notifications

A payer notification is a WhatsApp or email from Chytapay to the payer (not an event to your backend). Channels are chosen in the fields, only with an amount. After a partial payment, reminders show the balance; paid, past due or canceled, they stop.

When each notification goes out

Reminders go out at 10 a.m. Argentina time.

Payment confirmation

The WhatsApp payment received notification is controlled by sendWhatsappPaymentConfirmation, not sendWhatsappNotification:

In CUIL mode the payer can request it with "Recibir confirmación de pago" (Receive payment confirmation), and false doesn't turn that off.

Create charges in bulk

POST /payment-request/bulk creates 1 to 100 charges, all or nothing. Each item is a single charge, except that:

• It always reconciles by CUIL: customer.taxDocument is required.
• The same document twice in a batch returns 422.
• A date with a time returns 400.
• conciliationType, type, expiresInMinutes and webhookUrl aren't allowed: events go to the integration's URL.

From your backend, send the batch:

curl -X POST https://integration-api.test.chytapay.com.ar/payment-request/bulk \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentRequests": [
      {
        "referenceId": "installment-2026-10-001",
        "amount": 12000,
        "description": "October installment",
        "dueDates": ["2026-10-15"],
        "sendWhatsappNotification": false,
        "sendEmailNotification": false,
        "customer": { "name": "Jane Doe", "taxDocument": "20000000001" }
      },
      {
        "referenceId": "installment-2026-10-002",
        "amount": 12000,
        "description": "October installment",
        "dueDates": ["2026-10-15"],
        "sendWhatsappNotification": false,
        "sendEmailNotification": false,
        "customer": { "name": "John Smith", "taxDocument": "30405060" }
      }
    ]
  }'

{
  "batchId": "<batch uuid>",
  "total": 2,
  "created": 2,
  "sharedCvu": "<22-digit CVU>",
  "accountInfo": {
    "accountHolderName": "<merchant account holder>",
    "accountHolderTaxId": "<holder's CUIT>",
    "bankName": "<bank>"
  },
  "paymentRequests": [
    { "referenceId": "installment-2026-10-001", "state": "pending" },
    { "referenceId": "installment-2026-10-002", "state": "pending" }
  ]
}

paymentRequests follows the request order; retrieve details with GET.

Checkout charge

A type: "checkout" charge is paid from the widget: see the checkout charge.

Next steps