> ## Documentation Index > Fetch the complete documentation index at: https://docs.pluggoucash.com/llms.txt > Use this file to discover all available pages before exploring further. # Regras de contrato > Entenda as regras de negócio, fluxo de validação e comportamento da API ao criar transações ## 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. 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`. ```json theme={null} { "error": "Credenciais inválidas", "message": "Chave não encontrada ou inativa" } ``` 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`. ```json theme={null} { "success": false, "message": "Esta credencial não tem permissão para realizar esta operação.", "data": null } ``` 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`. ```json theme={null} { "success": false, "message": "Sua conta precisa estar aprovada para usar esta funcionalidade.", "data": null } ``` 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`. ```json theme={null} { "success": false, "message": "Sua conta está bloqueada. Não é permitido realizar esta ação.", "data": null } ``` 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. ```json theme={null} { "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."] } } } ``` O campo `payment_method` deve ser `pix`. Se o método não estiver habilitado, a API retorna `400 Bad Request`. ```json theme={null} { "success": false, "message": "Este método de pagamento não está habilitado para sua conta.", "data": null } ``` 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`. ```json theme={null} { "success": false, "message": "O valor máximo permitido para transações é de R$ 3.000,00.", "data": null } ``` 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`. ```json theme={null} { "success": false, "message": "O valor da transação deve resultar em pelo menos R$ 0,10 após as taxas.", "data": null } ``` 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`: ```json theme={null} { "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 | ```json theme={null} { "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](/api-reference/transactions/create-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](/api-reference/acquirers/guide) (`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](/api-reference/acquirers/update). ### Campos opcionais de adquirente Informe um array `acquirers` com até **3 adquirentes**, cada uma com sua prioridade: ```json theme={null} { "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](/api-reference/acquirers/update), 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 ```bash theme={null} 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) ```json theme={null} { "success": false, "message": "Erro de validação", "data": { "errors": { "acquirers": [ "Nenhuma das adquirentes informadas está disponível para seleção nesta conta." ] } } } ``` ```json theme={null} { "success": false, "message": "Erro de validação", "data": { "errors": { "acquirers": [ "Não é permitido informar a mesma prioridade mais de uma vez." ] } } } ```