Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Lidando com erros

Aprenda como resolver erros da API de terminais e como lidar com pagamentos recusados.

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. 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"
       }
    ...
    }
  1. 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 -white_check_mark-
    DeviceOut -white_check_mark-
    NotAllowed -x-
    UnreachableHost -white_check_mark-
    WrongPIN -white_check_mark-
    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.

    Condição de erro Motivo de recusa mensagem Repetir?
    Cancelar Aprovado APROVADO -x-
    Cancelar (todos os outros motivos de recusa) (todas as outras mensagens) -white_check_mark-
    Condição de erro Motivo de recusa mensagem Repetir?
    InvalidCard
    Falha na autenticação dos dados do cartão DECLINED -x-
    InvalidCard Nenhuma conta corrente disponível no cartão NO_CHECKING_ACCOUNT_AVAILABLE_ON_CARD -white_check_mark-
    InvalidCard Nenhuma conta poupança disponível no cartão NO_SAVINGS_ACCOUNT_AVAILABLE_ON_CARD -white_check_mark-
    ErrorCondition refusalReason message Retry?
    Refusal CVC Declined CVC_DECLINED -white_check_mark-
    Refusal Refused DECLINED -white_check_mark-
    Refusal Declined Non Generic DECLINED -white_check_mark-
    Refusal Acquirer Error ERROR -white_check_mark-
    Refusal Expired Card CARD_EXPIRED -white_check_mark-
    Refusal Issuer Suspected Fraud ISSUER_SUSPECTED_FRAUD -x-
    Refusal Not enough balance NOT_ENOUGH_BALANCE -white_check_mark-
    Refusal Not Submitted NOT_SUBMITTED -white_check_mark-
    Refusal Not supported NOT_SUPPORTED -white_check_mark-
    Refusal Pin tries exceeded PIN_TRIES_EXCEEDED -white_check_mark-
    Refusal Pin validation not possible PIN_VALIDATION_NOT_POSSIBLE -x-
    Refusal Restricted Card RESTRICTED_CARD -x-
    Refusal Withdrawal count exceeded WITHDRAWAL_COUNT_EXCEEDED -white_check_mark-
    Refusal Withdrawal amount exceeded WITHDRAWAL_AMOUNT_EXCEEDED -white_check_mark-
    Refusal Transaction Not Permitted TRANSACTION_NOT_PERMITTED -white_check_mark-
    Refusal Always refused DECLINED -x-
    Refusal Amount too low to be accepted by Card Network DECLINED -x-
    Refusal Card is blocked BLOCK_CARD -x-
    Refusal declined DECLINED -white_check_mark-
    Refusal Timeout waiting for card after contactless fallback CONTACTLESS_FALLBACK -white_check_mark-
    Refusal Card requires online pin PIN_REQUIRED -white_check_mark-
    Refusal Mobile PIN required MOBILE_PIN_REQUIRED -white_check_mark-

    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