Skip to main content

​
Visão geral

Antes de realizar chamadas ao endpoint de criação de transações, é importante compreender as regras de negócio aplicadas pela Pluggou. Toda requisição passa por uma série de validações em cadeia — se qualquer etapa falhar, a transação não será criada e você receberá uma resposta de erro correspondente. Este guia detalha cada etapa de verificação na ordem exata em que são executadas, os possíveis erros e o comportamento esperado em caso de sucesso.

​
Fluxo de validação

As verificações abaixo são aplicadas na ordem listada. A primeira falha interrompe o processamento e retorna o erro correspondente.
1

Autenticação das credenciais

As credenciais X-Public-Key e X-Secret-Key devem estar presentes nos headers da requisição, além de serem válidas e ativas.Se as credenciais estiverem ausentes, inválidas ou inativas, a API retorna 401 Unauthorized.
{
    "error": "Credenciais inválidas",
    "message": "Chave não encontrada ou inativa"
}
2

Permissão da credencial

A credencial utilizada deve possuir permissão do tipo cashin (apenas entradas) ou all (ambas). Credenciais do tipo apenas saída não podem criar transações.Se a credencial não tiver permissão, a API retorna 403 Forbidden.
{
    "success": false,
    "message": "Esta credencial não tem permissão para realizar esta operação.",
    "data": null
}
3

Status da conta

A conta do usuário deve estar com o status approved (aprovada). Contas pendentes, em análise ou rejeitadas não podem processar transações.Se a conta não estiver aprovada, a API retorna 403 Forbidden.
{
    "success": false,
    "message": "Sua conta precisa estar aprovada para usar esta funcionalidade.",
    "data": null
}
4

Conta não bloqueada

A conta do usuário não pode estar bloqueada. Contas bloqueadas perdem temporariamente o acesso a todas as funcionalidades da API.Se a conta estiver bloqueada, a API retorna 403 Forbidden.
{
    "success": false,
    "message": "Sua conta está bloqueada.",
    "data": null
}
5

Validação dos campos

Todos os campos obrigatórios devem ser preenchidos com valores válidos, respeitando formato, tipo e tamanho. O campo buyer_document (CPF ou CNPJ) é validado algoritmicamente — documentos com dígitos verificadores inválidos serão rejeitados.Campos obrigatórios:
  • payment_method
  • amount
  • buyer.buyer_name
  • buyer.buyer_document
  • buyer.buyer_phone
Se houver erros de validação, a API retorna 422 Unprocessable Entity com os erros detalhados por campo.
{
    "success": false,
    "message": "Erro de validação nos dados fornecidos",
    "data": {
        "errors": {
            "payment_method": ["O método de pagamento é obrigatório."],
            "amount": ["O valor é obrigatório."],
            "buyer.buyer_name": ["O nome do comprador é obrigatório."],
            "buyer.buyer_document": ["CPF ou CNPJ do comprador inválido."],
            "buyer.buyer_phone": ["O telefone do comprador é obrigatório."]
        }
    }
}
6

Método de pagamento

O campo payment_method deve ser pix.Se o método não estiver habilitado, a API retorna 400 Bad Request.
{
    "success": false,
    "message": "Este método de pagamento não está habilitado para sua conta.",
    "data": null
}
7

Valor máximo

O valor da transação (amount) não pode ultrapassar 300.000 centavos (R$ 3.000,00).Se o valor exceder o limite, a API retorna 400 Bad Request.
{
    "success": false,
    "message": "O valor máximo permitido para transações é de R$ 3.000,00.",
    "data": null
}
8

Valor mínimo após taxas

Após o cálculo das taxas da plataforma, o valor líquido que será creditado na sua conta deve ser de no mínimo 10 centavos (R$ 0,10). Transações que resultem em valor líquido inferior a esse limite serão rejeitadas.Se o valor líquido for insuficiente, a API retorna 400 Bad Request.
{
    "success": false,
    "message": "O valor da transação deve resultar em pelo menos R$ 0,10 após as taxas.",
    "data": null
}
9

Comunicação com a adquirente

A comunicação com a adquirente deve ser bem-sucedida. A Pluggou encaminha a transação para o provedor de pagamento, que gera o código PIX.Se houver falha na comunicação, a API retorna 400 Bad Request (erro genérico) ou 401 Unauthorized (caso as credenciais da adquirente estejam incorretas).
{
    "success": false,
    "message": "Erro ao processar o pagamento. Tente novamente mais tarde.",
    "data": null
}

​
Resposta de sucesso

Se todas as validações passarem e a adquirente processar a transação com sucesso, a API retorna 201 Created com os seguintes dados:
CampoTipoDescrição
data.idstringUUID único da transação criada
data.amountintegerValor total da transação em centavos
data.platform_taxintegerTaxa cobrada pela plataforma em centavos
data.liquid_amountintegerValor líquido que será creditado na sua conta em centavos
data.pix.emvstringCódigo PIX copia e cola (EMV) para o pagador realizar o pagamento
{
    "success": true,
    "message": "Pagamento criado com sucesso!",
    "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "amount": 10000,
        "platform_tax": 149,
        "liquid_amount": 9851,
        "pix": {
            "emv": "00020126580014br.gov.bcb.pix0136..."
        }
    }
}
O valor de platform_tax é calculado automaticamente com base no plano da sua conta. O liquid_amount é sempre o resultado de amount - platform_tax.

​
Resumo dos códigos de resposta

CódigoSituação
201Transação criada com sucesso
400Regra de negócio violada (método, valor, adquirente)
401Credenciais ausentes, inválidas ou inativas
403Sem permissão (credencial, conta não aprovada, conta bloqueada)
422Erro de validação nos dados enviados
500Erro interno do servidor