Simulação de cenários

Guia completo para simular o fluxo recebedor da automatic-pix-api no ambiente sandbox. Este guia inclui tanto os endpoints de mock quanto os endpoints reais necessários para o fluxo completo de testes.

Pré-requisitos Importantes

Antes de executar qualquer simulação de mock, você deve criar uma recorrência utilizando uma das jornadas de autorização disponíveis. Os mocks simulam apenas as respostas da SPI, mas a recorrência precisa existir no sistema.

Consulte as jornadas de criação:

• Jornada 1 - Push Notification
• Jornada 2 - QR Code (apenas recorrência)
• Jornada 3 - QR Code (com primeiro pagamento)
• Jornada 4 - QR Code (com primeiro pagamento e valores variáveis)

Fluxo Completo de Simulação

Teste de ponta a ponta do Pix Automático - Sandbox Environment

SANDBOX

1

Criar Recorrência

REAL

Passo obrigatório antes de qualquer simulação. Escolha uma das quatro jornadas disponíveis (Jornada 1: Push Notification, Jornadas 2-4: QR Code com diferentes configurações). Após criar, guarde o outgoing_recurrence_spi_id retornado.

Jornadas disponíveis: Jornada 1 (Push), Jornada 2 (QR Code - recorrência), Jornada 3 (QR Code + primeiro pagamento), Jornada 4 (QR Code + pagamento + valores variáveis)

2

Aprovar Recorrência

MOCK

Simula as atualizações de status de recorrência que a SPI enviará para a automatic-pix-api. Utilize o endpoint /mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID para atualizar o status para pending_confirmation e depois para approved.

Atenção: Nas jornadas 2, 3 e 4, é necessário enviar também os dados da conta (account_data) na aprovação. Nas jornadas 3 e 4, inclua também informações do primeiro pagamento.

3

Processar Ordens de Pagamento

MOCK

Simula o processamento das ordens de pagamento através do endpoint /mock/process_payment_orders. Este passo cria automaticamente os lotes de conciliação e envia o webhook de criação de lote para sua URL configurada.

O que acontece: Ordens são criadas automaticamente, lotes de conciliação são criados ou atualizados com base na reference_date e tipo de recorrência, e o webhook de criação é disparado.

4

Consultar e Conciliar Ordens

REAL

Passo real (não é mock): Consultar o lote de conciliação criado e obter o receiver_conciliation_id e payment_order_key. Para recorrências do tipo variable_amount, você deve atualizar a ordem de pagamento com o valor específico.

Importante: Este passo é obrigatório para recorrências variable_amount. Sem a atualização do valor, a ordem não será processada. Para fixed_amount, este passo não é necessário.

5

Atualizar Data de Execução

MOCK

Atualiza o next_retry_execution_datetime de uma ordem de pagamento para a data atual, permitindo que o processamento das tentativas ocorra imediatamente. Utilize o endpoint /mock/payment_order/PAYMENT_ORDER_KEY/update_next_retry_execution_datetime.

Disponível apenas no sandbox. Este passo é necessário para avançar o fluxo e permitir o processamento imediato das tentativas de pagamento.

6

Processar Tentativas de Pagamento

MOCK

Simula o processamento das tentativas de pagamento através do endpoint /mock/process_payment_order_attempts. Cria as tentativas necessárias para o fluxo de PIX automático, preparando o sistema para receber a simulação de PIX de entrada ou rejeição.

Disponível apenas no sandbox. Após este passo, você pode simular o recebimento do PIX (Passo 7) ou a rejeição (Passo 8).

Simulações de Resultado

Pagamento

7. Simular Pix de Entrada

Simula o recebimento bem-sucedido do pagamento via PIX

Rejeições

7. Simular Rejeição

Simula a rejeição de uma tentativa de pagamento

---

Pré-requisito: Criar Recorrência

Obrigatório

Este passo é obrigatório antes de qualquer simulação de mock. Escolha uma das jornadas de criação de recorrência conforme sua necessidade.

Escolha sua Jornada

Jornada	Descrição	Link
Jornada 1	Push Notification - Autorização via notificação	Criar Recorrência: Jornada 1
Jornada 2	QR Code - Apenas autorização da recorrência	Criar Recorrência: Jornada 2
Jornada 3	QR Code - Recorrência + primeiro pagamento	Criar Recorrência: Jornada 3
Jornada 4	QR Code - Recorrência + primeiro pagamento + valores variáveis	Criar Recorrência: Jornada 4

