Simulação de cenários

Passo a passo para simular cenários do fluxo recebedor da automatic-pix-api. Essas simulações incluem a atualização de status de recorrências e cancelamentos que são acionados pela SPI (Sistema de Pagamentos Instantâneos).

Informação

Não há payload de retorno (response body) nessas requisições.

1 - Simulação de atualização de recorrência

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: Jornadas 2, 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
• Jornadas 2, 3 e 4: Primeiro apenas status, depois status + dados da conta

2 - Simulação de cancelamento de recorrência

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

3 - Simulação de cancelamento de pagamento

Este endpoint simula o cancelamento de um pagamento específico dentro de uma recorrência de saída, acionado pela SPI.

Request

ENDPOINT

/mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID/payment_order/PAYMENT_ORDER_SPI_ID/cancel

MÉTODO

PATCH

Sem Payload

Este endpoint não possui request body (payload). Apenas os path parameters são necessários.

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

4 - Simulação de processamento de Ordens de Pagamento e criação de Lotes

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.

5 - Simulação de atualização da data de execução 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 da 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

Pré-requisito

Este cenário deve ser executado após a simulação do cenário 4 (processamento das ordens de pagamento), pois é necessário ter Ordens de Pagamento criadas para atualizar sua data de execução.

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.

6 - Simulação de processamento de tentativas de pagamento

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.

Pré-requisito

Este cenário deve ser executado após a simulação do cenário 5 (atualização da data de execução), pois é necessário ter as datas de execução atualizadas para que as tentativas de pagamento sejam processadas corretamente.

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.

7 - Simulação de Pix de entrada

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

Pré-requisito

Este cenário deve ser executado após a simulação do cenário 5 (atualização da data de execução) e cenário 6 (processamento de tentativas de pagamento), pois é necessário ter as datas de execução atualizadas e as tentativas de pagamento criadas para que o PIX de entrada seja processado corretamente.

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
target_alias_key	string	Chave única do alias de destino (opcional)	36
amount*	number	Valor da transação PIX	-
receiver_conciliation_id	string	Identificação de conciliação do recebedor	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

8 - Simulação de tentativa de pagamento rejeitada

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.

Pré-requisito

Este cenário deve ser executado após a simulação do cenário 4 (processamento das ordens de pagamento), cenário 5 (atualização da data de execução) e cenário 6 (processamento de tentativas de pagamento), pois é necessário ter Ordens de Pagamento criadas, com datas de execução atualizadas e tentativas de pagamento processadas.

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)

Cenários de Uso

Jornada 1 - Autorização via Push Notification

1º Recebimento da solicitação pelo PSP Pagador: Simule com status pending_confirmation

2º Recebimento da confirmação de solicitação pelo PSP Pagador: Simule com status approved

Jornadas 2, 3 e 4 - Autorização via QR Code

1º Recebimento da solicitação pelo PSP Pagador: Simule com status pending_confirmation

2º Recebimento da confirmação de solicitação pelo PSP Pagador: Simule com status approved + account_data

Cancelamentos

• Cancelar Recorrência: Use o endpoint de cancelamento de recorrência
• Cancelar Pagamento Específico: Use o endpoint de cancelamento de pagamento

Processamento de Lotes

• Simular Criação de Lotes: Use o endpoint de processamento das ordens de pagamento para criar lotes e receber webhooks.

Atualização de Datas e Processamento (Sandbox)

• Atualizar Data de Execução: Use o endpoint de atualização da data de execução para permitir processamento imediato das tentativas de pagamento
• Processar Tentativas de Pagamento: Use o endpoint de processamento de tentativas de pagamento para criar as tentativas necessárias

Incoming PIX

• Simular Recebimento de Pix: Use o endpoint de Incoming Pix para simular pagamentos que serão associados às ordens de pagamento criadas nos cenários anteriores

Tentativas Rejeitadas

• Simular Rejeição de Tentativa: Use o endpoint de simulação de tentativa rejeitada para simular falhas no pagamento e receber webhooks de mudança de status

Fluxo Recomendado

1. Crie uma recorrência (cenários 1)
2. Processe ordens de pagamento (cenário 4) para criar lotes e receber webhooks
3. Atualize data de execução (cenário 5) para permitir processamento imediato no sandbox
4. Processe tentativas de pagamento (cenário 6) para criar as tentativas necessárias
5. Simule Pix de entrada (cenário 7) para associar pagamentos às ordens de pagamento usando o mesmo receiver_conciliation_id
6. Simule tentativa rejeitada (cenário 8) para testar o fluxo de rejeições e receber webhooks de mudança de status das tentativas