Erros da Plataforma

As transações podem falhar devido a diferentes circunstâncias durante o fluxo de processamento. Em seguida, apresentamos a estrutura geral de erro.

{
  "error": {
    "name": "string",
    "message": "string",
    "details": {
      "reason": "string",
      "message": "string",
      "path": "string",
      "code": "string",
      "info" : {
       	"missingProperty": "string",
        "allowedValues" : [
           "string"
      	]
    }
  }
}

Estes campos são detalhados abaixo:

Campo	Tipo	Description
error.name	string	Um identificador de grupo de erro, que pode ser reutilizado para vários `details.reasons`.
error.message	string	Uma descrição textual para o erro do grupo.
details.reason	string	O identificador de baixo nível, que pode ser usado para mapear erros para os usuários finais, caso os integradores desejem fornecer uma explicação de nível inferior sobre um erro ocorrido.
details.message	string	Uma descrição textual de baixo nível, tipicamente usada para auxiliar os integradores quando o `details.reason` não é autoexplicativo.
details.path	string	O path do serviço que causou o erro. Especialmente útil para invocações de serviço incorretas.
details.code	string	Um código para ajudar a entender erros relacionados a invocações de serviços.
details.info.missingProperty	string	Especifica uma propriedade que estava faltando na inovacação de um serviço.
details.info.allowedValues	string	Especifica o conjunto de valores que podem ser usados para um campo específico (e não foi respeitado).

Exemplos de Erros

Exemplo #1: Erro de Autenticação

{
  "statusCode": "Error",
  "error": {
    "name": "AuthenticationError",
    "message": "The authorization token is invalid",
    "details": {
      "reason": "AuthenticationTokenInvalid"
    }
  }
}

Exemplo #2: Falta de parâmetro obrigatório

{
  "statusCode": "Error",
  "error": {
    "name": "InvalidRequestFormatError",
    "message": "The request body is invalid. See error object `details` property for more info",
    "details": [
      {
        "path": "/payment/payer",
        "code": "required",
        "message": "must have required property 'cpf'",
        "info": {
          "missingProperty": "cpf"
        }
      }
    ]
  }
}

Exemplo #3: Valor de parâmetro fornecido inválido

{
  "statusCode": "Error",
  "error": {
    "name": "InvalidRequestFormatError",
    "message": "The request body is invalid. See error object `details` property for more info",
    "details": [
      {
        "path": "/payment/key/type",
        "code": "enum",
        "message": "must be equal to one of the allowed values",
        "info": {
          "allowedValues": [
            "CPF",
            "EMAIL",
            "PHONE",
            "EVP"
          ]
        }
      }
    ]
  }
}

Nota: Na seção de API nós exploramos outros cenários e apresentamos exemplos de erros relacionados a cada endpoint individualmente.

Identificadores do Erros

Como mencionado anteriormente, o details.reason é o identificador de baixo nível adequado para integradores. O mesmo se aplica para os eventos de webhooks em seu campo stateErrorCause.
Aqui está o conjunto de identificadores que você deve esperar.

Erros em Transações

Erros gerais.

Identificador	Descrição
BankingIntegrationError	A transação não pôde ser transferida para o banco, tipicamente por uma instabilidade e curto-período da instituição bancária.
BankingProcessingFail	A transação não pôde ser processada pelo banco, por uma restrição não identificada.
CustomerAccountInsufficientFunds	A conta não tem fundos suficientes para concluir a operação.
PaymentProcessingError	Um identificador de erro genérico que acontece no Sandbox, quando força-se um erro via API. Para detalhes, acesse os nossos Endpoints para forçar error em Sandbox, na API.
TransactionGlobalAmountAboveAllowed	Erro para tentativas de transações acima do limite.
TransactionDailylAmountLimit	O valor da transação excede o máximo permitido para um CPF em um dia. Uma vez que o limite depende de flutuações entre os valores do USD e Real, informações adicionais são providas na mensagem.
TransactioWeeklylAmountLimit	O valor da transação excede o máximo permitido para um CPF em um semana. Uma vez que o limite depende de flutuações entre os valores do USD e Real, informações adicionais são providas na mensagem.
TransactioMonthlylAmountLimit	O valor da transação excede o máximo permitido para um CPF em um mês. Uma vez que o limite depende de flutuações entre os valores do USD e Real, informações adicionais são providas na mensagem.
TransactionInternalCashoutFail	Se por qualquer razão a PayBrokers não foi capaz de processar o cashout internamente. Por favor, dirija-se ao time da PayBrokers se esse erro surgir.
TransactionMultipleCashouts	Este erro ocorre se múltiplas retiradas forem solicitadas em um mesmo segundo para um mesmo CPF (mesmo proveniente de merchants distintos).
TransactionPayerIsInvalid	Os detalhes do pagador são inválidos
TransactionStateWithInvalidDocumentAmount	O valor do pagamento difere do valor original da transação
TransactionOrderIdRequired	Se a idempotência de transação estiver configurada na sua conta, o parâmetro orderId é obrigatório e este erro é retornado se ele não for fornecido.
TransactionOrderIdDuplicated	Se a idempotência de transação estiver configurada na sua conta, este erro é retornado se duas ou mais requests apresentarem o mesmo orderId.
TransactionBankCashoutNotAllowed	Se o banco de destino está na blacklist.

Exclusivos PIX.

Identificador	Descrição
TransactionInvalidPixKey	A chave PIX fornecida não é válida
TransactionPixKeyUnsupportedType	A tipo de chave PIX não é suportada por essa operação
TransactionPixKeyValidationFail	Não foi possível validar que a chave PIX aponta para uma conta bancária cujo proprietário é o CPF do recebedor fornecido.
PixKeyTypeNotAllowed	O tipo da chave PIX não está habilitado para esse merchant.

Validação de Participantes.

Identificador	Descrição
CounterpartyAgeUnder18	O proprietário do CPF tem menos de 18 anos de idade.
CounterpartyAgeAbove80	O proprietário do CPF tem mais de 80 anos de idade.
CounterpartyDeathNotice	O proprietário do CPF é falecido.
CounterpartyTaxNumberInvalid	O CPF ou CNPJ da contraparte não pode ser validado.
CounterpartyServiceError	O CPF não pode ser validado, ou pertence a um menor de idade.
TransactionGlobalTaxNumberNotAllowed	Tentativa de fazer uma transação com uma pessoa que foi bloqueada pela plataforma da PayBrokers
TransactionInvalidPixRecipient	A conta de destino não pertence ao dono do CPF provido na request.
TransactionPartnerTaxNumberNotAllowed	Tentativa de fazer uma transação com uma pessoa que foi bloqueada por sua empresa.
UnacceptablePayerTaxNumber	O CPF do pagador difere por qualquer motivo do esperado para o pagamento.

Esses erros são atualizados esporadicamente quando novos casos de uso ou restrições são introduzidos na plataforma.

Com foco em uma experiência de integração tranquila, a equipe do PayBrokers manterá os integradores informados sobre quaisquer mudanças relevantes.