Documentación para comercios

Integra pagos sin adivinar parámetros.

Crea la sesión desde tu servidor, monta el checkout seguro y confirma el resultado con la API o un webhook firmado.

Antes de comenzar

Usa siempre https://checkout.arkax.app: una clave akx_test_... activa el simulador y akx_live_... el procesador real.
La API key vive únicamente en tu backend. El navegador recibe solo client_secret.
amount es un integer en centavos: 20100 significa MXN 201.00.
Todas las mutaciones usan Idempotency-Key, máximo 128 caracteres.

Modo prueba

Integra sin mover dinero

Genera una API key TEST y webhooks TEST desde el portal. Pagos, referencias, links, idempotencia, eventos y secretos están aislados de LIVE. Las respuestas incluyen livemode: false.

Tarjeta	Escenario	Eventos
`4242 4242 4242 4242`	Aprobada 2D	payment.succeeded
`4000 0000 0000 0002`	Rechazo genérico	payment.failed
`4000 0000 0000 9995`	Fondos insuficientes	payment.failed
`4000 0000 0000 3220`	Challenge 3DS	payment.requires_action → payment.succeeded
`4000 0000 0000 0000`	Timeout ambiguo	payment.unknown

Usa cualquier nombre, una fecha futura en formato MM/AA y cualquier CVV de tres dígitos. En el portal también puedes enviar un payment.succeeded sintético a un endpoint TEST para validar firma y entrega antes de crear una sesión.

1 · Backend

Crea una sesión

const response = await fetch("https://checkout.arkax.app/v1/payment-sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARKAX_API_KEY}`,
    "Idempotency-Key": "order-1842-create-session",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amount: 20100, // MXN 201.00
    currency: "484",
    reference: "ORDER-2026-1842-A1",
    metadata: {
      customer_id: "cus_8421",
      internal_order_id: "1842"
    },
    customer: {
      email: "ada@example.com",
      first_name: "Ada",
      last_name: "Lovelace",
      phone: "+525512345678"
    },
    return_url: "https://tienda.example/pagos/resultado",
    allowed_origin: "https://tienda.example",
    expires_in: 1800
  })
});

if (!response.ok) throw new Error(await response.text());
const session = await response.json();

Referencia

Parámetros de `POST /v1/payment-sessions`

Scope requerido: payment_sessions:create. La referencia debe ser única por intento, tener máximo 30 caracteres por límite del procesador y el origen debe estar autorizado en el tenant.

Parámetro	Tipo	Requerido	Reglas
`amount`	integer	Sí	Centavos. MXN: 20000–600000; 20100 = $201.00.
`currency`	string	No	ISO 4217 numérico. Default: "484" (MXN).
`reference`	string	Sí	3–30 caracteres; única por intento. Usa metadata para IDs más largos.
`metadata`	object	No	JSON privado; 50 claves y 8 KB máximo.
`customer`	object	Sí	email, first_name y last_name; phone opcional.
`return_url`	URL	Sí	HTTPS de retorno del comercio.
`allowed_origin`	URL/origin	Sí	Origen registrado exacto que montará el iframe.
`expires_in`	integer	No	300–86400 segundos. Default: 1800.

customer.email debe ser válido; first_name y last_name admiten 1–80 caracteres; phone admite 7–15 dígitos y un + inicial.

2 · Frontend

Monta el checkout

npm install @arkaxapp/payments-js

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

const checkout = mount({
  container: "#arkax-checkout",
  baseUrl: "https://checkout.arkax.app",
  clientSecret: session.client_secret,
  onResult(payment) {
    // Confirma payment.id desde tu backend o por webhook.
    console.log(payment.id, payment.status);
  },
  onError(error) {
    console.error(error.code, error.message);
  }
});

También puedes abrir session.checkout_url directamente o usar open() para mostrar un modal.

3 · Confirmación

Trata los estados correctamente

Estado	Qué hacer
`created`	Esperando el primer intento.
`processing`	El cobro está en proceso.
`requires_action`	El comprador debe completar 3DS u otra acción.
`unknown`	Resultado ambiguo; no reintentes automáticamente.
`approved`	Pago aprobado.
`declined`	Pago rechazado; crea una sesión y referencia nuevas.
`expired`	La sesión venció.
`partially_refunded / refunded / reversed`	Estado posterior a una devolución.

Consulta GET /v1/payments/{paymentId} con scope payments:read o procesa los webhooks. Después del intento, el pago incluye card_brand y card_last_four para conciliación; Arkax nunca devuelve el PAN completo ni el CVV. Nunca entregues el producto basándote solo en el callback del navegador.

Metadata

Concilia con tus IDs

metadata admite cualquier objeto JSON con hasta 50 claves y 8 KB. Úsala para IDs internos que superen los 30 caracteres permitidos en reference. Arkax la devuelve en la consulta y webhooks, pero nunca se muestra al comprador. No incluyas datos de tarjeta ni secretos.

Links

Cobra con una URL

POST /v1/payment-links recibe amount, reference, description, metadata, return_url, allowed_origin y expires_at. La descripción y referencia se muestran; metadata permanece privada.

Webhooks

Automatiza de forma segura

Registra una URL HTTPS pública con POST /v1/webhook-endpoints. Verifica Arkax-Signature como HMAC-SHA256 de timestamp + "." + rawBody, deduplica por event.id y responde 2xx rápidamente.

Los eventos incluyen payment.succeeded, payment.failed, payment.unknown, refunds y reversals. La metadata original acompaña cada cambio relevante.

Contrato completo

El OpenAPI contiene schemas, tipos, campos requeridos, límites, respuestas y errores de todas las rutas. La guía del repositorio añade ejemplos de firmas, refunds, reversals e idempotencia.

Abrir OpenAPI Guía extensa →