Lidando com erros

Para poder resolver problemas com suas solicitações, você precisa saber como a API de Terminais informa o status de processamento da sua solicitação. Isso é comunicado no objeto Response da resposta da API, que possui:

• Result: Um dos seguintes valores:

  • Success: A solicitação foi bem-sucedida / a transação foi aprovada.
  • Partial: O valor da transação foi parcialmente aprovado.

  • Failure: A solicitação ou transação não foi bem-sucedida. Os campos Response restantes fornecem mais informações sobre o erro, para permitir que você determine como lidar com ele.

• ErrorCondition: Este campo é incluído quando a solicitação ou transação falha, este também indica a causa da falha.

• AdditionalResponse: Mais informações sobre a condição de erro. Você receberá pares de valores-chave codificados em formulário ou uma cadeia codificada em Base64 que decodifica para um objeto JSON.

Agora vamos ver o que você pode fazer quando:

• A solicitação falhou porque era inválida.
• Você fez uma solicitação de pagamento, mas não recebeu um resultado.
• O resultado da sua solicitação de pagamento indica que a transação falhou.

Formato de mensagem inválido

Um objeto Response com Result Failure e ErrorCondition MessageFormat indicam que houve um erro na solicitação que você enviou. Você deverá prossegfuir da seguinte forma:

1. 1. Determine o que causou o erro, com base na message, warnings, ou errors no AdditionalResponse. Por exemplo, um campo obrigatório ausente ou um campo inesperado.

   O exemplo a seguir é para uma resposta indicando que o campo Currency está ausente na solicitação de pagamento:

   {
   ...
      "Response":{
         "Result":"Failure",
         "AdditionalResponse": "errors=At%20SaleToPOIRequest.PaymentRequest.PaymentTransaction.AmountsReq%2c%20field%20Currency%3a%20Missing",
         "ErrorCondition":"MessageFormat"
      }
   ...
   }

2. Consulte a referência Terminal API se necessário, corrija manualmente sua solicitação e tente novamente.

Formato JSON inválido

Se sua solicitação de API não contiver um objeto JSON válido, você receberá uma resposta HTTP Bad JSON que especifica o número da linha e uma descrição do problema:

["Bad JSON:LINE_NUMBER: DESCRIPTION"]

• Corrija manualmente o erro JSON na linha mencionada na resposta HTTP e tente novamente.

Serviço indisponível

Um objeto Response com Result Failure e ErrorCondition UnavailableService indica que não foi possível implementar sua solicitação. Proceda da seguinte forma:

1. Determinar o que causou o erro, com base na message, warnings, ou errors no AdditionalResponse. Por exemplo:

   • Você tentou usar a funcionalidade que o terminal de pagamento não suporta.
   • Você tentou usar uma ProtocolVersion que o terminal não pode gerenciar.
   • Você tentou usar funcionalidades que não são suportadas.

   O exemplo a seguir é para uma resposta indicando que há uma incompatibilidade entre as versões do protocolo (2.0 na solicitação e 3.0 no terminal):

   {
   ...
      "Response": {
         "Result": "Failure",
         "AdditionalResponse": "message=Sale%20Protocol%20Version%202.0%20mismatch%2c%20Version%20implemented%3a%203.0",
         "ErrorCondition": "UnavailableService"
      }
   ...
   }

2. Dependendo da causa do erro, corrija manualmente sua solicitação e envie-a novamente. Por exemplo, após receber a resposta de falha acima, você especificaria a mesma versão de protocolo que o terminal suporta.

Nenhum resultado recebido

Recomendamos que sua integração solicite automaticamente o status de uma transação, sempre que falhar em receber uma resposta da transação.

As solicitações de pagamento expiram após 120 segundos. Se você não receber uma resposta de pagamento (ou uma resposta indicando um tempo limite) após 150 segundos e a conexão de rede não cair, sua integração deverá solicitar automaticamente o status da transação.

Se você não receber um resultado da transação, nem de forma síncrona nem assíncrona, proceda da seguinte forma:

1. Faça uma TransactionStatusRequest (consulte Verificar status da transação para obter detalhes).

2. Determine sua próxima ação com base na TransactionStatusResponse.Response:

   Resposta	Descrição	Ação
   Result Success	A transação foi processada.	Use RepeatedResponseMessageBody para determinar como processar a transação.
   ErrorCondition InProgress	O terminal de pagamento está aguardando uma resposta do cliente ou há um atraso no emissor do cartão.	Continue fazendo uma solicitação de status de transação para esta transação a cada cinco segundos até receber uma resposta indicando que a transação foi processada.
   ErrorCondition NotFound	Causas Possíveis: Os detalhes que você especificou na solicitação de status da transação estão incorretos. Não recebemos sua solicitação; talvez sua conexão tenha caído após o envio da solicitação.	Ações possíveis: Forneça os detalhes da transação original em MessageReference sua solicitação de status de transação. o Repita a transação original.

Pagamento recusado

Quando uma PaymentRequest resulta em um objeto Response com Result Failure e uma das condições de erro listadas abaixo, a transação foi recusada. O AdditionalResponse tem mais informações sobre por que a transação foi recusada:

• refusalReason: Nosso mapeamento da resposta bruta que recebemos de adquirentes e emissores, para explicar por que a transação falhou.

• message: Nosso mapeamento do código de resposta que recebemos de adquirentes e emissores.

  Aqui está um exemplo de resposta de falha para um pagamento recusado:

  {
  ...
     "Response": {
        "Result": "Failure",
        "AdditionalResponse": "refusalReason=214%Declined%20online...&message=CANCELLED...",
        "ErrorCondition": "Refusal"
     }
  ...
  }

Quando sua solicitação de pagamento é recusada, você precisa determinar se pode tentar novamente:

1. Marque a caixa ErrorCondition no PaymentResponse.Response, porque em muitos casos isso já indica se você pode tentar novamente a transação.

   Condição de erro	Repetir?
   Aborted
   DeviceOut
   NotAllowed
   UnreachableHost
   WrongPIN
   Cancel	Veja o próximo passo
   InvalidCard	Veja o próximo passo
   Refusal	Veja o próximo passo

2. Para as condições de Cancel, InvalidCard, e Refusal, verifique a refusalReason e message na AdditionalResponse conforme mostrado nas tabelas a seguir.

   Para obter mais informações, consulte nossa documentação de referência por motivos de recusa. Se você ativou o recebimento do campo refusalReasonRaw no AdditionalResponse, consulte também nossa documentação de referência para obter respostas do adquirente.

   o refusalReasonRaw fornece informações adicionais. Mas se você basear seu código nele, isso poderá prejudicar sua integração, pois os adquirentes e emissores às vezes alteram suas respostas brutas sem notificação.

3. Se aplicável, tente novamente a transação.

Comparação de condição de erro

The table below compares error conditions and troubleshooting steps specific to making a PaymentRequest, TransactionStatusRequest, or ReversalRequest (a referenced refund).

Veja também