Skip to main content

​
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:
FluxoDocumentaçãoEscopo
Definir adquirente geral da contaAtualizar adquirentesAltera o padrão salvo na conta (vale para transações futuras sem override)
Override por transaçãoSeleção de adquirente por transaçãoEscolhe 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:
RequisitoDescrição
Permissão da credencialTipo cashin (apenas entradas) ou all (ambas)
Status da contaapproved (aprovada)
Conta não bloqueadaSua conta não pode estar bloqueada
Permissão habilitadaA permissão de Selecionar adquirentes da sua conta precisa estar habilitada

​
Fluxo recomendado

1

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.
2

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.
3

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

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

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:
RegraComportamento
acquirersArray obrigatório com 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ível para a contaErro 422 imediato (validação estrita)
Update parcialSe 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

AspectoAtualizar adquirentesSeleção por transação
EscopoAltera o padrão da contaSó na transação atual
Adquirente indisponívelErro imediato (422)Ignorada silenciosamente; tenta a próxima
PersistênciaSalva no usuárioNão salva
Uso típicoDefinir fallback padrãoRoteamento 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ódigoSituação
200Listagem obtida com sucesso
401Credenciais ausentes, inválidas ou inativas
403Sem permissão ou seleção de adquirente não habilitada
500Erro interno do servidor

​
PUT /pix-cash-in/acquirers

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