Informação Importante

Após criar a recorrência, guarde o outgoing_recurrence_spi_id retornado. Ele será necessário para as simulações de mock.

---

Passo 1: Simulação de Atualização de Recorrência (Simulação)

Pré-requisito

Antes deste passo, você deve ter:

1. Criado uma recorrência usando uma das jornadas de criação
2. Obtido o outgoing_recurrence_spi_id da recorrência criada

Este endpoint simula as atualizações de status de recorrência que a SPI enviará para a automatic-pix-api durante diferentes jornadas do fluxo recebedor.

Request

ENDPOINT

/mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID

MÉTODO

PATCH

Request Body: Jornada 1 - Recebimento da solicitação pelo PSP Pagador

{
  "outgoing_recurrence_status": "pending_confirmation"
}

Request Body: Jornada 1 - Recebimento da confirmação da solicitação pelo PSP Pagador

{
  "outgoing_recurrence_status": "approved"
}

Request Body: Jornadas 2, 3 e 4 - Recebimento da solicitação pelo PSP Pagador

{
  "outgoing_recurrence_status": "pending_confirmation"
}

Request Body: Jornada 2 - Recebimento da confirmação da solicitação pelo PSP Pagador

{
  "outgoing_recurrence_status": "approved",
  "account_data": {
    "account_number": "123456",
    "account_digit": "7",
    "account_branch": "0001",
    "ispb": "31872495"
  }
}

Request Body: Jornadas 3 e 4 - Recebimento da confirmação da solicitação pelo PSP Pagador

{
  "outgoing_recurrence_status": "approved",
  "account_data": {
    "account_number": "123456",
    "account_digit": "7",
    "account_branch": "0001",
    "ispb": "31872495"
  },
  "receiver_conciliation_id": "064b6563329047c59db6902725b8d31e",
  "target_account_key": "23a4a1c8-9d82-4ebe-a90d-44fe8d839ec0",
  "transaction_amount": 250
}

Path Parameters

Campo	Tipo	Descrição	Máx. Caract.
outgoing_recurrence_spi_id*	string	Identificador SPI da recorrência de saída	50

Objeto Request Body

Campo	Tipo	Descrição	Máx. Caract.
outgoing_recurrence_status*	string	Status da recorrência de saída	50
account_data	object	Dados da conta (apenas jornadas 2, 3 e 4)	-

Objeto account_data

Campo	Tipo	Descrição	Máx. Caract.
account_number*	string	Número da conta	20
account_digit*	string	Dígito da conta	1
account_branch*	string	Agência da conta	6
ispb*	string	Código ISPB da instituição financeira	8

Enumerador outgoing_recurrence_status

Enumerador	Descrição
pending_confirmation	Pendente de confirmação
approved	Aprovado

Fluxos de Jornada

• Jornada 1: Apenas atualização de status, sem dados da conta
• Jornada 2: Primeiro apenas status, depois status + dados da conta (apenas aprovação da recorrência)
• Jornadas 3 e 4: Primeiro apenas status, depois status + dados da conta + dados do primeiro pagamento

Próximo Passo

Após aprovar a recorrência, prossiga para o Passo 3: Processar Ordens de Pagamento

---

Passo 2: Simulação de Cancelamento de Recorrência (Simulação - Opcional)

Pré-requisito

Antes deste passo, você deve ter:

1. Criado uma recorrência
2. Aprovado a recorrência (Passo 1)

Este endpoint simula o cancelamento de uma recorrência de saída acionado pela SPI.

Request

ENDPOINT

/mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID/cancel

MÉTODO

PATCH

Sem Payload

Este endpoint não possui request body (payload). Apenas o path parameter é necessário.

Path Parameters

Campo	Tipo	Descrição	Máx. Caract.
outgoing_recurrence_spi_id*	string	Identificador SPI da recorrência de saída	50

---

Passo 3: Processar Ordens de Pagamento (Simulação)

Pré-requisitos

Antes deste passo, você deve ter:

1. Criado uma recorrência
2. Aprovado a recorrência (Passo 1)

Este endpoint simula o processamento das ordens de pagamento que, consequentemente, irá criar os lotes de conciliação e enviar o Webhook de criação desses lotes.

Request

ENDPOINT

/mock/process_payment_orders

MÉTODO

PATCH

Sem Payload

Este endpoint não possui request body (payload). A simulação é executada automaticamente.

