Regras de contrato

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.

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"
}

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
}

Status da conta

A conta do usuário deve estar com o status 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
}

Conta não bloqueada

A conta do usuário não pode estar bloqueada. Contas bloqueadas perdem o acesso a esta funcionalidade.Se a conta estiver bloqueada, a API retorna 403 Forbidden.

{
    "success": false,
    "message": "Sua conta está bloqueada. Não é permitido realizar esta ação.",
    "data": null
}

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."]
        }
    }
}

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
}

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
}

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
}

Comunicação com a adquirente

A Pluggou encaminha a transação para o provedor de pagamento conforme a cadeia de prioridade — configuração padrão da conta ou override informado na requisição. Se a primeira adquirente falhar, a API tenta automaticamente a próxima disponível na cadeia (retry automático).Se todas as tentativas falharem, a API retorna 400 Bad Request:

{
    "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:

Campo	Tipo	Descrição
`data.id`	string	UUID único da transação criada
`data.amount`	integer	Valor total da transação em centavos
`data.platform_tax`	integer	Taxa cobrada pela plataforma em centavos
`data.liquid_amount`	integer	Valor líquido que será creditado na sua conta em centavos
`data.pix.emv`	string	Có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ódigo	Situação
`201`	Transação criada com sucesso
`400`	Regra de negócio violada (método, valor, adquirente)
`401`	Credenciais ausentes, inválidas ou inativas
`403`	Sem permissão (credencial, conta não aprovada, conta bloqueada)
`422`	Erro de validação nos dados enviados
`500`	Erro interno do servidor

Seleção de adquirente por transação

Ao criar uma transação via Gerar transação PIX, você pode informar adquirentes opcionalmente para aquela transação específica. Se omitir o campo acquirers, a API utiliza a configuração padrão da conta (active_acquirers).

O override por transação não altera a configuração persistente da conta. Para definir o padrão global, consulte Atualizar adquirentes.

Campos opcionais de adquirente

Informe um array acquirers com até 3 adquirentes, cada uma com sua prioridade:

{
    "acquirers": [
        { "acquirer_key": "adq_c", "priority": 1 },
        { "acquirer_key": "adq_a", "priority": 2 },
        { "acquirer_key": "adq_b", "priority": 3 }
    ]
}

Se omitir o campo acquirers, a transação utiliza a configuração padrão da conta.

Regras de validação

Regra	Comportamento
`acquirers`	Opcional; quando informado, aceita de 1 a 3 itens
`acquirer_key`	Obrigatório em cada item; máximo 64 caracteres; formato `^[a-z0-9_]+$`
`priority`	Obrigatório em cada item; deve ser `1`, `2` ou `3`
Prioridades duplicadas	Erro `422`
Mesma adquirente em prioridades diferentes	Erro `422`
Adquirente indisponível	Ignorada silenciosamente; tenta a próxima disponível
Nenhuma disponível	Erro `422` genérico (sem expor nomes das chaves rejeitadas)

Diferente da configuração persistente, adquirentes indisponíveis informadas no override não bloqueiam a requisição — são puladas. Se nenhuma das informadas estiver disponível, a transação é rejeitada.

Lógica de fallback na transação

Ordena por priority (1 → 2 → 3).
Para cada item informado, verifica se acquirer_key está disponível para a conta.
Adquirentes indisponíveis são puladas silenciosamente.
Monta a cadeia apenas com as disponíveis.
Se a cadeia ficar vazia → erro 422.
Na geração do PIX, tenta a primeira da cadeia; se falhar na adquirente, tenta a próxima (retry automático).

Exemplo: você informou adq_c (prioridade 1, indisponível), adq_a (prioridade 2, disponível) e adq_b (prioridade 3, indisponível) → a API usa apenas adq_a e retorna 201 Created.

Exemplo de requisição com override

curl -X POST https://api.pluggoutech.com/api/transactions \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: pk_live_abc123def456..." \
  -H "X-Secret-Key: sk_live_xyz789ghi012..." \
  -d '{
    "payment_method": "pix",
    "amount": 10000,
    "acquirers": [
      { "acquirer_key": "adq_c", "priority": 1 },
      { "acquirer_key": "adq_a", "priority": 2 },
      { "acquirer_key": "adq_b", "priority": 3 }
    ],
    "buyer": {
      "buyer_name": "Maria Souza",
      "buyer_document": "98765432100",
      "buyer_phone": "11988887777"
    },
    "postback_url": "https://seusite.com/webhook/pagamento",
    "metadata": {
      "pedido_id": "12345"
    }
  }'

Erros específicos de adquirente (422)

{
    "success": false,
    "message": "Erro de validação",
    "data": {
        "errors": {
            "acquirers": [
                "Nenhuma das adquirentes informadas está disponível para seleção nesta conta."
            ]
        }
    }
}

{
    "success": false,
    "message": "Erro de validação",
    "data": {
        "errors": {
            "acquirers": [
                "Não é permitido informar a mesma prioridade mais de uma vez."
            ]
        }
    }
}

Guia de implementação

Adquirentes

Transações

Transferências

Visão geral

Fluxo de validação

Resposta de sucesso

Resumo dos códigos de resposta

Seleção de adquirente por transação

Campos opcionais de adquirente

Regras de validação

Lógica de fallback na transação

Exemplo de requisição com override

Erros específicos de adquirente (422)

​Visão geral

​Fluxo de validação

​Resposta de sucesso

​Resumo dos códigos de resposta

​Seleção de adquirente por transação

​Campos opcionais de adquirente

​Regras de validação

​Lógica de fallback na transação

​Exemplo de requisição com override

​Erros específicos de adquirente (422)

Visão geral

Fluxo de validação

Resposta de sucesso

Resumo dos códigos de resposta

Seleção de adquirente por transação

Campos opcionais de adquirente

Regras de validação

Lógica de fallback na transação

Exemplo de requisição com override

Erros específicos de adquirente (422)