Checkout widget

Embed the Chytapay checkout in your site: create the charge on your backend, install the SDK, and open the widget with your test or live publishable key.

By the end, your buyer pays by bank transfer without leaving your site. You need the id_token of a connected merchant account and Portal access as an integration admin.

To get to know the widget before integrating it, visit the widget page (in Spanish).

How it works

What the payer sees

1. Enters their document (CUIL, CUIT or DNI), which is what the charge reconciles by.
2. Sees the name ARCA has for that document: the transfer must come from an account in their name. It's informational: if ARCA doesn't respond, the flow continues.
3. Gets the CVU, assigned only now, with a copy button and a countdown.
4. Transfers from their account.
5. Sees the result: with the full amount, onSuccess. With less, the charge stays in partial_payment and the widget waits for the rest.

1Generate the publishable key

Keys belong to the integration, not to the merchant account:

One pk works for every merchant account and is all this guide needs. The sk is generated in the Portal, under Credenciales (Credentials), Widget de pago (Payment widget) section, with Generar clave secreta (Generate secret key). It's shown only once, and rotating it invalidates the previous one.

2Create the checkout charge

Use it when you don't know the payer in advance, as in ecommerce. On your backend, create the charge with type: "checkout":

curl -X POST https://integration-api.test.chytapay.com.ar/payment-request \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "checkout",
    "referenceId": "order-1001",
    "amount": 15000,
    "description": "Store purchase",
    "expiresInMinutes": 15
  }'

{
  "paymentRequestId": "00000000-0000-0000-0000-000000000000",
  "type": "checkout",
  "referenceId": "order-1001",
  "amount": 15000,
  "description": "Store purchase",
  "dueDates": ["2026-10-01T15:15:00Z"],
  "expiresInMinutes": 15,
  "state": "pending",
  "sendWhatsappNotification": false,
  "sendEmailNotification": false
}

You get a 201 with the charge in pending. The paymentRequestId is the paymentId you pass to the widget.

Sending customer, dueDates, surcharge, conciliationType or a payer notification field (sendWhatsappNotification, sendEmailNotification, sendWhatsappPaymentConfirmation, reminderNotificationDate, deferredInitialNotificationDate) returns 400 with the field name.

• Always reconciles by CUIL.
• The response has no CVU or bankAccountInfo: they're assigned when the payer identifies themselves.
• expiresInMinutes becomes a timestamped expiration in dueDates. When reached, the charge moves to overdue and payment_request.expired arrives.

As with standard, a repeated referenceId returns 409 ReferenceIdAlreadyExists.

3Install the SDK

From the CDN, the SDK is available as window.ChytaPay:

<script src="https://unpkg.com/@chytapay/integration-widget@1" defer></script>

defer lets the browser download the SDK without blocking your page from rendering, and runs it once the HTML is parsed, before DOMContentLoaded. An inline script placed above it won't find ChytaPay, so call ChytaPay.init from a DOMContentLoaded handler, as in the next step.

From npm, with a bundler:

npm i @chytapay/integration-widget

import { ChytaPay } from '@chytapay/integration-widget';

With @1 you get new 1.x releases; to control each one, pin the exact version (@1.0.0). Without a version, unpkg serves the latest. See the SDK changelog, also shipped in the package.

4Open the checkout

On your page, initialize the SDK with your pk and open the checkout with the paymentRequestId:

// 1. Once, after the SDK has loaded. The default URLs are the production ones.
document.addEventListener('DOMContentLoaded', () => {
  ChytaPay.init({ pk: YOUR_INTEGRATION_PK });
});

// 2. Call it when the buyer confirms, with the charge your backend created.
function openCheckout(paymentRequestId) {
  return ChytaPay.checkout({
    paymentId: paymentRequestId,
    onSuccess: (paymentId) => {
      // The full amount arrived: confirm the purchase in your UI.
    },
    onError: (error) => {
      // Expired or failed with no recovery: offer to create a new charge.
    },
    onCancel: () => {
      // The buyer closed the checkout without paying, or the charge was canceled.
    },
  });
}

// 3. Optional: the returned handle closes the checkout from your code. Doesn't fire onCancel.
//    const handle = openCheckout(paymentRequestId);
//    handle.close();

A modal opens and closes with Escape, a backdrop click or the X. To embed it, pass container.

onSuccess is for your UI. The payment confirmation is the payment_request.payment_received event on your backend, with its signature verified.

If your store uses CSP

If your page sends a Content Security Policy, allow these origins. Without them, the browser blocks the SDK, the checkout or the Mercado Pago button.

If your CSP doesn't set frame-src, the browser falls back to child-src, and then to default-src. If you change apiBaseUrl or iframeUrl in init, allow those origins instead of the production ones.

The button launches the app from a hidden frame on your page, which is why mercadopago: and intent: belong in frame-src. Without them, the payer sees the "app didn't open" notice, with the CVU ready to copy.

Try it in Sandbox

Leave iframeUrl at its default: the iframe doesn't call the API.

When something fails

It also fires onError if the charge expires (overdue, expiresInMinutes elapsed) or if it shows "No se pudo cargar el pago." (The payment couldn't be loaded.) on open: paymentId missing or from another integration (404), unknown pk (401) or origin outside the authorized domains (403). partial_overdue doesn't fire it: the widget keeps waiting.

Quick reference

ChytaPay.checkout({
  paymentId: paymentRequestId,
  onWalletOpen: ({ wallet, opened, os, browser, via }) => {
    // { wallet: 'mercadopago', opened: false, os: 'android', browser: 'firefox', via: 'sdk' }
  },
});

Next steps