Aquisição de cartão

Recupere informações do cartão e do cliente antes de efetuar um pagamento.

A aquisição do cartão permite recuperar informações do cartão e do cliente antes de criar uma solicitação de pagamento. Existem várias situações em que isso pode ser benéfico, por exemplo:

Reconhecendo o cartão ou o cliente com base no alias do cartão ou na referência do cliente que você recebe na resposta. Você pode personalizar a experiência de compra ou obter informações através da análise de dados. Consulte Reconhecimento de clientes para obter mais informações.
Realizando uma verificação de elegibilidade para compras isentas de impostos.

Como funciona

Antes de acionar um pagamento:

Você faz uma solicitação de aquisição de cartão (consulte a Etapa 1). Você pode incluir o valor a pagar nesta solicitação.
O terminal de pagamento solicita que o cliente apresente seu cartão.

Para uma transação com chip de contato, o cliente não deve remover o cartão do terminal.
Você aplica sua lógica de negócios após receber a resposta de aquisição do cartão. Por exemplo:
- Você pode usar o país do emissor e o cartão BIN na resposta para determinar se é permitido fazer compras isentas de impostos.
- Você pode verificar se esse cliente é reconhecido. Se não, você pode fazer uma solicitação de entrada para solicitar que eles se inscrevam no seu programa de fidelidade. Se sim, você pode verificar se eles se qualificam para um desconto, presente ou oferta especial.
Você faz uma solicitação de pagamento que inclui a TransactionID a partir da aquisição do cartão (consulte a Etapa 2). Dependendo da sua lógica de negócios, pode ser necessário incluir campos específicos nesta solicitação ou alterar o valor. Para o cliente, a aquisição do cartão e o pagamento subsequente parecerão uma única ação.
O terminal mostra o valor a ser pago e o pagamento é concluído.

Se o valor da solicitação de pagamento for igual ao valor da solicitação de aquisição de cartão, um cliente que use um cartão que realizada transações sem contato precisará tocar no cartão apenas uma vez. Caso contrário, eles precisarão tocar duas vezes no cartão: uma para os detalhes do cartão e outra para o pagamento.

Você também pode cancelar a aquisição do cartão em vez de continuar com um pagamento. Você faria isso, por exemplo, se os dados recuperados do cartão não se qualificarem para uma transação.

Antes de você começar

Antes de iniciar a aquisição do cartão:

Verifique se você criou uma integração que pode efetuar um pagamento.
Em sua Customer Area, vá para Developers > Additional data, selecione os dados necessários para o seu caso de uso. Por exemplo, detalhes recorrentes para reconhecimento do cliente. A API de terminais retorna esses dados no AdditionalResponse.

Etapa 1: Adquirir detalhes do cartão

Para recuperar detalhes do cartão e do cliente antes de efetuar um pagamento:

Faça uma solicitação POST para um endpoint da API de terminais, especificando:

MessageHeader: Segue a estrutura da MessageHeader padrão, explicada nos fundamentos da API de terminais, que incluem:
- ProtocolVersion: 3.0
- MessageClass: Service
- MessageCategory: CardAcquisition
- MessageType: Request
- SaleID: Seu ID exclusivo para a caixa registradora..
- ServiceID: Seu ID exclusivo para esta tentativa de transação, consistindo em 1 a 10 caracteres alfanuméricos. Esse valor precisa ser exclusivo nas últimas 48 horas.
- POIID: ID exclusivo do terminal. Isso indica para qual terminal o pedido será roteado.
CardAcquisitionRequest: O corpo da solicitação de aquisição de cartão, que inclui:
- SaleData.SaleTransactionID.TransactionID: Sua referência exclusiva para esta solicitação.
- SaleData.SaleTransactionID.TimeStamp: Data e hora da solicitação, no formato UTC.
- SaleData.TokenRequestedType
  Optional
  : Customer. Isso retorna o alias do cartão no campo TokenValue da resposta. Se você não incluir o campo TokenRequestedType, o alias do cartão será retornado apenas no AdditionalResponse, e você precisará decodificá-lo para obter o alias do cartão.
