场景模拟

在沙盒环境中模拟 automatic-pix-api 收款方流程的完整指南。本指南包括完整测试流程所需的模拟端点和真实端点。

重要前提条件

在执行任何模拟之前，您必须使用可用的授权流程之一创建循环扣款。模拟只模拟 SPI 的响应，但循环扣款需要在系统中存在。

请查阅创建流程：

• 流程1 - 推送通知
• 流程2 - 二维码（仅循环扣款）
• 流程3 - 二维码（含首次付款）
• 流程4 - 二维码（含首次付款和可变金额）

完整模拟流程

Pix 自动扣款端到端测试 - 沙盒环境

SANDBOX

1

创建循环扣款

真实

任何模拟前的必要步骤。选择四种可用流程之一（流程1：推送通知，流程2-4：具有不同配置的二维码）。创建后，保存返回的 outgoing_recurrence_spi_id。

可用流程：流程1（推送），流程2（二维码 - 循环扣款），流程3（二维码 + 首次付款），流程4（二维码 + 付款 + 可变金额）

2

批准循环扣款

模拟

模拟 SPI 在收款方流程的不同旅程中发送给 automatic-pix-api 的循环扣款状态更新。使用端点 /mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID 将状态更新为 pending_confirmation，然后更新为 approved。

注意：在流程2、3和4中，批准时还需要发送账户数据（account_data）。在流程3和4中，还需要包含首次付款信息。

3

处理付款订单

模拟

通过端点 /mock/process_payment_orders 模拟付款订单处理。此步骤自动创建对账批次，并将批次创建 webhook 发送到您配置的 URL。

发生了什么：自动创建订单，根据 reference_date 和循环扣款类型创建或更新对账批次，并触发创建 webhook。

4

查询和对账订单

真实

真实步骤（非模拟）：查询上一步创建的对账批次，获取 receiver_conciliation_id 和 payment_order_key。对于 variable_amount 类型的循环扣款，您必须更新付款订单的具体金额。

重要：此步骤对于 variable_amount 循环扣款是必须的。不更新金额，订单将不会被处理。对于 fixed_amount，此步骤不是必要的。

5

更新执行日期

模拟

将付款订单的 next_retry_execution_datetime 更新为当前日期，允许立即处理尝试。使用端点 /mock/payment_order/PAYMENT_ORDER_KEY/update_next_retry_execution_datetime。

仅在沙盒中可用。此步骤是推进流程并立即处理付款尝试所必需的。

6

处理付款尝试

模拟

通过端点 /mock/process_payment_order_attempts 模拟付款尝试处理。创建自动 PIX 流程所需的尝试，为系统接收入账 PIX 模拟或拒绝做准备。

仅在沙盒中可用。此步骤后，您可以模拟接收 PIX（步骤7）或拒绝（步骤8）。

结果模拟

付款

7. 模拟入账 Pix

模拟通过 PIX 成功接收付款

拒绝

7. 模拟拒绝

模拟付款尝试被拒绝

---

前提条件：创建循环扣款

必须

此步骤是必须的，在任何模拟之前。根据您的需求选择循环扣款创建流程之一。

选择您的流程

流程	描述	链接
流程1	推送通知 - 通过通知授权	创建循环扣款：流程1
流程2	二维码 - 仅循环扣款授权	创建循环扣款：流程2
流程3	二维码 - 循环扣款 + 首次付款	创建循环扣款：流程3
流程4	二维码 - 循环扣款 + 首次付款 + 可变金额	创建循环扣款：流程4

重要信息

创建循环扣款后，保存返回的 outgoing_recurrence_spi_id。模拟时将需要它。

---

步骤1：循环扣款更新模拟（模拟）

前提条件

在此步骤之前，您必须：

1. 使用创建流程之一创建循环扣款
2. 获取创建的循环扣款的 outgoing_recurrence_spi_id

此端点模拟 SPI 在收款方流程的不同旅程中发送给 automatic-pix-api 的循环扣款状态更新。

请求

ENDPOINT

/mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID

方法

PATCH

请求体：流程1 - 付款方 PSP 接收请求

{
  "outgoing_recurrence_status": "pending_confirmation"
}

请求体：流程1 - 付款方 PSP 接收请求确认

{
  "outgoing_recurrence_status": "approved"
}

请求体：流程2、3和4 - 付款方 PSP 接收请求

{
  "outgoing_recurrence_status": "pending_confirmation"
}

请求体：流程2 - 付款方 PSP 接收请求确认

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

请求体：流程3和4 - 付款方 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
}

路径参数

字段	类型	描述	最大字符数
outgoing_recurrence_spi_id*	string	出站循环扣款的 SPI 标识符	50

请求体对象

字段	类型	描述	最大字符数
outgoing_recurrence_status*	string	出站循环扣款状态	50
account_data	object	账户数据（仅流程2、3和4）	-

account_data 对象

字段	类型	描述	最大字符数
account_number*	string	账户号码	20
account_digit*	string	账户校验位	1
account_branch*	string	机构代码	6
ispb*	string	金融机构 ISPB 代码	8

