Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

NFC-enabled passes

Learn how to process transactions with NFC-enabled 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.

Você faz uma solicitação de pagamento. Se o cliente pagar com uma carteira móvel habilitada para NFC, você será informado na resposta do pagamento se o cliente tem o seu passe na carteira móvel. Se o fizerem, a resposta do pagamento incluirá o ID exclusivo do passe do cliente para que você possa atualizar a conta do cliente.

Primeiro, você faz uma solicitação de aquisição de cartão com um valor. O terminal pede ao cliente que apresente seu cartão. Quando o cliente toca seu dispositivo móvel habilitado para NFC no terminal de pagamento, o terminal pesquisa a carteira móvel no dispositivo para:

  • Seus passes.
  • Os detalhes do método de pagamento (o cartão de crédito ou débito vinculado à carteira).

Se o cliente tiver o seu passe, a resposta de aquisição do cartão incluirá o ID exclusivo do passe do comprador para que você possa consultar a conta do cliente. Você pode então, por exemplo:

  • Faça uma solicitação de entrada para perguntar ao comprador se ele deseja resgatar pontos de fidelidade.
  • Adicione ou recalcule pontos de fidelidade.
  • Aplique um desconto.

Em seguida, você faz uma solicitação de pagamento do valor final. Deve ser igual ou inferior ao valor de aquisição do cartão.

Nesse fluxo, o cliente conecta seu dispositivo móvel ao terminal apenas uma vez, pois a aquisição do cartão pesquisa os detalhes do passe e da forma de pagamento ao mesmo tempo.

Você primeiro faz uma solicitação de aquisição de cartão com ou sem um valor. O terminal pede ao cliente que apresente seu cartão. Quando o cliente liga seu dispositivo móvel habilitado para NFC ao terminal de pagamento, o terminal consulta a carteira móvel do dispositivo para seus passes. Se o cliente tiver o seu passe, a resposta de aquisição do cartão incluirá o ID exclusivo do passe do cliente para que você possa consultar a conta do comprador. Você pode então, por exemplo:

  • Faça uma solicitação de entrada para perguntar ao cliente se ele deseja resgatar pontos de fidelidade.
  • icione ou recalcule pontos de fidelidade.
  • Aplique um desconto.

