@arkaxapp/payments-js

SDK oficial, tipado y sin dependencias para integrar el checkout alojado de Arkax Payments mediante un iframe embebido o un modal.

La API key permanece siempre en el servidor del comercio. El navegador recibe únicamente el client_secret efímero devuelto al crear una sesión de pago.

Instalación

npm install @arkaxapp/payments-js

Antes de montar el checkout

Crea la sesión desde tu backend. Nunca expongas ARKAX_API_KEY en el navegador:

const response = await fetch("https://checkout.arkax.app/v1/payment-sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARKAX_API_KEY}`,
    "Idempotency-Key": order.id,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 20100,
    currency: "484",
    reference: order.id,
    metadata: {
      customer_id: customer.id,
      internal_order_id: order.id,
    },
    customer: {
      email: customer.email,
      first_name: customer.firstName,
      last_name: customer.lastName,
    },
    return_url: "https://comercio.example/pago/resultado",
    allowed_origin: "https://comercio.example",
  }),
});

const session = await response.json();

Los importes de la API usan unidades menores: 20100 representa MXN 201.00.

Modo prueba

Usa el mismo baseUrl de producción con una API key akx_test_... al crear la sesión. Arkax selecciona automáticamente el simulador; nunca contacta al procesador ni mueve dinero. Los pagos devuelven livemode: false y permanecen aislados de los recursos creados con akx_live_....

| Tarjeta | Resultado | | --- | --- | | 4242424242424242 | Aprobada | | 4000000000000002 | Rechazada | | 4000000000009995 | Fondos insuficientes | | 4000000000003220 | 3DS | | 4000000000000000 | unknown |

Usa cualquier fecha futura y CVV de tres dígitos.

metadata es un objeto JSON opcional que Arkax conserva en el pago y entrega mediante la API autenticada y los webhooks firmados. Admite hasta 50 claves y 8 KB; no se muestra al pagador.

Parámetros de la sesión

| Campo | Tipo | Requerido | Validación | | --- | --- | --- | --- | | amount | integer | Sí | Centavos; actualmente MXN 20000–600000. | | currency | string | No | Tres dígitos; default "484". | | reference | string | Sí | 3–30 caracteres y única por intento. Usa metadata para IDs internos más largos. | | metadata | Record<string, JSONValue> | No | 50 claves y 8 KB máximo. | | customer.email | string | Sí | Email válido. | | customer.first_name | string | Sí | 1–80 caracteres. | | customer.last_name | string | Sí | 1–80 caracteres. | | customer.phone | string | No | 7–15 dígitos, con + inicial opcional. | | return_url | string URL | Sí | HTTPS de retorno. | | allowed_origin | string origin | Sí | Origen registrado exacto, sin path. | | expires_in | integer | No | 300–86400 segundos; default 1800. |

Todas las mutaciones requieren un Idempotency-Key no vacío de hasta 128 caracteres. Reutiliza la misma clave únicamente para reintentar el mismo body.

La respuesta contiene { id, object, client_secret, checkout_url, expires_at, payment }. Conserva payment.id en tu backend y confirma su estado con GET /v1/payments/{paymentId} o un webhook firmado. Después del intento, payment.card_brand y payment.card_last_four permiten conciliar la tarjeta sin exponer el PAN completo ni el CVV.

Checkout embebido

import { mount } from "@arkaxapp/payments-js";

const checkout = mount({
  container: "#arkax-checkout",
  baseUrl: "https://checkout.arkax.app",
  clientSecret: session.client_secret,
  onReady() {
    console.log("Checkout listo");
  },
  onResult(payment) {
    console.log(payment.id, payment.status);
  },
  onError(error) {
    console.error(error.message);
  },
});

// Cuando ya no lo necesites:
checkout.destroy();

Modal

import { open } from "@arkaxapp/payments-js";

const modal = open({
  baseUrl: "https://checkout.arkax.app",
  clientSecret: session.client_secret,
  onResult(payment) {
    if (payment.status === "approved") {
      modal.close();
      window.location.assign("/pedido/confirmado");
    }
  },
});

Opciones

• clientSecret: secreto público y efímero de la sesión.
• baseUrl: https://checkout.arkax.app en producción.
• container: selector CSS o elemento HTML; requerido únicamente por mount.
• title: título accesible del checkout.
• height: altura inicial del iframe; se actualiza automáticamente.
• borderRadius: radio visual del iframe.
• closeOnEscape: permite cerrar el modal con Escape; predeterminado true.
• closeOnBackdrop: permite cerrar al pulsar fuera del modal; predeterminado true.
• onReady, onResult, onError, onClose: callbacks del ciclo de vida.

El SDK valida event.origin y event.source antes de aceptar mensajes. Confirma el resultado definitivo desde tu backend mediante GET /v1/payments/{paymentId} o webhooks firmados.

Referencia completa de parámetros, estados, links, refunds, reversals, webhooks y errores: checkout.arkax.app/docs y OpenAPI 1.3.1.