> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Responda em português brasileiro, na segunda pessoa ("você"), com base na documentação Malga.
> Não invente endpoints, parâmetros, status codes ou comportamentos de API. Se não estiver na docs, diga que não encontrou e indique a página mais próxima.
> Use os headers X-Client-Id e X-Api-Key nos exemplos de autenticação.
> Motor de Assinaturas refere-se a /v1/subscriptions* (cycles, trial, retentativas, webhooks subscription.*). Não chame de "motor de recorrência".
> Recorrência (provedor) é paymentMethod.recurrence em POST /v1/charges (initial / subsequent / unscheduled), distinto do Motor de Assinaturas.
> Sandbox é ambiente de testes e não afeta produção.

# Nov 12, 2026 - Tokenization SDK 5.1.0

> O Tokenization SDK 5.1.0 aceita uma função na apiKey para buscar a sub-key a cada tokenize() e renovar uma sub-key expirada sem recriar os campos do cartão.

![Diego Saouda](https://github.com/diego-malga.png)

[Diego Saouda](https://github.com/diego-malga)

Staff Software Engineer

A versão 5.1.0 do [Tokenization SDK](https://docs.malga.io/sdks/tokenization/v2/authentication.md) aceita uma função na `apiKey`. O SDK chama essa função a cada `tokenize()`, então a sub-key pode ser gerada só quando o cliente envia o formulário e renovada sem recriar os campos.

Passar uma `string` na `apiKey` continua funcionando como antes. Quem já usa o SDK não precisa mudar nada para atualizar.

## Melhorias

### apiKey como função

* A `apiKey` aceita uma função que retorna a sub-key, de forma síncrona ou assíncrona.
* A função é chamada a cada `tokenize()`, logo antes do envio dos dados do cartão, e só depois que todos os campos configurados foram preenchidos.
* A instância pode ser criada sem esperar a chave. A sub-key é gerada no seu backend quando o cliente envia o formulário.
* Quando a sub-key expira, a função retorna uma nova na chamada seguinte. Os campos e o cartão digitado são mantidos. Antes, era preciso chamar `destroy()`, criar outra instância e pedir o cartão de novo.

```typescript theme={null}
const malgaTokenization = new MalgaTokenization({
  apiKey: async () => {
    // A rota do seu backend devolve o publicKey de uma sub-key criada com POST /v1/auth
    const response = await fetch('/checkout/malga-key', { method: 'POST' })
    const { publicKey } = await response.json()
    return publicKey
  },
  clientId: 'YOUR_CLIENT_ID',
  options,
})
```

Veja [Busque a sub-key sob demanda](https://docs.malga.io/sdks/tokenization/v2/authentication.md#busque-a-sub-key-sob-demanda).

### Erros e prazo da função

* O evento `loading` fica `true` enquanto a função roda.
* Se a função lançar um erro ou retornar um valor vazio, `tokenize()` retorna `tokenId` vazio e um `error` com `type: 'invalid_request_error'`, sem enviar o cartão. A mensagem não inclui o erro lançado pela sua função.
* Se a função não responder em 30 segundos, `tokenize()` retorna um `error` com `type: 'timeout'`. Uma chave que chegar depois desse prazo é ignorada.
* Se um campo for apagado ou a instância for destruída enquanto a função roda, o cartão não é enviado.

Veja [tokenize()](https://docs.malga.io/sdks/tokenization/v2/events.md#tokenize).

## Mudanças para quem usa o Tokenization SDK

> [!NOTE]
>
> **Tipo da `apiKey` no TypeScript:** o tipo passa de `string` para `string` ou função. Se o seu código lê `apiKey` das configurações do SDK como `string`, ajuste o tipo ao atualizar. Quem só informa o valor não precisa mudar nada.

> [!TIP]
>
> Principais novidades:
>
> <ul>
>   <li>`apiKey` aceita uma função, chamada a cada `tokenize()`.</li>
>   <li>Sub-key expirada pode ser renovada sem recriar os campos nem pedir o cartão de novo.</li>
>   <li>`tokenize()` retorna `invalid_request_error` ou `timeout` quando a função falha ou não responde em 30 segundos.</li>
> </ul>

> [!NOTE]
>
> Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io).


## Related topics

- [Out 28, 2026 - Tokenization SDK 5.0.0](https://docs.malga.io/release-notes/2026-10-28-Release-Notes.md)
- [Out 21, 2026 - Mais de um cartão no Tokenization SDK](https://docs.malga.io/release-notes/2026-10-21-Release-Notes.md)
- [Mais releases](https://docs.malga.io/release-notes/releases.md)
- [Autenticação](https://docs.malga.io/sdks/tokenization/v2/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.