Em seguida, você faz uma solicitação de pagamento do valor final. O terminal pede ao cliente novamente para apresentar seu cartão. O cliente pode escolher pagar com sua carteira móvel e tocar seu dispositivo móvel no terminal uma segunda vez ou usar um método de pagamento diferente.

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

  1. 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.

  2. 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.

  3. Make sure that you have built a Terminal API integration that can make a payment.
  4. Tie in your loyalty program with your NFC-enabled passes. To learn more about how to link a customer in your loyalty program to a transaction, refer to 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:

  1. Faça o login na sua Customer Area e selecione o nível da conta onde deseja usar o seu passe habilitado para NFC.
  2. Vá para Point of sale > Terminal settings > Payment features.
  3. Selecione View decrypted e vá para Mobile wallet NFC pass services.
  4. 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.

  5. Digite o Nome do seu passe.
  6. 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.
  7. Em Vendor type, selecione a empresa responsável pelo protocolo no qual seu passe NFC se baseia. Por exemplo, Apple.
  8. 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.
  9. Na caixa Private key slot, selecione o slot onde você fornecerá sua chave privada. Por exemplo, Private key 1.
  10. 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.
  11. Para adicionar mais passes habilitados para NFC, selecione Add wallet e repita as etapas para completar as configurações.
  12. 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:

  1. 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.
    {
        "SaleToPOIRequest": {
            "MessageHeader": {
                "ProtocolVersion": "3.0",
                "MessageClass": "Service",
                "MessageCategory": "Payment",
                "MessageType": "Request",
                "ServiceID": "s9wrxa",
                "SaleID": "POSSystemID12345",
                "POIID": "V400m-324689265"
            },
            "PaymentRequest": {
                "SaleData": {
                    "SaleTransactionID": {
                        "TransactionID": "a1b2c3",
                        "TimeStamp": "2020-06-16T16:13:16"
                    },
                    "TokenRequestedType": "Customer"
                },
                "PaymentTransaction": {
                    "AmountsReq": {
                        "Currency": "EUR",
                        "RequestedAmount": 10.99
                    }
                }
            }
        }
    }
    {
        "SaleToPOIResponse": {
            "PaymentResponse": {
                "POIData": {
                    "POITransactionID": {
                        "TimeStamp": "2020-06-15T16:13:16.000Z",
                        "TransactionID": "fanx001580400796015.8535804008080700"
                    },
                    "POIReconciliationID": "1000"
                },
                "SaleData": {
                    "SaleTransactionID": {
                        "TimeStamp": "2020-06-15T16:13:16.000Z",
                        "TransactionID": "a1b2c3"
                    }
                },
                "PaymentReceipt": [...],
                "PaymentResult": {
                    "AuthenticationMethod": [
                        "SecuredChannel"
                    ],
                    "OnlineFlag": true,
                    "PaymentAcquirerData": {...},
                        "MerchantID": "YOUR_MERCHANT_ACCOUNT"
                    },
                    "PaymentInstrumentData": {
                        "CardData": {
                            "EntryMode": [
                                "Contactless"
                            ],
                            "PaymentToken": {
                                "TokenRequestedType": "Customer",
                                "TokenValue": "G526627978654924"
                            },
                            "PaymentBrand": "visa",
                            "MaskedPan": "481749 **** 1108",
                            "CardCountryCode": "076",
                            "SensitiveCardData": {
                                "CardSeqNumb": "00",
                                "ExpiryDate": "1223"
                            }
                        },
                        "PaymentInstrumentType": "Card"
                    },
                    "AmountsResp": {
                        "AuthorizedAmount": 10.99,
                        "Currency": "EUR"
                    }
                },
                "LoyaltyResult": [
                    {
                        "LoyaltyAccount": {
                            "LoyaltyAccountID": {
                                "IdentificationType": "AccountNumber",
                                "EntryMode": [
                                    "Contactless"
                                ],
                                "LoyaltyID": "rEqQFLnckxJ3jCvmQoLmBh"
                            },
                            "LoyaltyBrand": "AppleVAS"
                        }
                    }
                ],
                "Response": {
                    "Result": "Success",
                    "AdditionalResponse": "..."
                }
            },
            "MessageHeader": {...}
        }
    }

    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.IdentificationType AccountNumber. The type of ID of the shopper's pass.
      LoyaltyAccountID.EntryMode Contactless. Indicates how the NFC pass details were obtained.
      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.

  2. 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

  1. 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.

    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"CardAcquisition",
                "MessageType":"Request",
                "ServiceID":"0305Acq",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-346403161"
            },
            "CardAcquisitionRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"0422024",
                        "TimeStamp":"2020-06-19T12:18:04"
                    },
                    "TokenRequestedType":"Customer"
                },
                "CardAcquisitionTransaction":{
                    "TotalAmount": 14.98
                }
            }
        }
    }
    {
        "SaleToPOIResponse": {
            "CardAcquisitionResponse": {
                "POIData": {
                    "POITransactionID": {
                        "TimeStamp": "2020-06-19T10:18:48.000Z",
                        "TransactionID": "8ha5001592561928000"
                    },
                    "POIReconciliationID": "1000"
                },
                "SaleData": {
                    "SaleTransactionID": {
                        "TimeStamp": "2020-06-19T12:18:04.000Z",
                        "TransactionID": "0422024"
                    }
                },
                "PaymentInstrumentData": {
                    "CardData": {
                        "PaymentToken": {
                            "TokenRequestedType": "Customer",
                            "TokenValue": "M469509594859802"
                        },
                        "PaymentBrand": "mc",
                        "MaskedPan": "541333 **** 9999",
                        "CardCountryCode": "528",
                        "SensitiveCardData": {
                            "ExpiryDate": "0228"
                        }
                    },
                    "PaymentInstrumentType": "Card"
                },
                "Response": {
                    "Result": "Success",
                    "AdditionalResponse": "..."
                },
                "LoyaltyAccount": [
                    {
                        "LoyaltyAccountID": {
                            "IdentificationType": "AccountNumber",
                            "EntryMode": [
                                "Contactless"
                            ],
                            "LoyaltyID": "rEqQFLnckxJ3jCvmQoLmBh"
                        },
                        "LoyaltyBrand": "AppleVAS"
                    }
                ]
            },
            "MessageHeader": {...}
        }
    }
  2. 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.IdentificationType AccountNumber. The type of ID of the shopper's pass.
      LoyaltyAccountID.EntryMode Contactless. Indicates how the NFC pass details were obtained.
      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.

  3. 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

  1. 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.

    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"Payment",
                "MessageType":"Request",
                "ServiceID":"0305p",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-346403161"
            },
            "PaymentRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TimeStamp": "2020-06-19T12:23:04.000Z",
                        "TransactionID": "042208"
                    },
                    "SaleToAcquirerData":"shopperEmail=S.Hopper@example.com&shopperReference=YOUR_UNIQUE_SHOPPER_ID",
                    "TokenRequestedType":"Customer"
                },
                "PaymentTransaction":{
                    "AmountsReq":{
                        "Currency":"EUR",
                        "RequestedAmount":14.48
                    }
                },
                "PaymentData":{
                    "CardAcquisitionReference":{
                        "TimeStamp": "2020-06-19T10:21:27.000Z",
                        "TransactionID": "8ha5001592562087001"
                    }
                }
            }
        }
    }
    {
        "SaleToPOIResponse": {
            "PaymentResponse": {
                "POIData": {
                    "POITransactionID": {
                        "TimeStamp": "2020-06-19T10:24:03.000Z",
                        "TransactionID": "8ha5001592562087001.8825925622358203"
                    },
                    "POIReconciliationID": "1000"
                },
                "SaleData": {
                    "SaleTransactionID": {
                        "TimeStamp": "2020-06-19T12:23:04.000Z",
                        "TransactionID": "042208"
                    }
                },
                "PaymentReceipt": [...],
                "PaymentResult": {
                    "OnlineFlag": true,
                    "PaymentAcquirerData": {...},
                        "MerchantID": "YOUR_MERCHANT_ACCOUNT"
                    },
                    "PaymentInstrumentData": {
                        "CardData": {
                            "EntryMode": [
                                "Contactless"
                            ],
                            "PaymentToken": {
                                "TokenRequestedType": "Customer",
                                "TokenValue": "M469509594859802"
                            },
                            "PaymentBrand": "mc",
                            "MaskedPan": "541333 **** 9999",
                            "CardCountryCode": "056",
                            "SensitiveCardData": {
                                "CardSeqNumb": "83",
                                "ExpiryDate": "0228"
                            }
                        },
                        "PaymentInstrumentType": "Card"
                    },
                    "AmountsResp": {
                        "AuthorizedAmount": 14.48,
                        "Currency": "EUR"
                    },
                },
                "LoyaltyResult": [
                    {
                        "LoyaltyAccount": {
                            "LoyaltyAccountID": {
                                "IdentificationType": "AccountNumber",
                                "EntryMode": [
                                    "Contactless"
                                ],
                                "LoyaltyID": "rEqQFLnckxJ3jCvmQoLmBh"
                            },
                            "LoyaltyBrand": "AppleVAS"
                        }
                    }
                ],
                "Response": {
                    "Result": "Success",
                    "AdditionalResponse": "...&alias=M469509594859802&...recurring.shopperReference=YOUR_UNIQUE_SHOPPER_ID&...shopperReference=YOUR_UNIQUE_SHOPPER_ID&shopperEmail=S.Hopper%40example.com&..."
                }
            },
            "MessageHeader": {...}
        }
    }

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

Veja também