outgoing_recurrence_status 枚举

枚举值	描述
pending_confirmation	待确认
approved	已批准

流程说明

• 流程1：仅更新状态，不含账户数据
• 流程2：先仅更新状态，然后更新状态 + 账户数据（仅循环扣款批准）
• 流程3和4：先仅更新状态，然后更新状态 + 账户数据 + 首次付款数据

下一步

批准循环扣款后，继续步骤3：处理付款订单

---

步骤2：循环扣款取消模拟（模拟 - 可选）

前提条件

在此步骤之前，您必须：

1. 创建循环扣款
2. 批准循环扣款（步骤1）

此端点模拟由 SPI 触发的出站循环扣款取消。

请求

ENDPOINT

/mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID/cancel

方法

PATCH

无载荷

此端点没有请求体（载荷）。只需要路径参数。

路径参数

字段	类型	描述	最大字符数
outgoing_recurrence_spi_id*	string	出站循环扣款的 SPI 标识符	50

---

步骤3：处理付款订单（模拟）

前提条件

在此步骤之前，您必须：

1. 创建循环扣款
2. 批准循环扣款（步骤1）

此端点模拟付款订单处理，将相应地创建对账批次并发送这些批次的创建 Webhook。

请求

ENDPOINT

/mock/process_payment_orders

方法

PATCH

无载荷

此端点没有请求体（载荷）。模拟将自动执行。

此步骤发生了什么？

1. 付款订单由系统自动创建
2. 对账批次被创建或更新（payment_order_conciliation_batch）
   • 如果 reference_date 和循环扣款类型（'fixed_amount' 或 'variable_amount'）已存在开放批次，则将订单添加到其中
   • 否则，创建新批次
3. 批次创建 webhook 发送到您配置的 URL

下一步

处理订单后，您需要在继续之前查询和对账付款订单。请参阅步骤4。

---

步骤4：查询和对账付款订单

必要步骤（非模拟）

这是一个真实步骤，不是模拟！您需要查询上一步创建的对账批次，获取 receiver_conciliation_id 和 payment_order_key，这些将在之后使用。

前提条件

在此步骤之前，您必须：

1. 处理付款订单（步骤3）
2. 收到对账批次创建 webhook

4.1 - 查询付款批次

要查询已创建的批次，请使用批次查询端点：

查阅完整文档：

• 按账户查询付款批次
• 按请求方查询付款批次

重要信息

在 GET 响应中，您将找到：

• payment_order_conciliation_batch_key：批次密钥
• payment_orders：批次内的付款订单列表
• receiver_conciliation_id：保存此值！ 将在步骤7中用于模拟入账 PIX
• payment_order_spi_id：付款订单的 SPI 标识符
• payment_order_key：付款订单的唯一密钥

4.2 - 更新付款订单（可变金额必须）

重要

此步骤对于 variable_amount 类型的循环扣款是必须的。对于固定金额（fixed_amount）的循环扣款，此步骤不是必要的。

对于可变金额的循环扣款，您必须更新付款订单，提供本周期将收取的具体金额：

查阅完整文档：

• 更新付款订单

ENDPOINT

/account/ACCOUNT_KEY/outgoing_recurrence/OUTGOING_RECURRENCE_KEY/payment_order/PAYMENT_ORDER_KEY

方法

PATCH

请求体 - 可变金额示例

{
  "transaction_amount": 150.75,
}

何时为必须？

循环扣款类型	更新是否必须？	原因
fixed_amount	否	金额在创建循环扣款时已定义
variable_amount	是	必须在每次执行时提供金额

信息

• 固定循环扣款：金额在创建时已定义，不需要更新
• 可变循环扣款：每次付款处理前必须提供金额
• 不更新：未更新的可变循环扣款将不会被处理

下一步

查询批次并更新付款订单（如需要）后，继续步骤5。

---

步骤5：更新执行日期（模拟）

前提条件

在此步骤之前，您必须：

1. 处理付款订单（步骤3）
2. 查询对账批次（步骤4）
3. 获取付款订单的 payment_order_key

此端点允许将特定付款订单的 next_retry_execution_datetime 更新为当前日期，使订单尝试处理能够立即进行。

仅限沙盒

此端点仅在沙盒环境中可用。

请求

ENDPOINT

/mock/payment_order/payment_order_key/update_next_retry_execution_datetime

方法

PATCH

路径参数

字段	类型	描述	最大字符数
payment_order_key*	uuid4	付款订单唯一标识键	36

请求体

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

请求体参数

字段	类型	描述	最大字符数
next_retry_execution_datetime*	string	订单的新执行日期（格式 YYYY-MM-DD）	10

目的

此端点将下次尝试的执行日期更新为当前日期，允许系统立即处理付款尝试，这是模拟入账 PIX 接收所必需的。

下一步

更新执行日期后，继续步骤6。

---

步骤6：处理付款尝试（模拟）

前提条件

在此步骤之前，您必须：