- CardAcquisitionTransaction: Este objeto está vazio ou contém:
  - TotalAmount: Valor da transação.
    Se o valor for o mesmo da solicitação de pagamento subsequente, uma transação sem contato não exigirá tocar novamente no cartão para o pagamento
    Você pode alterar o valor posteriormente (na solicitação de pagamento) com base nas informações da caixa registradora, por exemplo, para dar um desconto de fidelidade. 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, poderá optar por omitir o campo TotalAmount.

Para obter uma lista completa dos campos, você pode passar uma solicitação de aquisição de cartão e receber a resposta, consulte a referência de API CardAcquisitionRequest e a referência de API CardAcquisitionResponse.

 {
    "SaleToPOIRequest":{
        "MessageHeader":{
            "ProtocolVersion":"3.0",
            "MessageClass":"Service",
            "MessageCategory":"CardAcquisition",
            "MessageType":"Request",
            "ServiceID":"282",
            "SaleID":"POSSystemID12345",
            "POIID":"V400m-346403161"
        },
        "CardAcquisitionRequest":{
            "SaleData":{
                "SaleTransactionID":{
                    "TransactionID":"369",
                    "TimeStamp":"2021-03-05T12:22:57.449Z"
                },
                "TokenRequestedTypeOptional, returns the card alias in TokenValue":"Customer"
            },
            "CardAcquisitionTransaction":{
                "TotalAmountOptional":16.98
            }
        }
    }
}

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 um pagamento.
- PaymentInstrumentData.CardData: As informações do cartão, que estão disponíveis no próprio cartão. No mínimo, incluindo o PAN mascarado e a data de validade. Se você especificou um TokenRequestedType do Cliente no seu pedido, este também inclui:
  - PaymentToken.TokenValue: O alias do cartão.
- Response.AdditionalResponse: Uma sequência base64. Quando decodificado, este é um objeto JSON com dados adicionais que você pode precisar em sua lógica de negócios, incluindo:
  - alias: O alias do cartão.
  - cardIssuerCountryId e cardBin: dados necessários para determinar a elegibilidade para compras isentas de impostos.
  - shopperReference e shopperEmail: Se incluído, isso significa que você já criou um perfil para esse cliente no seu banco de dados.

Etapa 2: continue com o pagamento

Depois de aplicar sua lógica comercial, você estará pronto para acompanhar a aquisição do cartão com uma solicitação de pagamento:

Faça uma solicitação POST para um endpoint da API de terminais, especificando:

