Widget de checkout

Cómo cobrar en tu checkout con el widget embebible de Chytapay y sus claves de Sandbox y Producción.

Al terminar, tu comprador paga por transferencia sin salir de tu sitio. Necesitás el id_token de una cuenta de comercio conectada y acceso al Portal como admin de la integración.

Para conocer el widget antes de integrarlo, visitá la página del widget.

Cómo funciona

Qué ve el pagador

1. Ingresa su documento (CUIL, CUIT o DNI), que es por lo que se concilia.
2. Ve el nombre que ARCA tiene para ese documento: tiene que transferir desde una cuenta suya. Es informativo: si ARCA no responde, sigue.
3. Recibe el CVU, asignado recién ahora, con botón para copiar y cuenta regresiva.
4. Transfiere desde su cuenta.
5. Ve el resultado: con el total, onSuccess. Con menos, el cobro queda en partial_payment y el widget espera el resto.

1Generá la clave publicable

Las claves son de la integración, no de la cuenta de comercio:

Una pk sirve para todas las cuentas de comercio de la integración.

2Creá el cobro de checkout

Sirve cuando no conocés al pagador de antemano, como en un ecommerce. En tu backend, creá el cobro con 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": "pedido-1001",
    "amount": 15000,
    "description": "Compra en la tienda",
    "expiresInMinutes": 15
  }'

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

Responde 201 con el cobro en pending. El paymentRequestId es el paymentId que le pasás al widget.

Mandar customer, dueDates, surcharge, conciliationType o un campo de aviso (sendWhatsappNotification, sendEmailNotification, sendWhatsappPaymentConfirmation, reminderNotificationDate, deferredInitialNotificationDate) da 400 con el nombre del campo.

• Concilia siempre por CUIL.
• La respuesta no trae CVU ni bankAccountInfo: se asignan cuando el pagador se identifica.
• expiresInMinutes se vuelve un vencimiento con hora en dueDates. Al cumplirse, el cobro pasa a overdue y llega payment_request.expired.

Como en standard, un referenceId repetido da 409 ReferenceIdAlreadyExists.

3Instalá el SDK

Por CDN, el SDK queda en window.ChytaPay:

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

Con defer, el navegador baja el SDK sin frenar el dibujado de tu página y lo ejecuta al terminar de leer el HTML, antes de DOMContentLoaded. Un script en línea que corra antes no encuentra ChytaPay: llamá a ChytaPay.init desde un manejador de DOMContentLoaded, como en el paso siguiente.

Por npm, con un bundler:

npm i @chytapay/integration-widget

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

Con @1 recibís las versiones nuevas de la serie 1; para controlar cada una, fijá la exacta (@1.5.0). Sin versión, unpkg sirve la última. Ver el changelog del SDK, también incluido en el paquete.

4Abrí el checkout

En tu página, inicializá el SDK con tu pk y abrí el checkout con el paymentRequestId:

// 1. Una sola vez, cuando el SDK ya cargó. El prefijo de la pk elige las URLs: pk_live para Producción, pk_test para Sandbox.
document.addEventListener('DOMContentLoaded', () => {
  ChytaPay.init({ pk: PK_DE_TU_INTEGRACION });
});

// 2. Llamala cuando el comprador confirma, con el cobro que creó tu backend.
function abrirCheckout(paymentRequestId) {
  return ChytaPay.checkout({
    paymentId: paymentRequestId,
    onSuccess: (paymentId) => {
      // Entró el monto total: confirmá la compra en tu UI.
    },
    onError: (error) => {
      // Venció o falló sin arreglo: ofrecé generar un cobro nuevo.
    },
    onCancel: () => {
      // El comprador cerró el checkout sin pagar, o el cobro se canceló.
    },
  });
}

// 3. Opcional: el handle que devuelve cierra el checkout desde tu código. No dispara onCancel.
//    const handle = abrirCheckout(paymentRequestId);
//    handle.close();

Se abre un modal que se cierra con Escape, clic en el fondo o la X. Para embeberlo, pasá container.

onSuccess es para tu interfaz. La confirmación del pago es el evento payment_request.payment_received en tu backend, con su firma verificada.

Si tu tienda usa CSP

Si tu página manda una Content Security Policy, permití estos orígenes. Sin ellos, el navegador bloquea el SDK, el checkout o el botón de Mercado Pago.

Si tu CSP no define frame-src, el navegador usa child-src y, si tampoco está, default-src. Si cambiás apiBaseUrl o iframeUrl en init, permití esos orígenes en lugar de los de producción.

En Sandbox permití https://integration-api.test.chytapay.com.ar en connect-src y https://widget-test.chytapay.com.ar en frame-src e img-src (más data:), aunque no cambies las URLs en init.

El botón abre la app desde un frame oculto de tu página. Por eso mercadopago: e intent: van en frame-src: sin ellos, el pagador ve el aviso de que la app no abrió y el CVU para copiar.

Probalo en Sandbox

pk_test_ elige https://integration-api.test.chytapay.com.ar y https://widget-test.chytapay.com.ar/checkout/; pk_live_, los hosts de Producción.

Cuando algo falla

También dispara onError si el cobro vence (overdue, se cumplió expiresInMinutes) o si al abrir dice "No se pudo cargar el pago.": paymentId inexistente o de otra integración (404), pk inexistente (401) u origen fuera de los dominios autorizados (403). partial_overdue no lo dispara: el widget sigue esperando.

Referencia rápida

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

Seguí por acá