Scenario Simulation

Complete guide to simulate the receiver flow of the automatic-pix-api in sandbox environment. This guide includes both mock endpoints and real endpoints necessary for the complete test flow.

Important Prerequisites

Before executing any mock simulation, you must create a recurrence using one of the available authorization journeys. Mocks only simulate SPI responses, but the recurrence needs to exist in the system.

Check the creation journeys:

• Journey 1 - Push Notification
• Journey 2 - QR Code (recurrence only)
• Journey 3 - QR Code (with first payment)
• Journey 4 - QR Code (with first payment and variable amounts)

Complete Simulation Flow

End-to-end testing of Automatic PIX - Sandbox Environment

SANDBOX

1

Create Recurrence

REAL

Mandatory step before any simulation. Choose one of the four available journeys (Journey 1: Push Notification, Journeys 2-4: QR Code with different configurations). After creating, save the returned outgoing_recurrence_spi_id.

Available journeys: Journey 1 (Push), Journey 2 (QR Code - recurrence), Journey 3 (QR Code + first payment), Journey 4 (QR Code + payment + variable amounts)

2

Approve Recurrence

MOCK

Simulates the recurrence status updates that SPI will send to automatic-pix-api. Use the /mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID endpoint to update status to pending_confirmation and then to approved.

Attention: In journeys 2, 3 and 4, you must also send account data (account_data) in the approval. In journeys 3 and 4, also include first payment information.

3

Process Payment Orders

MOCK

Simulates processing of payment orders through the /mock/process_payment_orders endpoint. This step automatically creates conciliation batches and sends the batch creation webhook to your configured URL.

What happens: Orders are created automatically, conciliation batches are created or updated based on reference_date and recurrence type, and creation webhook is triggered.

4

Query and Reconcile Orders

REAL

Real step (not a mock): Query the created conciliation batch and obtain the receiver_conciliation_id and payment_order_key. For variable_amount recurrences, you must update the payment order with the specific amount.

Important: This step is mandatory for variable_amount recurrences. Without the amount update, the order will not be processed. For fixed_amount, this step is not necessary.

5

Update Execution Date

MOCK

Updates the next_retry_execution_datetime of a payment order to the current date, allowing attempts processing to occur immediately. Use the /mock/payment_order/PAYMENT_ORDER_KEY/update_next_retry_execution_datetime endpoint.

Sandbox only. This step is necessary to advance the flow and allow immediate processing of payment attempts.

6

Process Payment Attempts

MOCK

Simulates processing of payment attempts through the /mock/process_payment_order_attempts endpoint. Creates necessary attempts for the automatic PIX flow, preparing the system to receive incoming PIX simulation or rejection.

Sandbox only. After this step, you can simulate PIX receipt (Step 7) or rejection (Step 8).

Result Simulations

Payment

7. Simulate Incoming PIX

Simulates successful payment receipt via PIX

Rejections

7. Simulate Rejection

Simulates rejection of a payment attempt

---

Prerequisite: Create Recurrence

Mandatory

This step is mandatory before any mock simulation. Choose one of the recurrence creation journeys according to your needs.

Choose Your Journey

Journey	Description	Link
Journey 1	Push Notification - Authorization via notification	Create Recurrence: Journey 1
Journey 2	QR Code - Recurrence authorization only	Create Recurrence: Journey 2
Journey 3	QR Code - Recurrence + first payment	Create Recurrence: Journey 3
Journey 4	QR Code - Recurrence + first payment + variable amounts	Create Recurrence: Journey 4

Important Information

After creating the recurrence, save the returned outgoing_recurrence_spi_id. It will be needed for mock simulations.

---

Step 1: Recurrence Update Simulation

Prerequisites

Before this step, you must have:

1. Created a recurrence using one of the creation journeys
2. Obtained the outgoing_recurrence_spi_id from the created recurrence

This endpoint simulates the recurrence status updates that SPI will send to automatic-pix-api during different receiver flow journeys.

Request

ENDPOINT

/mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID

METHOD

PATCH

Request Body: Journey 1 - Request received by Payer PSP

{
  "outgoing_recurrence_status": "pending_confirmation"
}

Request Body: Journey 1 - Request confirmation received by Payer PSP

{
  "outgoing_recurrence_status": "approved"
}

Request Body: Journeys 2, 3 and 4 - Request received by Payer PSP

{
  "outgoing_recurrence_status": "pending_confirmation"
}

Request Body: Journey 2 - Request confirmation received by Payer PSP

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

Request Body: Journeys 3 and 4 - Request confirmation received by Payer PSP

{
  "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

Field	Type	Description	Max Char.
outgoing_recurrence_spi_id*	string	SPI identifier of the outgoing recurrence	50

Request Body Object

Field	Type	Description	Max Char.
outgoing_recurrence_status*	string	Status of the outgoing recurrence	50
account_data	object	Account data (journeys 2, 3 and 4 only)	-

account_data Object

Field	Type	Description	Max Char.
account_number*	string	Account number	20
account_digit*	string	Account digit	1
account_branch*	string	Account branch	6
ispb*	string	ISPB code of the financial institution	8

outgoing_recurrence_status Enumerator

Enumerator	Description
pending_confirmation	Pending confirmation
approved	Approved

Journey Flows

• Journey 1: Status update only, no account data
• Journey 2: First status only, then status + account data (recurrence approval only)
• Journeys 3 and 4: First status only, then status + account data + first payment data

Next Step

After approving the recurrence, proceed to Step 3: Process Payment Orders

---

Step 2: Recurrence Cancellation Simulation (Optional)

Prerequisites

Before this step, you must have:

1. Created a recurrence
2. Approved the recurrence (Step 1)

This endpoint simulates the cancellation of an outgoing recurrence triggered by SPI.

Request

ENDPOINT

/mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID/cancel

METHOD

PATCH

No Payload

This endpoint has no request body (payload). Only the path parameter is required.

Path Parameters

Field	Type	Description	Max Char.
outgoing_recurrence_spi_id*	string	SPI identifier of the outgoing recurrence	50

---

Step 3: Process Payment Orders (Simulation)

Prerequisites

Before this step, you must have:

1. Created a recurrence
2. Approved the recurrence (Step 1)

This endpoint simulates the processing of payment orders which will consequently create conciliation batches and send the creation webhook for these batches.

Request

ENDPOINT

/mock/process_payment_orders

METHOD

PATCH

No Payload

This endpoint has no request body (payload). The simulation is executed automatically.

What happens in this step?

1. Payment orders are created automatically by the system
2. Conciliation batch is created or updated (payment_order_conciliation_batch)
   • If an open batch already exists for the reference_date and for the recurrence type ('fixed_amount' or 'variable_amount'), the order is included in