MessageHeader: Segue a estrutura da MessageHeader padrão, explicada nos fundamentos da API de terminais, que incluem:
- ProtocolVersion: 3.0
- MessageClass: Service
- MessageCategory: Payment
- MessageType: Request
- SaleID: Seu ID exclusivo para a caixa registradora..
- ServiceID: Seu ID exclusivo para esta tentativa de transação, consistindo em 1 a 10 caracteres alfanuméricos. Esse valor precisa ser exclusivo nas últimas 48 horas.
- POIID: ID exclusivo do terminal. Esse deve ser o mesmo terminal de pagamento para o qual você direcionou a solicitação de aquisição do cartão.
PaymentRequest: O corpo da solicitação da solicitação de pagamento deve incluir:
- SaleData.SaleTransactionID.TransactionID: Sua referência exclusiva para esta solicitação de pagamento.
- SaleData.SaleTransactionID.TimeStamp: Data e hora da solicitação de pagamento, no formato UTC.
- SaleData.SaleToAcquirerData: Pode ser necessário especificar as tender options ou dados adicionais aqui, dependendo da lógica de negócios. Por exemplo, taxfree.indicator=true para compras isentas de impostos no fluxo de reembolso rápido ou dados de reconhecimento do cliente.
- PaymentTransaction.AmountsReq.Currency: A moeda da transação.
- PaymentTransaction.AmountsReq.RequestedAmount: O valor da transação.
- PaymentData.CardAcquisitionReference: A Timestamp e TransactionID da solicitação de aquisição do cartão. Você recebeu esses dados no objeto POIData.POITransactionID da CardAcquisitionResponse.

 {
   "SaleToPOIRequest":{
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "MessageType":"Request",
         "SaleID":"POSSystemID12345",
         "ServiceID":"2020711110",
         "POIID":"V400m-346403161"
      },
      "PaymentRequest":{
         "SaleData":{
            "SaleTransactionID":{
               "TransactionID":"899",
               "TimeStamp":"2021-03-05T12:23:44.684Z"
            }
         },
         "PaymentTransaction":{
            "AmountsReq":{
               "Currency":"EUR",
               "RequestedAmount":16.98
            }
         },
         "PaymentData":{
            "CardAcquisitionReference":{
               "TimeStampFrom the POITransactionID of the card acquisition":"2021-03-05T12:22:59.000Z",
               "TransactionIDFrom the POITransactionID of the card acquisition":"8ha5001614946979000"
            }
         }
      }
   }
}

Na PaymentResponse note o seguinte:
- PaymentInstrumentData.CardData: Os mesmos detalhes do cartão que você recebeu no CardAcquisitionResponse.
- Response.AdditionalResponse: Uma sequência base64. Quando decodificado, este é um objeto JSON com dados adicionais, incluindo:
  - alias: O alias do cartão.

Cancelando a aquisição do cartão

Se o CardData que você obtiver na CardAcquisitionResponse indica que o cartão não pode ser usado para o pagamento subsequente, você pode cancelar a aquisição do cartão com EnableServiceRequest:

Faça uma solicitação POST para um endpoint da API de terminais, especificando:

MessageHeader: Segue a estrutura da MessageHeader padrão, explicada nos fundamentos da API de terminais, que incluem:
- ProtocolVersion: 3.0
- MessageClass: Service
- MessageCategory: EnableService
- MessageType: Request
- SaleID: Seu ID exclusivo para a caixa registradora.
- ServiceID: Seu ID exclusivo para esta tentativa de transação, consistindo em 1 a 10 caracteres alfanuméricos. Esse valor precisa ser exclusivo nas últimas 48 horas.
- POIID: ID exclusivo do terminal. Isso indica para qual terminal o pedido será roteado.
EnableServiceRequest:
- TransactionAction: AbortTransaction. Isso cancela a transação atual.
- DisplayOutput: Objeto opcional para exibir uma mensagem no terminal. É o mesmo que o objeto DisplayOutput em uma solicitação de exibição.

Para obter uma lista completa dos campos, você pode passar uma solicitação de serviço de ativação e receber a resposta, consulte a referência de API EnableServiceRequest e a referência de API EnableServiceResponse).

 {
   "SaleToPOIRequest":{
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"EnableService",
         "MessageType":"Request",
         "SaleID":"POSSystemID12345",
         "ServiceID":"3020711110",
         "POIID":"V400m-346403161"
      },
      "EnableServiceRequest":{
         "TransactionAction":"AbortTransaction"
      }
   }
}

Se a aquisição do cartão for cancelada com sucesso, você receberá uma EnableServiceResponse que contém:

Response.Result: Success

Continue conforme aplicável, por exemplo, com uma nova solicitação de aquisição de cartão ou uma solicitação de pagamento.

Próximos passos

Reconhecimento do cliente

Obtenha informações e personalize a jornada do cliente.

Coletar inputs

Use o terminal de pagamento para obter informações de seus clientes.

Captura com atraso

Aprenda a usar um atraso de captura para pagamentos no terminal.

Veja também

Compras isentas de impostos