Regras de contrato

Visão geral

Contas habilitadas para seleção de adquirente podem escolher até 3 adquirentes PIX em ordem de prioridade:

Prioridade 1 — adquirente primária
Prioridade 2 — adquirente secundária (fallback)
Prioridade 3 — adquirente terciária (fallback)

Existem dois fluxos distintos:

Fluxo	Documentação	Escopo
Definir adquirente geral da conta	Atualizar adquirentes	Altera o padrão salvo na conta (vale para transações futuras sem override)
Override por transação	Seleção de adquirente por transação	Escolhe adquirente(s) apenas naquela transação, sem alterar o padrão da conta

Os identificadores de adquirente (acquirer_key) devem ser obtidos via Listar adquirentes. Não utilize chaves inventadas — apenas adquirentes retornadas pela API estão disponíveis para sua conta.

Pré-requisitos

Para utilizar as rotas de adquirentes, sua conta e credencial devem atender aos seguintes requisitos:

Requisito	Descrição
Permissão da credencial	Tipo cashin (apenas entradas) ou all (ambas)
Status da conta	approved (aprovada)
Conta não bloqueada	Sua conta não pode estar bloqueada
Permissão habilitada	A permissão de `Selecionar adquirentes` da sua conta precisa estar habilitada

Fluxo recomendado

Listar adquirentes disponíveis

Faça um GET /pix-cash-in/acquirers para obter as chaves (acquirer_key) disponíveis para sua conta e ver quais já estão configuradas como primária, secundária ou terciária.

Configurar o padrão da conta (opcional)

Use PUT /pix-cash-in/acquirers para definir ou atualizar as adquirentes padrão da conta. Essa configuração será usada em todas as transações que não informarem override.

Criar transações

Ao chamar POST /transactions, omita os campos de adquirente para usar o padrão da conta, ou informe acquirers para escolher adquirentes apenas naquela transação. Consulte o guia de transações.

Configuração persistente (PUT)

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).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
}

Seleção de adquirente habilitada

A conta deve ter a permissão Selecionar Adquirente habilitada.Se a permissão não estiver disponível, a API retorna 403 Forbidden.

{
    "success": false,
    "message": "Seleção de adquirente PIX cash-in não está habilitada para esta conta.",
    "data": null
}

Validação do payload

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

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

Regras de validação:

Regra	Comportamento
`acquirers`	Array obrigatório com 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 para a conta	Erro `422` imediato (validação estrita)
Update parcial	Se enviar apenas prioridades 1 e 2, a prioridade 3 é limpa (`null`)

Se houver erros de validação, a API retorna 422 Unprocessable Entity.

{
    "success": false,
    "message": "Erro de validação",
    "data": {
        "errors": {
            "acquirers": ["Adquirente indisponível para seleção nesta conta."]
        }
    }
}

Resposta de sucesso (PUT)

Se todas as validações passarem, a API retorna 200 OK com o snapshot das adquirentes ativas:

{
    "success": true,
    "message": "Adquirentes atualizadas com sucesso.",
    "data": {
        "active_acquirers": {
            "primary": {
                "acquirer_key": "adq_a",
                "acquirer_name": "Nome A"
            },
            "secondary": {
                "acquirer_key": "adq_b",
                "acquirer_name": "Nome B"
            },
            "tertiary": {
                "acquirer_key": "adq_c",
                "acquirer_name": "Nome C"
            }
        }
    }
}

Diferença entre configuração persistente e override por transação

Aspecto	Atualizar adquirentes	Seleção por transação
Escopo	Altera o padrão da conta	Só na transação atual
Adquirente indisponível	Erro imediato (`422`)	Ignorada silenciosamente; tenta a próxima
Persistência	Salva no usuário	Não salva
Uso típico	Definir fallback padrão	Roteamento pontual por pedido

Use a configuração persistente para definir o comportamento padrão da sua integração. Use o override por transação quando precisar rotear um pedido específico por uma adquirente diferente, sem alterar a configuração global da conta.

Resumo dos códigos de resposta

GET /pix-cash-in/acquirers

Código	Situação
`200`	Listagem obtida com sucesso
`401`	Credenciais ausentes, inválidas ou inativas
`403`	Sem permissão ou seleção de adquirente não habilitada
`500`	Erro interno do servidor

PUT /pix-cash-in/acquirers

Código	Situação
`200`	Adquirentes atualizadas com sucesso
`401`	Credenciais ausentes, inválidas ou inativas
`403`	Sem permissão ou seleção de adquirente não habilitada
`422`	Erro de validação (adquirente indisponível, prioridades duplicadas, etc.)
`500`	Erro interno do servidor

Guia de implementação

Adquirentes

Transações

Transferências

Visão geral

Pré-requisitos

Fluxo recomendado

Configuração persistente (PUT)

Resposta de sucesso (PUT)

Diferença entre configuração persistente e override por transação

Resumo dos códigos de resposta

GET /pix-cash-in/acquirers

PUT /pix-cash-in/acquirers

​Visão geral

​Pré-requisitos

​Fluxo recomendado

​Configuração persistente (PUT)

​Resposta de sucesso (PUT)

​Diferença entre configuração persistente e override por transação

​Resumo dos códigos de resposta

​GET /pix-cash-in/acquirers

​PUT /pix-cash-in/acquirers

Visão geral

Pré-requisitos

Fluxo recomendado

Configuração persistente (PUT)

Resposta de sucesso (PUT)

Diferença entre configuração persistente e override por transação

Resumo dos códigos de resposta

GET /pix-cash-in/acquirers

PUT /pix-cash-in/acquirers