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

​
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

RegraComportamento
acquirersOpcional; quando informado, aceita de 1 a 3 itens
acquirer_keyObrigatório em cada item; máximo 64 caracteres; formato ^[a-z0-9_]+$
priorityObrigatório em cada item; deve ser 1, 2 ou 3
Prioridades duplicadasErro 422
Mesma adquirente em prioridades diferentesErro 422
Adquirente indisponívelIgnorada silenciosamente; tenta a próxima disponível
Nenhuma disponívelErro 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

  1. Ordena por priority (1 → 2 → 3).
  2. Para cada item informado, verifica se acquirer_key está disponível para a conta.
  3. Adquirentes indisponíveis são puladas silenciosamente.
  4. Monta a cadeia apenas com as disponíveis.
  5. Se a cadeia ficar vazia → erro 422.
  6. 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."
            ]
        }
    }
}