Utilizando os eventos

A aplicação possui três métodos principais: on, tokenize e destroy.

on(eventType, function)

O método on permite escutar eventos e executar um callback quando um determinado evento ocorre. Ele retorna uma função que remove o callback registrado:

const removeListener = malgaTokenization.on('validity', (data) => console.log(data))

removeListener()

Cada instância de MalgaTokenization tem seus próprios eventos. Ao tokenizar mais de um cartão, registre o on na instância de cada cartão. Nos eventos, field é o container configurado no campo, por exemplo card-number-2.

Eventos disponíveis

`cardTypeChanged`

Disparado quando o valor do campo de número do cartão é alterado. Objeto de retorno:

{
  field: string // container do campo, ex: 'card-number'
  parentNode: Element
  card?: {
    niceType: string
    type: string
    patterns: (number | number[])[]
    gaps: number[]
    lengths: number[]
    code: {
      name: string
      size: number
    }
  }
}

Exemplo de uso

malgaTokenization.on('cardTypeChanged', () => console.log('cardTypeChanged'))

`validity`

Disparado quando há uma alteração nos campos e a validação padrão (defaultValidation) está ativada. Objeto de retorno:

{
  field: string // container do campo, ex: 'card-number'
  valid: boolean
  error: {
    field: string // container do campo, ex: 'card-number'
    message: string
    code: string
  }
  empty: boolean
  potentialValid: boolean
  parentNode: Element | null
}

Exemplo de uso

malgaTokenization.on('validity', () => console.log('validity'))

`focus` e `blur`

Eventos disparados quando um campo recebe ou perde foco. Objeto de retorno:

{
  field: string // container do campo, ex: 'card-number'
  parentNode: Element
}

Exemplo de uso

malgaTokenization.on('blur', () => console.log('blur'))
malgaTokenization.on('focus', () => console.log('focus'))

`loading`

Disparado quando a tokenização começa (isLoading: true) e quando termina (isLoading: false), com sucesso, com erro ou por tempo esgotado. Útil para desabilitar o botão de envio enquanto o cartão é tokenizado. Objeto de retorno:

{
  isLoading: boolean
}

Exemplo de uso

malgaTokenization.on('loading', ({ isLoading }) => {
  submitButton.disabled = isLoading
})

tokenize()

Método responsável por enviar os dados do cartão para tokenização. Com mais de um cartão na página, chame tokenize() na instância de cada cartão. Cada instância retorna o resultado do próprio cartão, mesmo quando as chamadas são executadas ao mesmo tempo. Se o iframe do número do cartão não responder em 30 segundos, tokenize() retorna tokenId vazio e um error com type: 'timeout', e o evento loading volta para false. A partir da versão 5.0.0, tokenize() confere antes se todos os campos configurados em config.fields foram preenchidos. Se faltar algum, o método retorna na hora, sem enviar nada à API e sem disparar o evento loading, com tokenId vazio e um error com type: 'invalid_request_error'. O details lista os campos que faltam, por exemplo ['cardCvv', 'cardExpirationDate']. Campos que não estão em config.fields não são exigidos.

const { tokenId, error } = await malgaTokenization.tokenize()

if (error?.type === 'invalid_request_error') {
  // error.details: campos que faltam, ex.: ['cardCvv']
  mostrarCamposPendentes(error.details)
  return
}

Quando o campo de número do cartão não está na página, tokenize() é rejeitado com um erro. Trate esse caso com try/catch.

Objeto de retorno:

{
  tokenId: string
  error: {
    type: string 
    code: number
    message: string
    details?: string | string[]
    declinedCode?: string 
    }
}

Exemplo de uso

try {
  const { tokenId, error } = await malgaTokenization.tokenize()

  if (error) {
    console.error('Error', error.message)
    return
  }

  console.log('TokenId:', tokenId)
} catch (exception) {
  // Campo de número do cartão fora da página
  console.error('Tokenization failed', exception)
}

Método responsável por criptografar os dados do cartão, enviá-los para tokenização e retornar o tokenID em caso de sucesso.

destroy()

Desmonta a instância de MalgaTokenization. O método remove os iframes dos containers, o listener de mensagens e os callbacks registrados com on, apaga os dados do cartão coletados e libera os containers para uma nova instância.

Disponível a partir da versão 5.0.0 do @malga/tokenization.

Chame destroy() sempre que o checkout sair da tela. Em aplicações de página única, como React, Vue e Angular, montar a tela de novo sem chamar destroy() faz o construtor lançar ContainerInUseError, porque a instância anterior ainda ocupa os containers.

Até a versão 4.x, criar uma nova instância nos mesmos containers sem chamar destroy() não dava erro: empilhava um segundo conjunto de iframes e mantinha o listener anterior ativo. A partir da 5.0.0, o construtor lança ContainerInUseError. Se a tela do checkout pode ser montada mais de uma vez (um useEffect sem função de limpeza, o StrictMode do React ou a volta para a rota), chame destroy() na desmontagem antes de atualizar.

