@validapay/3ds

Confirma com o banco emissor que quem está pagando é o dono do cartão. Na maioria das compras a confirmação é invisível; quando o banco pede, abre uma janela do próprio banco.

npm install @validapay/3ds

Uso

Chame quando o comprador clicar em pagar, antes de tokenizar o cartão:

import { authenticate } from "@validapay/3ds";

const authentication = await authenticate({
  publicId: "3f1c2a8e-8a4b-4c1e-9d3a-2b7e6f5a4c10",
  amount: 149.9,
  card: { number: "4111111111111111", holderName: "MARIA SILVA", cvv: "123", expiration: "12/2030" },
  customer: {
    name: "Maria Silva",
    document: "12345678901",
    email: "[email protected]",
    phone: "11999998888",
    address: { zipCode: "01001000", street: "Praça da Sé", number: "1", neighborhood: "Sé", city: "São Paulo", state: "SP" },
  },
  statementDescriptor: "Loja Exemplo",
});

• amount é o valor exato da cobrança, em reais, já com juros e descontos.
• Devolve null quando a conta não usa autenticação. Pode chamar sempre.
• Exige telefone e endereço completo do comprador.
• Comprador estrangeiro: customer.address.country com o código ISO do país (ex.: US), phone em E.164 (+14155552671) e document opcional.
• Desabilite o botão de pagar até a promessa resolver.
• environment: production (padrão), sandbox ou development.
• challenge: true pede o desafio ao banco em vez de deixar passar sem atrito. Serve para testar a janela de senha; em produção quem decide é o banco.

Depois, passe authentication para @validapay/tokenize e inclua na cobrança:

const { cardToken } = await tokenize({ publicId, card, customer, authentication });

POST /v1/charges
{ "paymentMethod": "creditcard", "amount": 149.9, "cardToken": "ctk_…", "authentication": { … } }

Erros

| code | Quando acontece | |---|---| | THREE_DS_MISSING_DATA | faltam telefone ou partes do endereço; details.missing lista os campos | | THREE_DS_FAILED | o banco não autenticou | | THREE_DS_TIMEOUT | o comprador não concluiu a confirmação em 3 minutos | | THREE_DS_UNAVAILABLE | a autenticação não carregou; tente de novo | | INVALID_AMOUNT | amount ausente ou menor ou igual a zero |