O que acontece neste passo?

1. Ordens de pagamento são criadas automaticamente pelo sistema
2. Lote de conciliação é criado ou atualizado (payment_order_conciliation_batch)
   • Se já existir um lote aberto para a reference_date e para o tipo de recorrência ('fixed_amount' ou 'variable_amount'), a ordem é incluída nele
   • Caso contrário, um novo lote é criado
3. Webhook de criação de lote é enviado para sua URL configurada

Próximo Passo

Após processar as ordens, você precisa consultar e conciliar as ordens de pagamento antes de continuar. Veja o Passo 4.

---

Passo 4: Consultar e Conciliar Ordens de Pagamento

Passo Obrigatório (NÃO é Mock)

Este é um passo real, não é uma simulação! Você precisa consultar o lote de conciliação criado no passo anterior e obter o receiver_conciliation_id e a payment_order_key que serão usados posteriormente.

Pré-requisitos

Antes deste passo, você deve ter:

1. Processado as ordens de pagamento (Passo 3)
2. Recebido o webhook de criação do lote de conciliação

4.1 - Consultar Lote de Pagamentos

Para consultar os lotes criados, utilize o endpoint de consulta de lotes:

Consulte a documentação completa:

• Consultar lote de pagamentos por conta
• Consultar lote de pagamentos por requester

Informações Importantes

Na resposta do GET, você encontrará:

• payment_order_conciliation_batch_key: Chave do lote
• payment_orders: Lista de ordens de pagamento dentro do lote
• receiver_conciliation_id: Guarde este valor! Será usado no Passo 7 para simular o PIX de entrada
• payment_order_spi_id: Identificador SPI da ordem de pagamento
• payment_order_key: Chave única da ordem de pagamento

4.2 - Atualizar Ordem de Pagamento (Obrigatório para Valor Variável)

Importante

Este passo é obrigatório para recorrências do tipo variable_amount. Para recorrências de valor fixo (fixed_amount), este passo não é necessário.

Para recorrências de valor variável, você deve atualizar a ordem de pagamento informando o valor específico que será cobrado neste ciclo:

Consulte a documentação completa:

• Atualizar ordem de pagamento

ENDPOINT

/automatic_pix/payment_order/PAYMENT_ORDER_KEY

MÉTODO

PATCH

Request Body - Exemplo para Valor Variável

{
  "transaction_amount": 150.75,
}

Quando é Obrigatório?

Tipo de Recorrência	Atualização Obrigatória?	Motivo
fixed_amount	Não	Valor já definido na criação da recorrência
variable_amount	Sim	Valor deve ser informado a cada execução

Informação

• Recorrências fixas: O valor já está definido na criação, não precisa ser atualizado
• Recorrências variáveis: O valor deve ser informado antes de cada processamento de pagamento
• Sem atualização: Recorrências variáveis sem atualização não serão processadas

Próximo Passo

Após consultar o lote e atualizar a ordem de pagamento (se necessário), prossiga para o Passo 5.

---

Passo 5: Atualizar Data de Execução (Simulação)

Pré-requisitos

Antes deste passo, você deve ter:

1. Processado as ordens de pagamento (Passo 3)
2. Consultado o lote de conciliação (Passo 4)
3. Obtido o payment_order_key da ordem de pagamento

Este endpoint permite atualizar o next_retry_execution_datetime de uma Ordem de Pagamento específica para a data atual, possibilitando que o processamento das Order Attempts ocorra imediatamente.

Sandbox Apenas

Este endpoint está disponível apenas no ambiente sandbox.

Request

ENDPOINT

/mock/payment_order/payment_order_key/update_next_retry_execution_datetime

MÉTODO

PATCH

Path Params

Campo	Tipo	Descrição	Máx. Caract.
payment_order_key*	uuid4	Chave única de identificação da ordem de pagamento	36

Request Body

{
  "next_retry_execution_datetime": "2025-08-22"
}

Request Body Params

Campo	Tipo	Descrição	Máx. Caract.
next_retry_execution_datetime*	string	Nova data de execução da order (formato YYYY-MM-DD)	10

Finalidade

Este endpoint atualiza a data de próxima execução da tentativa para a data atual, permitindo que o sistema processe imediatamente as tentativas de pagamento, que são necessárias para simular o recebimento de PIX de entrada.

Próximo Passo

Após atualizar a data de execução, prossiga para o Passo 6.

---