Depois de destroy(), tokenize() lança um erro. Chamar destroy() mais de uma vez não tem efeito. Exemplo de uso Crie a instância quando o componente do checkout é montado e chame destroy() quando ele é desmontado: ao trocar de rota, ao voltar para o carrinho ou ao entrar de novo na tela de pagamento. Assim, cada montagem tem a sua própria instância, e a anterior já liberou os containers.

checkout-config.ts

export const configurations = {
  apiKey: 'YOUR_API_KEY',
  clientId: 'YOUR_CLIENT_ID',
  options: {
    sandbox: true,
    config: {
      fields: {
        cardNumber: { container: 'card-number' },
        cardHolderName: { container: 'card-holder-name' },
        cardCvv: { container: 'card-cvv' },
        cardExpirationDate: { container: 'card-expiration-date' },
      },
    },
  },
}

import { useEffect, useRef } from 'react'
import { MalgaTokenization } from '@malga/tokenization'
import { configurations } from './checkout-config'

export function Checkout() {
  const malgaTokenization = useRef<MalgaTokenization | null>(null)

  useEffect(() => {
    const instance = new MalgaTokenization(configurations)
    malgaTokenization.current = instance

    // Desmontagem: troca de rota e também a segunda montagem do StrictMode
    return () => instance.destroy()
  }, [])

  async function handleSubmit(event: React.FormEvent) {
    event.preventDefault()

    const { tokenId, error } = await malgaTokenization.current!.tokenize()
    // Envie o tokenId para o seu backend
  }

  return (
    <form onSubmit={handleSubmit}>
      <div id="card-number" />
      <div id="card-holder-name" />
      <div id="card-cvv" />
      <div id="card-expiration-date" />
      <button type="submit">Pagar</button>
    </form>
  )
}

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue'
import { MalgaTokenization } from '@malga/tokenization'
import { configurations } from './checkout-config'

let malgaTokenization: MalgaTokenization | undefined

onMounted(() => {
  malgaTokenization = new MalgaTokenization(configurations)
})

onUnmounted(() => {
  malgaTokenization?.destroy()
})

async function handleSubmit() {
  const { tokenId, error } = await malgaTokenization!.tokenize()
  // Envie o tokenId para o seu backend
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <div id="card-number"></div>
    <div id="card-holder-name"></div>
    <div id="card-cvv"></div>
    <div id="card-expiration-date"></div>
    <button type="submit">Pagar</button>
  </form>
</template>

import { Component, OnDestroy, OnInit } from '@angular/core'
import { MalgaTokenization } from '@malga/tokenization'
import { configurations } from './checkout-config'

@Component({
  selector: 'app-checkout',
  template: `
    <form (ngSubmit)="handleSubmit()">
      <div id="card-number"></div>
      <div id="card-holder-name"></div>
      <div id="card-cvv"></div>
      <div id="card-expiration-date"></div>
      <button type="submit">Pagar</button>
    </form>
  `,
})
export class CheckoutComponent implements OnInit, OnDestroy {
  private malgaTokenization?: MalgaTokenization

  ngOnInit() {
    this.malgaTokenization = new MalgaTokenization(configurations)
  }

  ngOnDestroy() {
    this.malgaTokenization?.destroy()
  }

  async handleSubmit() {
    const { tokenId, error } = await this.malgaTokenization!.tokenize()
    // Envie o tokenId para o seu backend
  }
}

Sem framework, a regra é a mesma: chame destroy() no ponto em que o seu código remove o formulário de pagamento da página, antes de criar outra instância com os mesmos containers.

Containers em uso

Cada container pertence a uma única instância enquanto ela não for destruída. O construtor lança um erro, antes de renderizar qualquer campo, quando:

o container já é usado por outra instância ativa: ContainerInUseError;
o mesmo container aparece em dois campos da mesma configuração: DuplicatedContainerError.

Se o construtor lançar qualquer erro, nenhum container fica reservado: corrija a configuração e crie a instância de novo. Os dois erros trazem o nome do container repetido na propriedade container e podem ser importados do pacote:

import { MalgaTokenization, ContainerInUseError } from '@malga/tokenization'

try {
  const malgaTokenization = new MalgaTokenization(configurations)
} catch (error) {
  if (error instanceof ContainerInUseError) {
    // Chame destroy() na instância anterior antes de criar a nova
    console.error('Container já em uso:', error.container)
  }
}

Exemplos de tokenização

Veja o código completo

Tokenization SDK

API SDKs

UI SDKs

Plugins

Utilizando os eventos

on(eventType, function)

Eventos disponíveis

`cardTypeChanged`

`validity`

`focus` e `blur`

`loading`

tokenize()

destroy()

Containers em uso

Exemplos de tokenização

​on(eventType, function)

​Eventos disponíveis

cardTypeChanged

validity

focus e blur

loading

​tokenize()

​destroy()

​Containers em uso

Exemplos de tokenização

on(eventType, function)

Eventos disponíveis

`cardTypeChanged`

`validity`

`focus` e `blur`

`loading`

tokenize()

destroy()

Containers em uso