Autenticação

​

Como funciona

• A chave secreta só aparece nas chamadas entre o seu backend e a Malga.
• O navegador recebe apenas a sub-key, com escopo tokens e válida por 15 minutos.
• Cada abertura do checkout gera uma sub-key nova.

​

1. Crie a sub-key no backend

1. Chamar POST /v1/auth com o X-Client-Id e a chave secreta da sua conta, pedindo {"scope": ["tokens"], "expires": 900}.
2. Devolver ao front-end só o publicKey e o clientId da resposta, nunca a chave secreta.

curl --location --request POST 'https://api.malga.io/v1/auth' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "scope": ["tokens"],
    "expires": 900
  }'

{
  "publicKey": "YOUR_PUBLIC_KEY",
  "clientId": "YOUR_CLIENT_ID",
  "scope": ["tokens"],
  "expires": 900,
  "createdAt": "2026-09-30T14:00:00.000Z"
}

​

2. Crie a instância do SDK com a sub-key

import { MalgaTokenization } from '@malga/tokenization'

async function createMalgaTokenization() {
  const response = await fetch('/checkout/malga-key', { method: 'POST' })
  const { publicKey, clientId } = await response.json()

  return new MalgaTokenization({
    apiKey: publicKey,
    clientId,
    options: {
      sandbox: true,
      config: {
        fields: {
          cardNumber: { container: 'card-number' },
          cardHolderName: { container: 'card-holder-name' },
          cardCvv: { container: 'card-cvv' },
          cardExpirationDate: { container: 'card-expiration-date' },
        },
      },
    },
  })
}

const malgaTokenization = await createMalgaTokenization()

async function handleSubmit(event: SubmitEvent) {
  event.preventDefault()

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

​

Quando a sub-key expira

• Crie a sub-key quando o cliente abrir a tela de pagamento, não no início da navegação na loja.
• Se a sua jornada de pagamento costuma passar de 15 minutos, use um prazo um pouco maior, como 3600 (1 hora), em vez de uma chave sem expiração.
• Para trocar a sub-key, chame destroy() na instância atual, busque uma sub-key nova no backend e crie outra instância. Os dados digitados nos campos não são mantidos, então peça ao cliente para digitar o cartão de novo.

​

Boas práticas