术语表

API 参考 Webhooks MED Pix 密钥类型

通用概念

术语	定义
Pix	巴西中央银行的即时支付系统。全天候 24/7 运行,数秒内完成清算。
DICT	交易账户标识符目录。Bacen 的数据库,将 Pix 密钥映射到账户。付款前请查询。
EMV / BR Code	Pix 用于生成复制粘贴 QR Code 的国际标准。以 `00020126...` 开头的字符串。
动态 QR	每次收款带有 `id` 和(可选)金额的 QR Code。Magen 仅支持此类。
静态 QR	可重复使用的 QR Code。Magen 不支持。
MED	特殊退款机制。Bacen 用于在欺诈或错误情况下对 Pix 提出争议的流程。在 Magen 中转为违规。
Bearer token	在 header `Authorization: Bearer SEU_TOKEN` 中发送的认证 token。Magen 唯一的认证方式。
Callback / Webhook	当交易状态变化时,Magen 向你的 `callbackUrl` 发送的 `POST` 请求。最多重试 72 次,带退避策略。
幂等性	保证多次执行同一操作与执行一次具有相同效果。创建时使用 `clientReference`。
指数退避	重试间隔翻倍的策略(1秒、2秒、4秒、8秒)。Magen 使用此策略,推荐你在 `5xx`/`429` 重试时也使用。
Jitter	添加到退避时间上的随机变化,避免"惊群效应"(客户端同时发起请求)。

交易类型(`type`)

值	含义
`DEPOSIT`	Pix 收款,资金进入你的账户。
`WITHDRAW`	Pix 出款,资金转出到 Pix 密钥或 QR Code。
`INTERNAL_TRANSFER`	Magen 账户间转账,即时到账。
`COMMISSION`	佣金记账(内部使用)。可能出现在列表和报表中。

交易状态(`status`)

状态因类型而异。完整列表:

状态	含义
`PENDING`	等待付款(收款)或处理中(出款/转账)。
`COMPLETED`	成功完成。收款时:客户已付款。出款时:资金已转出。
`CANCELED`	完成前被取消(手动或规则触发)。
`WAITING_FOR_REFUND`	等待退款处理(通常在 MED 被接受后)。
`REFUNDED`	已退款,金额返还给付款人。
`EXPIRED`	收款过期未付款(超过 `expiresIn`)。
`ERROR`	操作期间发生技术错误。查看 payload 中的 `cancellationReason`。

退款状态(`refundStatus`)

值	含义
`PENDING`	退款处于处理队列中。
`COMPLETED`	退款已处理,金额已返还。
`CANCELED`	退款完成前被取消。

Pix 密钥类型(`pixType`)

值	含义
`cpf`	收款人的 CPF(11 位数字)。
`cnpj`	收款人的 CNPJ(14 位数字)。
`phone`	带国家码/区号的电话号码,格式为 `+5511999999999`。
`email`	在 Bacen 注册的 email 地址。
`evp`	随机密钥(由银行生成的 UUID)。

违规 / MED

状态(`infraction.status`)

值	描述
`WAITING_PSP`	等待提供方响应。
`OPEN`	违规活跃中,正在分析。
`ACKNOWLEDGED`	已被机构确认。
`DEFENDED`	已提交申辩。
`ANSWERED`	已提供额外信息。
`WAITING_ADJUSTMENTS`	等待文档材料。
`CLOSED`	已最终裁定结案(见 `analysisResult`)。
`CANCELLED`	在解决前被取消。

类型(`infraction.type`)

值	描述
`REFUND_REQUEST`	标准退款请求。
`FRAUD`	安全相关的投诉。
`REFUND_CANCELLED`	取消先前的退款。

分析结果(`infraction.analysisResult`)

值	描述
`AGREED`	违规已接受。将处理退款。
`DISAGREED`	违规被拒绝。不退款,交易保持不变。

报告方(`infraction.reportedBy`)

值	描述
`DEBITED_PARTICIPANT`	付款方机构发起。
`CREDITED_PARTICIPANT`	收款方机构发起。

API 通用字段

我们保留英文名称,因为它们在 JSON 中即如此呈现。

标识

字段	用途
`id`	Magen 中交易的唯一标识符。格式为 `MAGEN` + 时间戳 + 哈希。
`clientReference`	由你定义的外部标识符。每次 callback 中都会返回。最多 64 个字符。
`virtualAccount`	用于多租户的虚拟子账户(最多 50 个字符,适用于门店、分支、marketplace)。callback 中会返回。
`endToEndId`	Bacen 中操作的唯一标识符。格式为 `E` + 32 个字符。在争议中有用。
`requestId`	Magen 中调用的唯一 ID。出现在每个错误响应中(4xx 和 5xx)。请始终记录并在联系支持时附上,调查可直接追踪。参见错误格式。
`accountNumber`	Magen 账户号(6 位数字)。用于内部转账。

