Blu Checkout Tokenization

SDK de tokenizacao de cartoes da Blu para checkout ecommerce. Os dados sensiveis do cartao transitam exclusivamente entre iframes seguros e a Malga — o SDK, o lojista e a API de cobranca nunca acessam dados de cartao, apenas o tokenId (conformidade PCI DSS).

Fork de @malga/tokenization (MIT). A logica de tokenizacao e herdada do upstream; este fork adiciona branding, CI/CD, exemplos e documentacao Blu.

Installation

npm install @useblu/checkout-tokenization

or

pnpm add @useblu/checkout-tokenization

Getting Started

1. Adicione no seu formulario os containers para cada campo do cartao:

<form onsubmit="handleGetTokenId(event)">
  <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>

2. Configure o SDK com as credenciais do merchant e chame tokenize():

import { BluTokenization } from '@useblu/checkout-tokenization'

const tokenization = new BluTokenization({
  apiKey: '<API_KEY_DO_MERCHANT>',
  clientId: '<CLIENT_ID_DO_MERCHANT>',
  options: {
    config: {
      fields: {
        cardNumber: { container: 'card-number', placeholder: '9999 9999 9999 9999' },
        cardHolderName: { container: 'card-holder-name', placeholder: 'Nome impresso' },
        cardExpirationDate: { container: 'card-expiration-date', placeholder: 'MM/AA' },
        cardCvv: { container: 'card-cvv', placeholder: '999' },
      },
      styles: {
        input: { color: '#000', 'font-size': '16px' },
      },
      preventAutofill: false,
    },
    sandbox: true,
  },
})

// Eventos disponiveis
tokenization.on('cardTypeChanged', (event) => console.log('bandeira', event))
tokenization.on('validity', (event) => console.log('validity', event))
tokenization.on('focus', (event) => console.log('focus', event))
tokenization.on('blur', (event) => console.log('blur', event))

async function handleGetTokenId(event) {
  event.preventDefault()

  const { tokenId } = await tokenization.tokenize()

  // Envie o tokenId + dados da cobranca para a API de cobranca — ver abaixo.
  await criarCobranca(tokenId)
}

As credenciais (apiKey / clientId) sao por merchant e sao fornecidas pela Blu.

Fluxo completo

O fluxo tem dois passos:

1. Gerar o token — o SDK tokeniza o cartao e retorna um tokenId (tokenize()). Os dados sensiveis ficam entre os iframes seguros e a Malga.
2. Enviar o token para a API de cobranca — envie o tokenId, junto com os dados da cobranca, para a API de cobranca, que cria a cobranca.

async function criarCobranca(tokenId) {
  await fetch('https://<endpoint-da-api-de-cobranca>/<rota-de-cobranca>', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_uuid: '<identificador-do-lojista>',
      charge: {
        amount: 15000, // inteiro em centavos
        order_id: 'pedido-123',
        statement_descriptor: 'LOJA XYZ',
        description: 'Pedido 123',
        payment_method: { payment_type: 'credit', installments: 3 },
        payment_source: { source_type: 'token', token_id: tokenId },
      },
    }),
  })
}

API Reference

new BluTokenization(configurations)

Campo	Tipo	Descricao
apiKey	string	Chave de API do merchant
clientId	string	Identificador do merchant
options.config.fields	object	Config dos campos seguros (cardNumber, cardHolderName, cardExpirationDate, cardCvv)
options.config.styles	object	Estilos dos inputs
options.config.preventAutofill	boolean	Desabilita autofill
options.sandbox	boolean	Ambiente sandbox

tokenize(): Promise<{ tokenId, error? }>

Retorna { tokenId } em caso de sucesso, ou { error } em caso de falha (error.type, error.declinedCode quando card_declined).

on(eventType, handler)

Eventos: validity, cardTypeChanged, focus, blur.

Ambientes

O ambiente e escolhido por options — nao ha URL a configurar:

options	Ambiente Malga
{ debug: true }	dev (hosted-fields.dev.malga.io)
{ sandbox: true }	sandbox (hosted-fields-sandbox.malga.io)
{} ou { sandbox: false }	producao (hosted-fields.malga.io)

Para producao, use as credenciais de producao do merchant (fornecidas pela Blu).

Tratamento de erros

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

if (error) {
  // error.type: 'api_error' | 'bad_request' | 'invalid_request_error' | 'card_declined'
  // error.declinedCode: 'insufficient_funds' | 'invalid_cvv' | 'expired_card' | ...
  console.error(error.type, error.message, error.declinedCode)
}

Examples

• examples/blu/vanilla-js/ — HTML + JS puro (tokenizar e enviar a cobranca)
• examples/blu/react/ — componente React (tokenizar e enviar a cobranca)
• examples/v1 e examples/v2 — exemplos herdados do upstream

Seguranca (PCI DSS)

Os dados de cartao transitam apenas entre os iframes seguros e a Malga. Nem o frontend do lojista, nem o SDK, nem a API de cobranca tem acesso aos dados sensiveis — somente ao tokenId resultante.

Contributing

Whether you're helping us fix bugs, improve the docs, or spread the word, we'd love to have you as part of this project! Read below to learn how you can take part of it.

Code of Conduct

We adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.

Contributing Guide

Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, how we sync with the upstream project, and how to build and test your changes.

Security

Found a security issue? Please do not open a public issue — follow our security policy and report it privately to seguranca@useblu.com.br.

License

Licensed under the terms of the MIT License. This project is a fork of plughacker/malga-tokenization, with attribution preserved.