Verifique o status da transação

Ao fazer uma transação, um problema técnico ou de comunicação pode impedir que sua caixa registradora receba a resposta. Sem essa resposta, sua equipe poderá não conseguir verificar se a transação foi processada ou qual foi seu resultado. Eles também podem tentar cancelar ou reembolsar a transação ou arriscar uma transação duplicada.

Em vez disso, sua integração deve solicitar o status da transação para verificar se a transação:

• Foi processada
• Está em progresso
• Não foi encontrada

Se a transação foi processada, você também receberá a resposta da transação original, indicando o resultado.

Antes de começar

Antes de verificar o status de uma transação com nossa API de terminais, certifique-se de:

1. Ler e entender os fundamentos da API de terminal.
2. Realizar uma transação uma transação, como um pagamento.

Solicitar status da transação

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.

Para solicitar o status de uma transação, sua caixa registradora deve:

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

  • O objeto MessageHeader. Este segue a estrutura MessageHeader padrão, explicada nos fundamentos da API de terminais:

    • ProtocolVersion: 3.0
    • MessageClass: Service
    • MessageCategory: TransactionStatus
    • MessageType: Request
    • SaleID: Seu ID exclusivo para a caixa registradora que faz a solicitação de status da transação.
    • ServiceID: Seu ID exclusivo para esta tentativa de transação, consistindo em 1 a 10 caracteres alfanuméricos. Esse valor deve ser exclusivo nas últimas 48 horas.

    • POIID: ID exclusivo do terminal

  • TransactionStatusRequest:

    • ReceiptReprintFlag: true

    • DocumentQualifier: Receba os dados que deseja receber na resposta. Pode ser um ou ambos:

      • CashierReceipt: Recibo de caixa, incluindo dados de assinatura.

      • CustomerReceipt: Recibo do cliente.

    • MessageReference: Este objeto é opcional. Se você não incluí-lo, receberá o status da transação mais recente feita pelo terminal.

      • SaleID: A SaleID da caixa registradora que fez a transação original.
      • ServiceID: The ServiceID of the original transaction.

      • MessageCategory: O tipo da transação original:

        • Payment: Pedido de pagamento.
        • Reversal: Solicitação de reembolso.
        • StoredValue: Solicitação para ativar ou carregar saldo em um cartão vale presente.

O exemplo abaixo mostra como você solicitaria o status de um pagamento com o ServiceID 29235.

``` json
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "MessageClass": "Service",
      "MessageCategory": "TransactionStatus",
      "MessageType": "Request",
      "SaleID": "POSSystemID12345",
      "ServiceID": "29245",
      "POIID": "V400m-324688179"
    },
    "TransactionStatusRequest": {
      "ReceiptReprintFlag": true,
      "DocumentQualifier": [
        "CashierReceipt",
        "CustomerReceipt"
      ],
      "MessageReference": {
        "SaleID": "POSSystemID12345",
        "ServiceID": "29235",
        "MessageCategory": "Payment"
      }
    }
  }
}
```

!! Para obter uma lista completa dos campos que você pode passar ao solicitar um status de transação, consulte a [referência TransactionStatusRequest API](/point-of-sale/basic-tapi-integration/verify-transaction-status/transactionstatusrequestnexo).

A resposta contém a TransactionStatusResponse.Response.Result, indicando se a transação foi processada:

• Success : A transação foi processada. A resposta da transação original também é fornecida.

• Failure: A transação não foi processada. O motivo é indicado pelo ErrorCondition:

  • InProgress : A transação ainda está sendo processada.

  • NotFound : Não conseguimos encontrar a transação.

Um exemplo de cada resultado é fornecido abaixo.

Transação processada

A TransactionStatusResponse.Response.Result Success indica que a transação foi processada. Use a resposta da transação original, fornecida no objeto RepeatedResponseMessageBody, para determinar como processar a transação.

A resposta de exemplo abaixo indica que esta transação, um pagamento, foi processada. O objeto RepeatedResponseMessageBody na resposta indica que o pagamento foi bem sucedido (PaymentResponse.Response.Result Success).

