Respostas e erros

Toda resposta traz clientTransactionId, status e protocolVersion. O status diz o que aconteceu; o error diz por quê; os demais campos aparecem conforme a operação.

Campo	Quando vem
status	Sempre
error	Em declined, cancelled, busy, error e unknown
receipt	Em approved de venda e estorno, e em declined quando a adquirente gera comprovante da recusa
transactions, nextCursor	Em consultas
terminal	Em terminal_status
users, user	Nas operações de usuários locais

Status

Status	Significado	Ação do seu app
approved	Operação concluída	Concluir; o comprovante vem em receipt
declined	Recusada pelo emissor ou adquirente	Mostrar error.message; o cliente pode tentar outro meio
cancelled	Interrompida pelo operador ou portador no terminal	Voltar ao carrinho
busy	Havia outra operação em curso; nada foi executado	Tentar de novo em instantes
error	Falhou antes de virar transação, ou o desfecho é desconhecido	Decidir por error.code (tabela abaixo)
unknown	Status de uma versão mais nova do host	Mostrar error.message sem tomar decisão de negócio

O atalho response.isApproved equivale a status == APPROVED.

Comprovante (receipt)

Campo	Conteúdo
transactionId	Identificador da transação no gateway. Use-o em estorno, reimpressão e consulta
amountInCents, paymentMethod, transactionType, installments	Dados da venda
authorizationCode, nsu, timestampIso	Dados da autorização
cardBrand, cardBin, cardLastDigits	Bandeira, 6 primeiros e 4 últimos dígitos. O número completo nunca sai do terminal
merchantName, merchantDocument, terminalId, terminalSerialNumber	Identificação do estabelecimento e do terminal
merchantReceipt, customerReceipt	Vias do lojista e do cliente, já formatadas para impressão
voucherBalanceInCents	Saldo do voucher, quando a adquirente informa. null significa não informado
acquirer	Nome do adquirente que processou (por exemplo, pagseguro). null significa não informado. No estorno, é o adquirente da venda original

Objeto de erro

Campo	Uso
code	Código estável do protocolo. Use este campo para lógica
message	Texto pronto para o operador, no idioma do terminal
vendorCode	Código bruto do fabricante ou do adquirente. Só para log e suporte, porque muda junto com o kernel do fabricante

Nunca tome decisão pelo texto de message: ele pode mudar entre versões do host.

Códigos de erro

Código	Significado	Ação recomendada
no_response	Gerado no seu app: o host não respondeu ou a resposta veio ilegível	Recuperar o desfecho antes de cobrar de novo (Recuperação)
operation_timeout	Teto de tempo atingido (a transação pode seguir viva no terminal), ou cartão não apresentado no prazo	Recuperar; só cobrar de novo se não houve aprovação
terminal_busy	Outra operação em curso, inclusive uma anterior que ainda pode devolver desfecho	Aguardar; se houver id pendente, recuperar
unauthorized_caller	App não credenciado	Pedir credenciamento com requestAuthorization
authorization_denied	Credenciamento recusado, ou senha de Supervisor não confirmada	Parar; é decisão humana
terminal_not_initialized	Terminal ainda não ativado, ou ativado mas sem as tabelas de pagamento carregadas	Abrir a ativação com activateTerminal(). Se a resposta da própria ativação for esta, o terminal já está cadastrado: verificar a rede dele
malformed_request	JSON inválido, campo obrigatório ausente, action diferente da operação, metadata fora dos limites ou com número de cartão, bloco de impressão desconhecido, ou valor e parcelas fora das regras do terminal (mínimo, máximo, limite de contactless)	Corrigir a requisição; não é caso de retentativa
unsupported_operation	Operação que esta versão do host não executa	Esconder a função ou atualizar o host
unsupported_protocol_version	O host não fala a versão enviada	Atualizar o host ou o contrato
unsupported_payment_method	Meio de pagamento não habilitado no terminal	Oferecer outro meio
operation_cancelled	Interrompida no terminal, ou transação desfeita	Voltar ao carrinho
card_read_error	Falha na leitura do cartão	Pedir para apresentar o cartão de novo
declined_by_issuer	Recusa do emissor	Mostrar a mensagem; oferecer outro meio
network_error	Falha de comunicação com o gateway: sem rede, terminal não autorizado no gateway, sessão expirada, requisição recusada ou falha do servidor	Verificar a conexão do terminal e tentar de novo; se persistir, acionar o suporte
refund_exceeds_balance	Estorno maior que o saldo da transação	Ajustar o valor
transaction_not_found	Id sem registro para o seu app no terminal	Na recuperação ou reimpressão: consultar o portal
printer_error, no_paper	Falha de impressão	Verificar a impressora e o papel
invalid_user_data	Nome vazio, CPF sem 11 dígitos, perfil desconhecido ou senha fora do formato	Corrigir os dados
user_not_found	userId inexistente	Atualizar a lista com list_users
user_already_exists	Já há usuário com o CPF	Usar o cadastro existente
last_supervisor	Deixaria Operadores sem Supervisor	Cadastrar outro Supervisor antes
supervisor_limit	Terminal já tem 10 Supervisores	Remover ou rebaixar um
supervisor_required	Sem Supervisor, o primeiro usuário tem de ser Supervisor	Cadastrar um Supervisor primeiro
internal_error	Falha inesperada no host, ou documento de impressão inválido	Registrar message e, quando vier, vendorCode; acionar o suporte
unknown	Código não classificado: de uma versão mais nova do host, ou falha sem código do fabricante	Mostrar message; não decidir

terminal_busy merece atenção: o terminal executa uma operação por vez e recusa concorrência em vez de enfileirar, porque uma fila deixaria o operador sem retorno por minutos.