Cofre
Biblioteca do Hosted Fields (cofre)
Script que a sua página inclui pra montar o campo do cartão (Hosted Fields). Ele cria um
iframe servido pelo cofre, repassa ticket e encryptionKey, e devolve o token quando o
cliente envia. Sem autenticação. Cache de 5 minutos (ETag).
<div id="card"></div>
<script src="https://vault.sandbox.switchpay.app.br/sdk.js"></script>
<script>
const field = SwpVault.mount(document.getElementById('card'), {
vaultUrl: intent.cardTokenization.vaultUrl,
ticket: intent.cardTokenization.ticket,
encryptionKey: intent.cardTokenization.encryptionKey,
onToken: ({ token, brand, last4 }) => confirmOnYourServer(intent.id, token),
onError: (err) => showMessage(err.code) // TICKET_EXPIRED, VALIDATION_ERROR, PROVIDER_ERROR…
});
// field.tokenize() dispara o envio por código, se preferir ao botão dentro do campo
</script>O que a sua página recebe em onToken é o mesmo corpo da resposta de POST /tokenize.
O número do cartão nunca aparece no seu JavaScript, na URL nem no seu servidor.
Opções a mais do mount, todas opcionais (a forma de uso acima não muda):
| Opção | O que faz |
|---|---|
style | Aparência do campo: fonte, cor, tamanho e tema. Só fonte já instalada no aparelho — o campo não baixa nada de fora. |
placeholders | Texto de exemplo de cada campo. |
locale | Idioma dos textos do campo: pt-BR (padrão) ou en. |
hideSubmitButton | true esconde o botão de dentro do campo. Use com o seu botão de pagar chamando field.tokenize(). |
onReady | O campo terminou de carregar. |
onChange | Algo mudou. Traz só { field, empty, complete, valid, brand, formComplete }: o nome do campo, se está vazio, completo e válido, a bandeira e se os 4 campos estão prontos pra enviar. Nunca traz dígito do cartão. |
onFocus / onBlur | Um campo ganhou ou perdeu o foco. Traz { field }. |
Além de tokenize(), o que o mount devolve tem focus() (põe o cursor no número do
cartão) e unmount() (tira o campo da página).
O campo confere o cartão enquanto o cliente digita (número, validade e código de segurança) e só chama o cofre com os dados válidos.
curl -X GET "https://api.sandbox.switchpay.app.br/sdk.js""/*! SwitchPay Hosted Fields 0.2.0 */ (function(w){ ... w.SwpVault = { mount } })(window);"{
"code": "RATE_LIMITED",
"message": "Limite de chamadas atingido. Aguarde e tente de novo."
}