金额

字段	用途
`amount`	金额单位为雷亚尔(BRL),非分。例如:`10.90` 表示 R$ 10,90。
`serviceFeeCharged`	Magen 对该操作收取的手续费,单位为雷亚尔。

生成的收款

字段	用途
`qrCodeText`	Pix 复制粘贴码(EMV BR Code)。在带复制按钮的输入框中使用。
`qrCodeUrl`	公开 URL,将 QR 渲染为 PNG。可直接用在 `<img>` 中。
`qrCodeBase64`	Base64 格式的 QR Code 图像。
`generatedName`	与收款关联的引用名称。
`generatedDocument`	与收款关联的 CPF 或 CNPJ。
`generatedEmail`	与收款关联的 email。
`expiresIn`	收款过期时间,单位为秒。最大 172000(47 小时)。

付款人

字段	用途
`payerName`	付款人姓名(付款后在 callback 中返回)。
`payerDocument`	付款人的 CPF/CNPJ。
`payerInstitutionIspb`	付款人银行的 ISPB(8 位数字)。
`payerInstitutionName`	付款人银行名称。
`payerAccountNumber`	付款人的 Magen 账户(内部转账时存在)。

收款人

字段	用途
`receiverName`	收款人姓名(出款时)。
`receiverDocument`	收款人的 CPF/CNPJ。
`receiverInstitutionIspb`	收款人银行的 ISPB。
`receiverInstitutionName`	收款人银行名称。
`receiverAccountNumber`	收款人的 Magen 账户(内部转账时存在)。

按密钥出款

字段	用途
`pixKey`	收款人的 Pix 密钥。格式取决于 `pixType`。
`pixType`	密钥类型:`cpf`、`cnpj`、`phone`、`email`、`evp`。
`withdrawPixKey`	出款中使用的密钥(在 callback 中)。
`withdrawPixType`	出款中使用的密钥类型。

清算与退款

字段	用途
`paidAt`	付款时间戳(ISO 8601)。`COMPLETED` 后出现。
`cancellationReason`	取消原因。
`refundEndToEndId`	退款的 EndToEnd ID。
`refundAmount`	退款金额。
`refundStatus`	退款状态:`PENDING`、`COMPLETED`、`CANCELED`。
`refundReason`	退款原因。
`refundDescription`	退款描述。
`refundedAt`	退款时间戳(ISO 8601)。

其他

字段	用途
`callbackUrl`	Magen 推送交易更新的 URL。
`description`	最多 140 个字符的自由文本(用于出款和内部转账)。
`createdAt`	交易创建时间戳(ISO 8601)。
`updatedAt`	最后更新时间(ISO 8601)。
`infraction`	当交易转为 MED 争议时,callback 中出现的对象。

HTTP 状态码

代码	含义
`200`	操作成功。
`201`	资源已创建(收款、出款、转账)。
`204`	成功,无响应主体。
`400`	Payload 无效。详情查看 `message`。
`401`	Token 缺失、无效或已吊销。
`403`	Token 有效但无 endpoint 访问权限。
`404`	资源未找到。
`409`	冲突(重复、资源处于无效状态)。
`422`	语义验证失败。
`429`	达到限流。等待后用退避策略重试。
`5xx`	服务器错误。使用指数退避重试(仅 `5xx` 和 `429`)。

其他缩写(Bacen / Pix)

缩写	全称
Bacen	巴西中央银行。
PSP	支付服务提供商。每家银行/fintech 即是一个 PSP。
ISPB	巴西支付系统标识符。识别每个 PSP 的 8 位数字代码。
SPI	即时支付系统。Bacen 处理 Pix 的基础设施。
CACC	活期账户(Bacen 使用的 ISO 20022 术语)。
SVGS	储蓄账户。
TRAN	支付账户(过渡性)。
CUID	Magen 在内部资源中使用的唯一字符串标识符(例如违规的 `id`)。

Tipos de chave Pix

Tipos de chave Pix aceitos pela API Magen, formato esperado de cada um e regras de validação.

Para IAs (LLMs)

Toda a documentação da Magen disponível em formato consumível por modelos de linguagem. Copie o conteúdo direto, baixe o dump completo, ou use as URLs específicas por página. Funciona com ChatGPT, Claude, Gemini, Cursor, Copilot, etc.