Referencia de n1co.js

El loader, el cliente, el card element, la captura de tarjetas, el cobro y los errores de n1co.js.

1. Carga n1co.js desde el host de n1co, en una página https.
2. Crea el cliente: n1co('pk_…').
3. Monta el card element y llama a capture() o confirmPayment().

<!doctype html>
<html lang="es">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>n1co.js</title>
  </head>
  <body>
    <div id="card"></div>
    <script src="https://elements.n1co.dev/v1/n1co.js"></script>
    <script>
      const card = n1co('pk_3x4mpl3pUbl1shabl3k3yAAAAAAAAAAA').elements().create('card');
      card.on('ready', () => console.log('card element listo'));
      card.on('error', (error) => console.error(error.code, error.message));
      card.mount('#card');
    </script>
  </body>
</html>

Cargar n1co.js#

<script src="https://elements.n1co.dev/v1/n1co-<hash>.js" integrity="sha384-…" crossorigin="anonymous"></script>

Cada versión fijada se publicará en el Changelog. En desarrollo, el host es https://elements.n1co.dev.

Tu página usa https:// (o localhost para desarrollar) y otro origen que n1co.js. Su Content Security Policy permite ese host en script-src y frame-src.

n1co(publishableKey)#

Crea el cliente con tu llave pública. No acepta opciones.

El card element#

n1co('pk_…').elements().create('card', options?) crea el elemento. 'card' es el único tipo.

Opciones#

Todas son opcionales; un valor inválido lanza invalid_options.

Un número de una marca fuera de brands se informa como unsupported_brand.

Apariencia#

No se acepta CSS libre, solo estos tokens:

colorText y colorDanger necesitan un contraste de 3:1 con colorBackground, y colorTextPlaceholder de 2:1. Con un fondo oscuro, usa theme: 'dark'.

const card = n1co('pk_3x4mpl3pUbl1shabl3k3yAAAAAAAAAAA')
  .elements()
  .create('card', {
    layout: 'inline',
    brands: ['visa', 'mastercard'],
    appearance: { theme: 'light', variables: { fontFamily: 'system', colorBorderFocus: '#7b3eff', borderRadius: 8 } },
  });

Métodos#

Todos menos capture() devuelven el elemento y se pueden encadenar.

mount() lanza un N1coError si la página no cumple los requisitos. Llama a focus() y clear() después de ready.

Eventos#

change se emite cuando cambia el estado, no con cada tecla.

capture()#

const result = await card.capture({ client_secret: 'cs_…_secret_…' });
// { ok: true, card: { id: 'card_…', brand: 'visa', last4: '4242', exp_month: 12, exp_year: 2030 } }

client_secret es el de una sesión de tarjeta. Durante la captura los campos se deshabilitan; si tiene éxito se vacían, y otra captura responde already_captured hasta clear(). Si falla, la promesa se rechaza con N1coCaptureError.

Códigos de capture()#

Tras capture_timeout o network_error, la tarjeta pudo guardarse: lee la sesión antes de crear otra.

confirmPayment()#

Paga un payment intent con el card element o con la tarjeta que adjuntó tu servidor, y muestra 3D Secure si el banco lo pide.

const n1 = n1co('pk_3x4mpl3pUbl1shabl3k3yAAAAAAAAAAA');
const intent = await n1.confirmPayment({ client_secret, card }); // tarjeta nueva
const paid = await n1.confirmPayment({ client_secret }); // tarjeta adjunta

Se resuelve con el intent en succeeded, processing, requires_payment_method o canceled; ver Cobrar. Si n1co tarda, lee el intent hasta 60 segundos antes de resolver con processing.

Corre una confirmación a la vez por cliente.

Rechazos de confirmPayment()#

Se rechaza con N1coPaymentError cuando el intento no pudo hacerse.

retrievePaymentIntent()#

const intent = await n1.retrievePaymentIntent(client_secret);

Lee el intent para mostrar el monto o la tarjeta adjunta antes de confirmar. Tu página ve una versión reducida:

Nunca incluye metadata, referencia, facturación, ids de tarjetas, order_id ni authorization_code.

Errores#

Decide con code, que es estable; message viene traducido y se puede mostrar.

Navegadores#

Las versiones actuales de Chrome, Edge, Firefox y Safari. not_visible solo actúa con IntersectionObserver v2.