{
  "SaleToPOIResponse":{
    "TransactionStatusResponse":{
      "MessageReference":{
        "SaleID":"POSSystemID12345",
        "MessageCategory":"Payment",
        "ServiceID":"29235"
      },
      "Response":{
        "Result":"Success"
      },
      "RepeatedMessageResponse":{
        "RepeatedResponseMessageBody":{
          "PaymentResponse":{
            "POIData":{
              "POITransactionID":{
                "TimeStamp":"2019-03-07T10:11:04+00:00",
                "TransactionID":"4rVu001559643049000.981517998282382K"
              },
              "POIReconciliationID":"1000"
            },
            "SaleData":{
              "SaleTransactionID":{
                "TimeStamp":"2019-03-07T10:11:04+00:00",
                "TransactionID":"29235"
              }
            },
            "PaymentReceipt":[...],
            "PaymentResult":{...},
            "Response":{
              "Result":"Success",
              "AdditionalResponse":"...pspReference=981517998282382K..."
            }
          }
        },
        "MessageHeader":{
          "SaleID":"POSSystemID12345",
          "MessageClass":"Service",
          "MessageCategory":"Payment",
          "ServiceID":"29235",
          "POIID":"V400m-324688179",
          "MessageType":"Response"
        }
      }
    },
    "MessageHeader":{
      "SaleID":"POSSystemID12345",
      "MessageClass":"Service",
      "MessageCategory":"TransactionStatus",
      "ServiceID":"29235status",
      "POIID":"V400m-324688179",
      "MessageType":"Response"
    }
  }
}

Transação em andamento

Um TransactionStatusResponse.Response.ErrorCondition of InProgress indica que a transação ainda está sendo processada. Geralmente, isso ocorre porque o terminal aguarda a entrada do cliente (por exemplo, uma solicitação de conversão de moeda), mas também pode resultar de um atraso com o emissor do cartão.

Recomendamos que você continue solicitando o status desta transação novamente a cada 5 segundos, até receber uma resposta indicando que a transação foi processada.

A resposta de exemplo abaixo indica que esta transação ainda está em andamento.

{
  "SaleToPOIResponse":{
    "MessageHeader":{
      "MessageType":"Response",
      "MessageCategory":"TransactionStatus",
      "MessageClass":"Service",
      "ProtocolVersion":"3.0",
      "POIID":"V400m-324688179",
      "SaleID":"POSSystemID12345",
      "ServiceID":"29235status"
    },
    "TransactionStatusResponse":{
      "Response":{
        "Result":"Failure",
        "ErrorCondition":"InProgress",
        "AdditionalResponse":"message=Uncompleted%20transaction"
      }
    }
  }
}

Transação não encontrada

Um TransactionStatusResponse.Response.ErrorCondition NotFound indica que não conseguimos encontrar a transação com o SaleID e ServiceID que você especificou. Isso significa que:

• O POIID, SaleID ou ServiceID especificou na solicitação de status da transação estão incorretos. Verifique se você forneceu o POIID, SaleID, e ServiceID a partir da transação original noTransactionStatusRequest.MessageReference.
• Não recebemos sua solicitação de transação. Isso pode ser devido a uma queda na conexão com a Internet. Você pode tentar a transaçã original novamente.

A resposta de exemplo abaixo indica que esta transação não foi encontrada.

{
  "SaleToPOIResponse":{
    "MessageHeader":{
      "POIID":"V400m-324688179",
      "SaleID":"POSSystemID12345",
      "ServiceID":"29235-status",
      "ProtocolVersion":"3.0",
      "MessageCategory":"TransactionStatus",
      "MessageType":"Response",
      "MessageClass":"Service"
    },
    "TransactionStatusResponse":{
      "Response":{
        "ErrorCondition":"NotFound",
        "Result":"Failure",
        "AdditionalResponse":"message=Message%20with%20category%2018%20not%20Found%2c%20last%20such%20Request%20has%20SaleID%3dPOSSystemID12344%20ServiceID%29233"
      }
    }
  }
}

Veja também