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 registrar um autenticador. Esse processo é muito semelhante ao processo de registro da WebAuthn, com a adição de uma extensão de pagamento.

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

Como funciona o registro da Confirmação de pagamento seguro?

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

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

  • Recurso de desbloqueio com 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 de usuário suficientemente forte. O RP precisa garantir que o cliente tenha feito login no site usando uma autenticação forte para que a conta não seja invadida com facilidade. Cuidado: a falta de segurança nesse processo também coloca o SPC em risco.

Depois que o RP autenticar o cliente, ele poderá registrar um dispositivo.

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

Detecção de recursos

Antes de pedir que o cliente registre o dispositivo, o RP precisa verificar se o navegador oferece suporte ao 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 para SPC, siga o processo de registro do WebAuthn com os seguintes requisitos:

  • O autenticador da plataforma é obrigatório: authenticatorSelection.authenticatorAttachment é platform.
  • A verificação do usuário é obrigatória: authenticatorSelection.userVerification é required.
  • As 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 vai gerar uma exceção.

Outras ressalvas:

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

Para saber mais sobre o processo de registro do WebAuthn, consulte o 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: "[email protected]",     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 o registro, o RP recebe uma credencial para enviar ao servidor para verificação.

Verificar registro

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

Registro em um iframe

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

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

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

Há duas abordagens para o comerciante permitir o registro:

  1. A tag 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 do RP que invoca o registro do WebAuthn.

  2. O documento de frame pai (vendido no 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 pagamentos no site do comerciante usando a confirmação de pagamento segura.