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.

   Cancel InvalidCard Refusal

   Cancel InvalidCard Refusal

   Condição de erro	Motivo de recusa	mensagem	Repetir?
   Cancelar	Aprovado	APROVADO
   Cancelar	(todos os outros motivos de recusa)	(todas as outras mensagens)

   Condição de erro	Motivo de recusa	mensagem	Repetir?
   InvalidCard
   Falha na autenticação dos dados do cartão	DECLINED
   InvalidCard	Nenhuma conta corrente disponível no cartão	NO_CHECKING_ACCOUNT_AVAILABLE_ON_CARD
   InvalidCard	Nenhuma conta poupança disponível no cartão	NO_SAVINGS_ACCOUNT_AVAILABLE_ON_CARD

   ErrorCondition	refusalReason	message	Retry?
   Refusal	CVC Declined	CVC_DECLINED
   Refusal	Refused	DECLINED
   Refusal	Declined Non Generic	DECLINED
   Refusal	Acquirer Error	ERROR
   Refusal	Expired Card	CARD_EXPIRED
   Refusal	Issuer Suspected Fraud	ISSUER_SUSPECTED_FRAUD
   Refusal	Not enough balance	NOT_ENOUGH_BALANCE
   Refusal	Not Submitted	NOT_SUBMITTED
   Refusal	Not supported	NOT_SUPPORTED
   Refusal	Pin tries exceeded	PIN_TRIES_EXCEEDED
   Refusal	Pin validation not possible	PIN_VALIDATION_NOT_POSSIBLE
   Refusal	Restricted Card	RESTRICTED_CARD
   Refusal	Withdrawal count exceeded	WITHDRAWAL_COUNT_EXCEEDED
   Refusal	Withdrawal amount exceeded	WITHDRAWAL_AMOUNT_EXCEEDED
   Refusal	Transaction Not Permitted	TRANSACTION_NOT_PERMITTED
   Refusal	Always refused	DECLINED
   Refusal	Amount too low to be accepted by Card Network	DECLINED
   Refusal	Card is blocked	BLOCK_CARD
   Refusal	declined	DECLINED
   Refusal	Timeout waiting for card after contactless fallback	CONTACTLESS_FALLBACK
   Refusal	Card requires online pin	PIN_REQUIRED
   Refusal	Mobile PIN required	MOBILE_PIN_REQUIRED

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

Condição de erro	PaymentRequest	TransactionStatusRequest	ReversalRequest
Aborted	Consulte Pagamento recusado	não se aplica	Opcionalmente, tente novamente
Cancel	Consulte Pagamento recusado	não se aplica	não se aplica
DeviceOut	Consulte Pagamento recusado	Aguarde e tente novamente	Aguarde e tente novamente
InProgress	não se aplica	Consulte Nenhum resultado recebido	não se aplica
InvalidCard	Consulte Pagamento recusado	não se aplica	não se aplica
Formato de mensagem inválido
NotAllowed	Consulte Pagamento recusado	Aguarde e tente novamente	Aguarde e tente novamente ou tente um dispositivo diferente
NotFound	Recuperação manual	Consulte Nenhum resultado recebido	Recuperação manual
Refusal	Consulte Pagamento recusado	não se aplicae	Recuperação manual
Serviço indisponível
UnreachableHost	Consulte Pagamento recusado)	Repetir	Repetir
WrongPIN	Consulte Pagamento recusado	não se aplica	não se aplica

Veja também