Passo 6: Processar Tentativas de Pagamento (Simulação)

Pré-requisitos

Antes deste passo, você deve ter:

1. Atualizado a data de execução (Passo 5)

Este endpoint simula o processamento das tentativas de pagamento, criando as tentativas necessárias para o fluxo de PIX automático.

Sandbox Apenas

Este endpoint está disponível apenas no ambiente sandbox.

Request

ENDPOINT

/mock/process_payment_order_attempts

MÉTODO

PATCH

Sem Payload

Este endpoint não possui request body (payload). A simulação é executada automaticamente.

Finalidade

Este endpoint processa as tentativas de pagamento baseadas nas ordens de pagamento com datas de execução atualizadas, criando as tentativas necessárias para simular o recebimento de PIX de entrada.

Próximo Passo - Escolha seu Caminho

Fluxo de Sucesso: Prossiga para o Passo 7: Simular PIX de Entrada

Fluxo de Rejeição: Prossiga para o Passo 8: Simular Tentativa Rejeitada

---

Passo 7: Simular Pix de Entrada

Pré-requisitos

Antes deste passo, você deve ter:

1. Atualizado a data de execução (Passo 5)
2. Processado as tentativas de pagamento (Passo 6)
3. Obtido o receiver_conciliation_id do lote (Passo 4)
4. Obtido o outgoing_recurrence_spi_id e payment_order_spi_id

Este endpoint simula o recebimento de um Pix que será associado a uma Ordem de Pagamento de uma recorrência.

Request

ENDPOINT

/mock/automatic_pix/incoming_pix

MÉTODO

POST

Request Body

{
  "target_account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
  "amount": 1000.00,
  "receiver_conciliation_id": "7535f0467d9a4af69c4d99408c2fec9d"
}

Objeto Request Body

Campo	Tipo	Descrição	Máx. Caract.
target_account_key*	string	Chave única da conta de destino	36
amount*	number	Valor da transação PIX	-
receiver_conciliation_id*	string	Identificação de conciliação do recebedor (obtido no Passo 4)	35

Informação

Este endpoint simula o fluxo completo de Incoming Pix, incluindo:

1. Processamento da transferência Pix
2. Associação à ordem de pagamento da automatic-pix usando o receiver_conciliation_id

Fluxo Concluído!

Parabéns! Você completou o fluxo de pagamento bem-sucedido. O sistema processou:

• Criação da recorrência
• Aprovação da recorrência
• Criação de ordens de pagamento e lotes
• Processamento de tentativas
• Recebimento do PIX

---

Passo 8: Simular Tentativa de Pagamento Rejeitada (Simulação)

Pré-requisitos

Antes deste passo, você deve ter:

1. Processado as ordens de pagamento (Passo 3)
2. Atualizado a data de execução (Passo 5)
3. Processado as tentativas de pagamento (Passo 6)
4. Obtido o outgoing_recurrence_spi_id e payment_order_spi_id

Este endpoint simula a rejeição de uma tentativa de pagamento PIX dentro de uma recorrência de saída, replicando o comportamento quando a SPI rejeita uma transação. O sistema criará automaticamente as tentativas de pagamento e simulará o PIX rejeitado, resultando no envio do webhook de mudança de status da tentativa.

Request

ENDPOINT

/mock/automatic_pix/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID/payment_order/PAYMENT_ORDER_SPI_ID

MÉTODO

PATCH

Request Body: Tentativa rejeitada

{
  "payment_order_status": "rejected",
  "rejection_information": {
    "bacen_reason_code": "AC06"
  }
}

Path Parameters

Campo	Tipo	Descrição	Máx. Caract.
outgoing_recurrence_spi_id*	string	Identificador SPI da recorrência de saída	50
payment_order_spi_id*	string	Identificador SPI da ordem de pagamento	50

Objeto Request Body

Campo	Tipo	Descrição	Máx. Caract.
payment_order_status*	string	Status da ordem de pagamento (sempre "rejected")	50
rejection_information*	object	Informações sobre a rejeição	-

Objeto rejection_information

Campo	Tipo	Descrição	Máx. Caract.
bacen_reason_code*	string	Código de erro do Bacen para rejeição	4

Códigos de Erro Bacen Comuns

