NFC wallet passes

Learn how to process transactions with NFC wallet passes.

Os clientes podem vincular seus cartões de crédito e débito a um aplicativo de carteira móvel e, em seguida, fazer pagamentos na loja com a carteira móvel usando um serviço como o Apple Pay. O terminal faz interface com a carteira móvel por meio de comunicação por aproximação (NFC) entre o terminal e o telefone ou smartwatch do comprador.

Além dos cartões de crédito e débito, os clientes também podem manter outros passes em sua carteira móvel, como cartões de fidelidade, vouchers, cartões-presente, cartões de embarque e passagens. Com esses passes habilitados para NFC, eles podem, por exemplo, resgatar um voucher ou acumular pontos em um cartão de fidelidade.

Como comerciante, você pode criar seus próprios passes habilitados para NFC e vinculá-los ao seu programa de fidelidade. Com a integração do Terminal API, você pode verificar se o comprador tem o seu passe na carteira móvel e usar o passe para a transação.

No momento, oferecemos suporte para:

Apple Wallet passes

Como funciona

Existem várias maneiras de implementar passes habilitados para NFC com um pagamento, dependendo do que faz sentido para seu passe e programa de fidelidade:

Fluxo de pagamento: Você verifica os passes após o pagamento e atualiza a conta do cliente posteriormente.
Fluxo de resgate: Você verifica os passes antes do pagamento por meio de uma solicitação de aquisição de cartão. Se houver descontos ou outras vantagens relacionadas ao passe, você pode aplicá-los ao pagamento antecipado.

Existem duas variações do fluxo de resgare: single-tap redeem flow e double-tap redeem flow. Além de uma definição de configuração, a implementação é a mesma. A diferença é que, no fluxo de double-tap, o terminal pede uma segunda vez ao cliente para apresentar o cartão. Isso permite que o cliente resgate o passe NFC na primeira vez que o terminal solicitar o cartão e, a seguir, mude para outro método de pagamento na segunda vez que o terminal solicitar o cartão.

Selecione as guias abaixo para saber mais. Antes de configurar seu passe NFC na Área do Cliente, você precisa entender como esses fluxos funcionam e qual fluxo você deseja implementar.

Inscrição do cliente

Para permitir que os clientes se inscrevam no programa de fidelidade vinculado ao seu passe habilitado para NFC e adicionem o passe à carteira móvel, você pode informá-los por e-mail, mídia social, seu site e assim por diante.

Também podemos ajudar seus compradores a se inscreverem: Quando eles fazem um pagamento de carteira NFC, mas ainda não têm o seu passe na carteira móvel, enviamos um sinal NFC para que os compradores recebam uma mensagem com o URL onde podem se inscrever. Para tornar isso possível, você precisa fornecer essa URL na configuração da sua área do cliente.

Antes de você começar

Configure um servidor para seus passes habilitados para NFC. Nesse servidor de passe, você precisa disponibilizar um URL onde os clientes possam se inscrever no programa de fidelidade vinculado ao seu passe habilitado para NFC e adicionar o passe à carteira móvel.

Você precisa especificar este URL ao configurar o passe em sua área do cliente.
Crie um ou mais passes habilitados para NFC. Consulte, por exemplo, o Guia do Desenvolvedor de Carteira, que explica como criar um passe da Carteira Apple para o seu programa de fidelidade.

Ao criar seu passe, um ID do tipo de passe e uma chave privada são gerados. Você precisará deles mais tarde, quando configurar o passe em sua Área do Cliente.
Make sure that you have built a Terminal API integration that can make a payment.
Tie in your loyalty program with your NFC wallet passes. To learn more about how to link a customer in your loyalty program to a transaction, see Shopper recognition and tokenization.

Configure passes habilitados para NFC em sua área do cliente

Para nos permitir obter a identificação exclusiva do passe do comprador, você precisa nos informar sobre seu passe habilitado para NFC e o fluxo que deseja usar:

Faça o login na sua Customer Area e selecione o nível da conta onde deseja usar o seu passe habilitado para NFC.
Vá para In-person payments > Terminal settings > Payment features.
Selecione View decrypted e vá para Mobile wallet NFC pass services.
Em Card acquisition VAS mode, selecione uma opção para o fluxo que deseja usar. Esta configuração determina o que o terminal tenta fazer quando você faz uma solicitação de aquisição de cartão e o comprador conecta um dispositivo com uma carteira NFC ao terminal de pagamento.
- Para o fluxo de pagamento e o fluxo single-tap redeem, selecione VAS and payment. Isso obtém os detalhes da passagem NFC e os detalhes do método de pagamento NFC.
- Para o fluxo double-tap redeem, selecione VAS only. Isso obtém os detalhes da passagem NFC quando você faz uma solicitação de aquisição de cartão.
- Existem mais duas opções que listamos aqui para integridade::
  - Se você não quiser coletar os detalhes do passe NFC ao fazer uma solicitação de aquisição de cartão, selecione Payment only.
  - Para deixar a cargo do cliente se os detalhes do passe NFC são coletados com a solicitação de aquisição do cartão, selecione VAS or payment.
Digite o Nome do seu passe.
Em Merchant pass type identifier, insira a ID do tipo de passe que foi gerada quando você criou seu passe NFC.
Usamos isso para pesquisar apenas o seu passe e não os passes de outras organizações que o comprador possa ter em sua carteira móvel. Para um passe da Apple Wallet, tem o formato pass.com.company.pass-name.
Em Vendor type, selecione a empresa responsável pelo protocolo no qual seu passe NFC se baseia. Por exemplo, Apple.
Insira o URL onde as pessoas podem adicionar o passe à carteira móvel.
Usamos isso quando o comprador ainda não tem o seu passe na carteira, para enviar um sinal NFC para que o comprador receba uma mensagem com a URL onde ele pode se inscrever.
Na caixa Private key slot, selecione o slot onde você fornecerá sua chave privada. Por exemplo, Private key 1.
Em Private key slots, vá para o slot que você selecionou na etapa anterior e insira a chave privada para o seu passe NFC.
Esta chave foi gerada quando você criou o passe. Iremos protegê-lo e criptografá-lo em nosso back end. O terminal usa essa chave para descriptografar a mensagem NFC e retornar o ID exclusivo do passe do comprador na resposta.
Para adicionar mais passes habilitados para NFC, selecione Add wallet e repita as etapas para completar as configurações.
Selecione Save.

Depois de concluir a configuração, você está pronto para aceitar seu passe habilitado para NFC com um pagamento, usando o fluxo de pagamento ou o fluxo de resgate.

Use o fluxo de pagamento

Para fazer uma solicitação de pagamento e depois atualizar a conta do passe NFC do cliente:

Faça um PaymentRequest with:

Parameter	Description
`SaleData.TokenRequestedType`	Cliente. Isso retorna o alias do cartão no campo da resposta `TokenValue`. Se você não incluir o `TokenRequestedType`, o alias do cartão será retornado apenas no `AdditionalResponse`.

No PaymentResponse, observe o seguinte:

LoyaltyResult. An array with your NFC enabled passes that are in the shopper's digital wallet. For each pass, there is a LoyaltyAccount object with:

Property	Description
`LoyaltyAccountID.EntryMode`	Indicates how the NFC pass details were obtained.
`LoyaltyAccountID.IdentificationType`	AccountNumber. The type of ID of the shopper's pass.
`LoyaltyAccountID.LoyaltyID`	The unique ID of the shopper's pass.
`LoyaltyBrand`	The vendor protocol that the NFC pass is based on.

Se a resposta não incluir um LoyaltyResult, o cliente ainda não adicionou seu passe habilitado para NFC à carteira móvel.

Usando o LoyaltyID e o alias do cartão retornado na resposta, procure o comprador em seu servidor de passes e programa de fidelidade e atualize os dados do comprador. Por exemplo, os pontos de fidelidade acumulados.

Use o fluxo de resgate

Aqui, descrevemos como você pode primeiro verificar se o cliente tem seu passe habilitado para NFC em seu aplicativo de carteira antes de iniciar o pagamento. Isso permite que você aplique um desconto ou outras vantagens relacionadas ao passe.
Se o cliente precisa tocar em seu telefone ou smartwatch uma segunda vez para concluir o pagamento, depende da configuração da áre a do cliente de seu passe.

Etapa 1: obtenha os detalhes do passe do cliente

Faça um CardAcquisitionRequest com:

Parameter Description

