Boas práticas

Erros e mensagens

Quando um pagamento não passa, a API diz o que mostrar ao comprador e se vale tentar de novo. O texto técnico fica para o log.

Formato do erro

Toda resposta de erro tem o mesmo formato. erro.codigo é estável: trate por ele, não pela mensagem.

JSON

HTTP/1.1 400
{
  "erro": {
    "codigo": "requisicao_invalida",
    "mensagem": "No Pix, o endereço do comprador é obrigatório (exigência da operadora).",
    "campo": "comprador.endereco",
    "motivo": {
      "codigo": "dados_comprador_invalidos",
      "mensagem_comprador": "Confira seus dados (CPF e endereço) e tente de novo.",
      "tentar_novamente": "sim",
      "detalhe_operadora": null
    }
  }
}

Mensagem para o comprador

O bloco motivo vem no pedido recusado, expirado ou erro e nas respostas de erro que o comprador pode resolver:

{
  "id": "…",
  "status": "recusado",
  "motivo_recusa": "Transação não autorizada - saldo insuficiente",
  "motivo": {
    "codigo": "cartao_sem_limite",
    "mensagem_comprador": "Seu cartão não tem limite disponível para esta compra. Tente outro cartão ou pague com Pix.",
    "tentar_novamente": "outro_meio",
    "detalhe_operadora": { "codigo": "51", "mensagem": "Transação não autorizada - saldo insuficiente" }
  }
}

mensagem_comprador: mostre como vier. Já está no idioma do pedido (pt-BR, pt-PT, en ou es).
tentar_novamente: sim = mesmo meio de novo; outro_meio = ofereça outro cartão ou o Pix; nao = não adianta repetir.
detalhe_operadora e motivo_recusa: texto técnico, só para o log e o suporte. Nunca mostre ao comprador.

Os textos são mantidos pela Yuupe e podem melhorar com o tempo; os códigos, não mudam. Um motivo.codigo que você não conhece trate como outro_meio.

Motivos

motivo.codigo	Quando	tentar_novamente
`cartao_sem_limite`	Saldo ou limite insuficiente	`outro_meio`
`cartao_vencido`	Cartão vencido	`outro_meio`
`cartao_dados_invalidos`	Número, validade ou código de segurança errados	`sim`
`cartao_bloqueado`	Cartão bloqueado ou não permitido pelo banco	`outro_meio`
`suspeita_de_fraude`	O banco suspeitou da compra	`outro_meio`
`banco_indisponivel`	O banco do cartão não respondeu	`sim`
`nao_autorizado`	Recusa genérica do banco	`outro_meio`
`autenticacao_falhou`	Confirmação do banco não concluída ou negada	`sim`
`autenticacao_expirou`	O comprador não confirmou com o banco em 5 minutos	`sim`
`pix_expirado`	O Pix não foi pago no prazo	`sim`
`dados_comprador_invalidos`	CPF/CNPJ ou endereço faltando ou recusados	`sim`
`comprador_igual_vendedor`	Dados do próprio vendedor usados como comprador	`nao`
`pagamento_indisponivel`	Problema do lado da loja ou da operadora	`outro_meio`
`valor_fora_do_permitido`	Abaixo do mínimo do cartão ou parcelas fora do permitido	`outro_meio`

Perdido, roubado e suspeita de fraude nunca aparecem como tal para o comprador: a mensagem é genérica, como manda a boa prática.

Códigos de erro

Erros da integração (chave, campo, idempotência) vêm sem motivo: são para você corrigir, não para o comprador.

erro.codigo	HTTP	Quando
`nao_autenticado`	401	Chave ausente, com formato errado ou inexistente
`chave_revogada`	401	Chave revogada no painel
`conta_inativa`	403	Conta Yuupe Pay da loja desativada
`conta_nao_configurada`	503	A loja ainda não está pronta para cobrar neste ambiente
`requisicao_invalida`	400	Campo faltando ou inválido (veja erro.campo)
`valor_invalido`	400	Total do pedido zero ou inválido
`parcelas_nao_permitidas`	400	Parcelas fora do que a loja aceita para o valor
`metodo_indisponivel`	400	Forma de pagamento desligada na loja
`token_cartao_obrigatorio`	400	Cartão sem token_cartao
`valor_abaixo_minimo_3ds`	422	Cartão abaixo do mínimo; nada foi cobrado
`dados_recusados`	422	A operadora recusou os dados enviados
`autenticacao_indisponivel`	503	Confirmação do banco indisponível na operadora; nada foi cobrado
`pedido_nao_encontrado`	404	Id ou número inexistente neste ambiente
`idempotency_key_obrigatoria`	400	Estorno sem o cabeçalho Idempotency-Key
`valor_acima_do_estornavel`	409	Estorno maior que o saldo
`estorno_nao_permitido`	409	Pedido que não pode ser estornado
`erro_gateway`	502	A operadora falhou ou recusou a operação
`limite_de_requisicoes`	429	Mais de 600 requisições por minuto
`erro_interno`	500	Erro do nosso lado: tente de novo; se persistir, fale com a Yuupe

A lista fechada também está na Referência.

#Formato do erro

#Mensagem para o comprador

#Motivos

#Códigos de erro

Formato do erro

Mensagem para o comprador

Motivos

Códigos de erro