Código	Descrição (Inglês)	Descrição (Português)
AB10	ErrorInstructedAgent	Erro interno no PSP pagador
AC05	ClosedDebtorAccountNumber	Conta do pagador encerrada
AC06	BlockedAccount	Conta do pagador bloqueada
AG12	NotAllowedBookTransfer	Transferência não permitida entre contas da mesma instituição
AM02	NotAllowedAmount	Valor excede limite máximo do pagador
AM09	WrongAmount	Valor não corresponde ao estabelecido na recorrência
DENC	DebtorIdentifierNotCorrespond	CPF/CNPJ do pagador não confere com a recorrência
DS27	UserNotYetActivated	Participante não cadastrado no SPI
DTED	InvalidExpiryDate	Data de vencimento inválida para a periodicidade
DTNT	-	Tentativas pós vencimento fora do prazo permitido
FBRD	FailureToComplyBusinessRuleDeadline	Solicitação fora do prazo para regras de negócio
IRNT	-	Recorrência não permite novas tentativas pós vencimento
MIDI	MandateIdIncorrect	ID da recorrência inexistente ou incorreto
MSUC	UnconfirmedMandateStatus	Status da recorrência não confirmado pelo pagador
NIEC	-	Ordem de pagamento anterior ainda pendente
NIPA	-	Pagamento já foi efetivado
NITX	-	Instrução não corresponde à cobrança recorrente anterior
QUNT	-	Limite de tentativas pós vencimento excedido
RC09	InvalidDebtorClearingSystemMemberIdentifier	ISPB do pagador inválido ou inexistente
UDEI	UltimateDebtorIdentifierIncorrect	CPF/CNPJ do devedor incorreto

Funcionamento do Sistema

1. Simulação de rejeição: O sistema simula o PIX rejeitado com o código de erro especificado
2. Webhook enviado: Para cada tentativa rejeitada, é enviado o webhook baas.automatic_pix.payment_order_attempt.status_change
3. Múltiplas tentativas: O sistema permite até 4 tentativas de pagamento. Na 4ª tentativa rejeitada, a ordem de pagamento tem seu status alterado para "rejected"

Webhook Resultante

Cada tentativa rejeitada irá gerar um webhook com o seguinte formato:

{
  "event_type": "baas.automatic_pix.payment_order_attempt.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "request_control_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "pending",
    "payment_order_attempt_status": "rejected",
    "transaction_amount": 125.53,
    "reason": "Conta de destino inexistente",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82"
  }
}

Fluxo de Múltiplas Tentativas

1. 1ª Tentativa: Payment order permanece com status "pending", attempt status "rejected"
2. 2ª Tentativa: Payment order permanece com status "pending", nova attempt criada
3. 3ª Tentativa: Payment order permanece com status "pending", nova attempt criada
4. 4ª Tentativa: Payment order muda para status "rejected" (limite máximo atingido)

---

Resumo dos Fluxos

Fluxo Completo de Sucesso

Passo	Descrição	Fluxo	Documentação
0	Criar Recorrência	Real	Jornadas de criação
1	Aprovar Recorrência	Simulação	Ver detalhes
3	Processar Ordens de Pagamento	Simulação	Ver detalhes
4	Consultar e Conciliar Ordens	Real	Consultar lotes
5	Atualizar Data de Execução	Simulação	Ver detalhes
6	Processar Tentativas	Simulação	Ver detalhes
7	Simular PIX de Entrada	Simulação	Ver detalhes

Fluxo Completo de Rejeição

Passo	Descrição	Fluxo	Documentação
0	Criar Recorrência	Real	Jornadas de criação
1	Aprovar Recorrência	Simulação	Ver detalhes
3	Processar Ordens de Pagamento	Simulação	Ver detalhes
4	Consultar e Conciliar Ordens	Real	Consultar lotes
5	Atualizar Data de Execução	Simulação	Ver detalhes
6	Processar Tentativas	Simulação	Ver detalhes
8	Simular Rejeição	Simulação	Ver detalhes

---

Links Úteis

Gerenciamento de Recorrências

• Consultar uma recorrência
• Consultar uma recorrência pelo QR Code
• Listar recorrências de uma conta
• Cancelar recorrência

Gerenciamento de Pagamentos

• Listar ordens de pagamento
• Consultar ordem de pagamento
• Atualizar ordem de pagamento
• Cancelar ordem de pagamento

Lotes de Conciliação

• Consultar lote por conta
• Consultar lote por requester
• Listar pagamentos de um lote
• Webhooks de conciliação

Webhooks

• Webhooks do Usuário Recebedor
• Webhooks de Lotes de Conciliação