SaleData.TokenRequestedType CLiente. Isso retorna o alias do cartão no campo da resposta TokenValue. Se você não incluir o TokenRequestedType, o alias do cartão será retornado apenas no AdditionalResponse.

CardAcquisitionTransaction

No fluxo de single-tap redeem, esrte objeto deve conter:

TotalAmount: O valor da transação.

No fluxo de double-tap redeem, você pode deixar este objeto vazio se você espera que o valor mude na maioria dos casos, por exemplo, se você fizer uma aquisição de cartão assim que o primeiro item for digitalizado.

No CardAcquisitionResponse, observe o seguinte:

POIData.POITransactionID: O TimeStamp e TransactionID desta solicitação de aquisição de cartão. Você precisará desses dados posteriormente, quando continuar com o pagamento.
AdditionalResponse: Se você já tiver o cliente registrado, este contém a shopperReference.
LoyaltyResult. An array with your NFC enabled passes that are in the shopper's digital wallet. For each pass, there is a LoyaltyAccount object with:

Property	Description
`LoyaltyAccountID.EntryMode`	Indicates how the NFC pass details were obtained.
`LoyaltyAccountID.IdentificationType`	AccountNumber. The type of ID of the shopper's pass.
`LoyaltyAccountID.LoyaltyID`	The unique ID of the shopper's pass.
`LoyaltyBrand`	The vendor protocol that the NFC pass is based on.

Se a resposta não incluir um LoyaltyResult, o cliente ainda não adicionou seu passe habilitado para NFC à carteira móvel.

Usando LoyaltyID e shopperReferenceretornado na resposta, procure o comprador em seu servidor de passes e programa de fidelidade e aplique sua lógica de negócios.
Por exemplo:
- Faça uma solicitação de confirmação de entrada para perguntar ao comprador se ele deseja resgatar pontos de fidelidade.
- Adicione ou recalcule pontos de fidelidade.
- Aplique um desconto.
- Recalcule o valor da transação.
Ou se você ainda não tem o cliente registrado, você pode querer:
- Pergunte ao comprador se ele deseja se inscrever em seu programa de fidelidade e adicionar seu passe à carteira móvel. Se o fizerem, você precisará coletar os detalhes do comprador, como o endereço de e-mail. Você pode usar uma solicitações de entrada para coletar essas informações ou permitir que sua equipe insira as informações no software da caixa registradora.
- Crie um perfil de cliente para o comprador em seu programa de fidelidade e passe o servidor com as informações que você coletou.

Etapa 2: Continue com o pagamento

Faça um PaymentRequest com:

Parameter	Description
`SaleData.TokenRequestedType`	Cliente. Isso retorna o alias do cartão no campo de resposta `TokenValue` field of the response. Consulte Reconhecimento e tokenização do comprador.
`SaleData.SaleToAcquirerData`	Se você ainda não tinha o cliente registrado, use este parâmetro para criar identificadores de cliente em nossa plataforma para que da próxima vez o comprador seja reconhecido. Veja as instruções abaixo.
`PaymentTransaction.AmountsReq`	An object with: `Currency`: A moeda da transação. `RequestedAmount`: O valor final da transação.
`PaymentData.CardAcquisitionReference`	Um objeto que faz referência à aquisição do cartão:: `TimeStamp`: O carimbo de data / hora retornado na reposta `POIData.POITransactionID` de aquisição do cartão. `TransactionID`: O ID da transação retornado na resposta `POIData.POITransactionID` da aquisição do cartão.

Para um cliente não reconhecido, você pode incluir o seguinte em SaleData.SaleToAcquirerData:

shopperEmail: O endereço de e-mail do cliente, se você o coletou..
shopperReference: Sua referência exclusiva para este cliente (comprimento mínimo de três caracteres).
recurringContract: ONECLICK,RECURRING.

Passe o valor SaleToAcquirerData em um dos seguintes formatos:

Opção 1: um objeto JSON convertido em uma string codificada em Base64. Consulte Adicionar informações a um pagamento .
Opção 2: pares de valores-chave codificados por formulário (usando & como separador). Por exemplo:
shopperEmail=S.Hopper@example.com&recurringContract=ONECLICK,RECURRING

O formato que você usa aqui também será o formato do AdditionalResponse que você receber.

No PaymentResponse, observe que você recebe o mesmo LoyaltyResult que no CardAcquisitionResponse.