1. 更新执行日期（步骤5）

此端点模拟付款尝试处理，创建自动 PIX 流程所需的尝试。

仅限沙盒

此端点仅在沙盒环境中可用。

请求

ENDPOINT

/mock/process_payment_order_attempts

方法

PATCH

无载荷

此端点没有请求体（载荷）。模拟将自动执行。

目的

此端点根据已更新执行日期的付款订单处理付款尝试，创建模拟入账 PIX 接收所需的尝试。

下一步 - 选择您的路径

成功流程：继续步骤7：模拟入账 PIX

拒绝流程：继续步骤8：模拟拒绝尝试

---

步骤7：模拟入账 Pix

前提条件

在此步骤之前，您必须：

1. 更新执行日期（步骤5）
2. 处理付款尝试（步骤6）
3. 从批次获取 receiver_conciliation_id（步骤4）
4. 获取 outgoing_recurrence_spi_id 和 payment_order_spi_id

此端点模拟接收将与循环扣款付款订单关联的 Pix。

请求

ENDPOINT

/mock/automatic_pix/incoming_pix

方法

POST

请求体

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

请求体对象

字段	类型	描述	最大字符数
target_account_key*	string	目标账户唯一密钥	36
amount*	number	PIX 交易金额	-
receiver_conciliation_id*	string	收款方对账标识（在步骤4获取）	35

信息

此端点模拟完整的入账 Pix 流程，包括：

1. 处理 Pix 转账
2. 使用 receiver_conciliation_id 与 automatic-pix 付款订单关联

流程完成！

恭喜！您已完成成功付款流程。系统处理了：

• 创建循环扣款
• 批准循环扣款
• 创建付款订单和批次
• 处理尝试
• 接收 PIX

---

步骤8：模拟拒绝的付款尝试（模拟）

前提条件

在此步骤之前，您必须：

1. 处理付款订单（步骤3）
2. 更新执行日期（步骤5）
3. 处理付款尝试（步骤6）
4. 获取 outgoing_recurrence_spi_id 和 payment_order_spi_id

此端点模拟出站循环扣款中 PIX 付款尝试的拒绝，复制 SPI 拒绝交易时的行为。系统将自动创建付款尝试并模拟被拒绝的 PIX，导致发送尝试状态变更 webhook。

请求

ENDPOINT

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

方法

PATCH

请求体：尝试被拒绝

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

路径参数

字段	类型	描述	最大字符数
outgoing_recurrence_spi_id*	string	出站循环扣款的 SPI 标识符	50
payment_order_spi_id*	string	付款订单的 SPI 标识符	50

请求体对象

字段	类型	描述	最大字符数
payment_order_status*	string	付款订单状态（始终为 "rejected"）	50
rejection_information*	object	拒绝信息	-

rejection_information 对象

字段	类型	描述	最大字符数
bacen_reason_code*	string	拒绝的 Bacen 错误代码	4

常见 Bacen 错误代码

代码	英文描述	葡萄牙语描述
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

系统运作

1. 拒绝模拟：系统使用指定的错误代码模拟被拒绝的 PIX
2. 发送 Webhook：每次被拒绝的尝试，都会发送 webhook baas.automatic_pix.payment_order_attempt.status_change
3. 多次尝试：系统允许最多4次付款尝试。第4次尝试被拒绝后，付款订单状态更改为 "rejected"

结果 Webhook

每次被拒绝的尝试将生成以下格式的 webhook：

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

多次尝试流程

1. 第1次尝试：付款订单保持 "pending" 状态，尝试状态 "rejected"
2. 第2次尝试：付款订单保持 "pending" 状态，创建新尝试
3. 第3次尝试：付款订单保持 "pending" 状态，创建新尝试
4. 第4次尝试：付款订单更改为 "rejected" 状态（达到最大限制）

---

流程摘要

完整成功流程

步骤	描述	流程类型	文档
0	创建循环扣款	真实	创建流程
1	批准循环扣款	模拟	查看详情
3	处理付款订单	模拟	查看详情
4	查询和对账订单	真实	查询批次
5	更新执行日期	模拟	查看详情
6	处理尝试	模拟	查看详情
7	模拟入账 PIX	模拟	查看详情

完整拒绝流程

步骤	描述	流程类型	文档
0	创建循环扣款	真实	创建流程
1	批准循环扣款	模拟	查看详情
3	处理付款订单	模拟	查看详情
4	查询和对账订单	真实	查询批次
5	更新执行日期	模拟	查看详情
6	处理尝试	模拟	查看详情
8	模拟拒绝	模拟	查看详情

---

实用链接

循环扣款管理

• 查询循环扣款
• 通过二维码查询循环扣款
• 列出账户的循环扣款
• 取消循环扣款

付款管理

• 列出付款订单
• 查询付款订单
• 更新付款订单
• 取消付款订单

对账批次

• 按账户查询批次
• 按请求方查询批次
• 列出批次付款
• 对账 Webhooks

Webhooks

• 收款用户 Webhooks
• 对账批次 Webhooks