Registrar uma confirmação de pagamento seguro

Eiji Kitamura

Para usar a confirmação de pagamento seguro (SPC, na sigla em inglês) em uma transação, o cliente precisa primeiro registrar um autenticador. Esse processo é muito semelhante ao processo de registro do WebAuthn, com a adição de uma extensão de pagamento.

Neste artigo, os bancos emissores que atuam como partes confiáveis (RPs, na sigla em inglês) podem aprender como implementar o registro de SPC. A experiência do usuário é explicada em mais detalhes na visão geral da confirmação de pagamento seguro.

Como funciona o registro na confirmação de pagamento seguro?

O SPC é criado como uma extensão do padrão WebAuthn.

A partir de abril de 2022, o SPC só oferece suporte a autenticadores da plataforma de verificação de usuário (UVPA, na sigla em inglês) em computadores. Isso significa que o cliente precisa estar em um computador ou laptop com um autenticador incorporado, como:

  • Desbloquear recurso, incluindo o Touch ID em um dispositivo macOS
  • Windows Hello em um dispositivo Windows

Registrar o dispositivo

O registro de um dispositivo pela parte confiável (RP, na sigla em inglês) precisa seguir um processo de verificação do usuário suficientemente forte. A parte restrita precisa garantir que o cliente tenha feito login no site usando autenticação forte para que a conta não seja facilmente invadida. Cuidado: a falta de segurança nesse processo também coloca a SPC em risco.

Depois que o RP tiver autenticado o cliente, o cliente poderá registrar um dispositivo.

Fluxo de trabalho de registro típico no site da parte confiável

Detecção de recursos

Antes de pedir ao cliente para registrar o dispositivo, o RP precisa verificar se o navegador é compatível com SPC.

const isSecurePaymentConfirmationSupported = async () => {
  if (!'PaymentRequest' in window) {
    return [false, 'Payment Request API is not supported'];
  }

  try {
    // The data below is the minimum required to create the request and
    // check if a payment can be made.
    const supportedInstruments = [
      {
        supportedMethods: "secure-payment-confirmation",
        data: {
          // RP's hostname as its ID
          rpId: 'rp.example',
          // A dummy credential ID
          credentialIds: [new Uint8Array(1)],
          // A dummy challenge
          challenge: new Uint8Array(1),
          instrument: {
            // Non-empty display name string
            displayName: ' ',
            // Transparent-black pixel.
            icon: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==',
          },
          // A dummy merchant origin
          payeeOrigin: 'https://non-existent.example',
        }
      }
    ];

    const details = {
      // Dummy shopping details
      total: {label: 'Total', amount: {currency: 'USD', value: '0'}},
    };

    const request = new PaymentRequest(supportedInstruments, details);
    const canMakePayment = await request.canMakePayment();
    return [canMakePayment, canMakePayment ? '' : 'SPC is not available'];
  } catch (error) {
    console.error(error);
    return [false, error.message];
  }
};

isSecurePaymentConfirmationSupported().then(result => {
  const [isSecurePaymentConfirmationSupported, reason] = result;
  if (isSecurePaymentConfirmationSupported) {
    // Display the payment button that invokes SPC.
  } else {
    // Fallback to the legacy authentication method.
  }
});

Registrar um autenticador

Para registrar um dispositivo na SPC, siga o processo de registro do WebAuthn com estes requisitos:

  • O autenticador da plataforma é necessário: authenticatorSelection.authenticatorAttachment é platform.
  • A verificação do usuário é obrigatória: authenticatorSelection.userVerification é required.
  • Credenciais detectáveis (chaves residentes) são obrigatórias: authenticatorSelection.residentKey é required.

Além disso, especifique uma extensão de "pagamento" com isPayment: true. Especificar essa extensão sem atender aos requisitos acima gerará uma exceção

Algumas outras ressalvas:

  • rp.id: o nome do host da RP. A parte eTLD+1 do domínio precisa corresponder ao local em que está sendo registrado. Ele pode ser usado para autenticação em domínios que correspondem a eTLD+1.
  • user.id: uma expressão binária do identificador do usuário. O mesmo identificador será retornado após a autenticação. Portanto, a parte restrita precisa fornecer um identificador de usuário consistente do titular do cartão.
  • excludeCredentials: uma matriz de credenciais para que a RP possa evitar o registro do mesmo autenticador.

Para mais informações sobre o processo de registro do WebAuthn, consulte webauthn.guide.

Exemplo de código de registro:

const options = {
  challenge: new Uint8Array([21...]),
  rp: {
    id: "rp.example",
    name: "Fancy Bank",
  },
  user: {
    id: new Uint8Array([21...]),
    name: "jane.doe@example.com",
    displayName: "Jane Doe",
  },
  excludeCredentials: [{
    id: new Uint8Array([21...]),
    type: 'public-key',
    transports: ['internal'],
  }, ...],
  pubKeyCredParams: [{
    type: "public-key",
    alg: -7 // "ES256"
  }, {
    type: "public-key",
    alg: -257 // "RS256"
  }],
  authenticatorSelection: {
    userVerification: "required",
    residentKey: "required",
    authenticatorAttachment: "platform",
  },
  timeout: 360000,  // 6 minutes

  // Indicate that this is an SPC credential. This is currently required to
  // allow credential creation in an iframe, and so that the browser knows this
  // credential relates to SPC.
  extensions: {
    "payment": {
      isPayment: true,
    }
  }
};

try {
  const credential = await navigator.credentials.create({ publicKey: options });
  // Send new credential info to server for verification and registration.
} catch (e) {
  // No acceptable authenticator or user refused consent. Handle appropriately.
}

Após um registro bem-sucedido, a RP recebe uma credencial para enviar ao servidor para verificação.

Verificar registro

No servidor, a RP precisa verificar a credencial e manter a chave pública para uso posterior. O processo de registro do lado do servidor é igual a um registro comum do WebAuthn. Nada mais é necessário para obedecer ao SPC.

Registro de dentro de um iframe

Se o pagador não tiver registrado o dispositivo no RP (emissor de pagamento), o pagador poderá se registrar no site do comerciante. Após uma autenticação bem-sucedida durante uma compra, a parte com restrições pode solicitar que o pagador registre o dispositivo indiretamente em um iframe.

Fluxo de trabalho do registro no site de um comerciante durante o pagamento.

Para fazer isso, o comerciante ou pai precisa permitir explicitamente essa ação em um iframe usando a política de permissões. O emissor segue as mesmas etapas para registrar um autenticador em um iframe.

O comerciante pode permitir o registro de duas formas:

  1. A tag de iframe no HTML veiculado do domínio do comerciante adiciona um atributo allow:

    <iframe name="iframe" allow="payment https://spc-rp.glitch.me"></iframe>

    Verifique se o atributo allow contém payment e a origem da RP que invoca o registro do WebAuthn.

  2. O documento do frame pai (veiculado do domínio do comerciante) é enviado com um cabeçalho HTTP Permissions-Policy:

    Permissions-Policy: payment=(self "https://spc-rp.glitch.me")

Próximas etapas

Depois que um dispositivo é registrado para a parte confiável, o cliente pode confirmar os pagamentos no site do comerciante usando a confirmação de pagamento seguro.