开户 — 个人 (PF)

本指南介绍如何使用默认的 CorpX 生物识别流程开立个人账户：我们生成人脸采集链接，您交付给最终用户，人脸验证通过后账户将自动开立 — 无需人工审核。

流程

第 1 步：创建 accreditation

请求

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/pf" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-customer-12345" \
  -d '{
    "person": {
      "name": "Maria da Silva",
      "cpf": "12345678901",
      "birthDate": "1990-05-20",
      "email": "maria@email.com",
      "phone": "+5511999998888",
      "monthlyIncome": 5000.00
    },
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Apto 42",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "cityIbgeCode": "3550308"
    }
  }'

参数

字段	类型	必填	说明
`person.name`	string	是	持有人全名。
`person.cpf`	string	是	CPF（11 位数字，无标点）。
`person.birthDate`	string	是	出生日期（`YYYY-MM-DD`）。
`person.email`	string	是	持有人邮箱。
`person.phone`	string	是	电话，格式为国际区号 + 区号 + 号码（如 `+5511999998888`）。
`person.monthlyIncome`	number	否	申报月收入（BRL）。
`address.*`	object	是	完整地址。`cityIbgeCode` 为 7 位 IBGE 城市代码。
`biometry`	object	否	仅用于自带生物识别流程。
`callbackUri`	string	否	流程结束后把持有人带回何处。需事先向支持团队登记 —— 参见返回您的应用。

初始 PIX 限额将自动应用保守默认值。限额变更（上调或下调）需向支持人工申请。

响应 (201)

{
  "accreditationId": "acr_9f8e7d6c5b4a",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "type": "pf",
  "status": "PENDING_BIOMETRY",
  "persons": [
    {
      "personId": "prs_3b1c9a7f2e4d",
      "cpf": "12345678901",
      "name": "Maria da Silva",
      "biometryStatus": "PENDING",
      "biometryLink": "https://cadastro.unico.app/process/abc123...",
      "linkExpiresAt": "2026-07-14T18:00:00Z"
    }
  ],
  "createdAt": "2026-07-07T18:00:00Z"
}

personId 是该人在此 accreditation 中的稳定标识符。请用它来关联返回您应用的跳转（参见返回您的应用）—— 出现在返回 URI 中的是 personId，而不是 CPF。

账户尚未绑定

在状态为 PENDING_BIOMETRY 时，CPF 不会绑定到 tenant，accountId 尚不存在。POST 不会去重——用同一 CPF 重复请求会创建新的 accreditation。请保存 accreditationId，对放弃的待处理流程使用 POST /v1/accreditations/{id}/cancel 取消。accountId 仅在生物识别确认后出现。

异步链接

biometryLink 会在数秒内生成，但生成过程是异步的——极少数情况下 POST 响应中可能暂缺该字段。此时请通过 accreditation.biometry.link.created webhook 接收，或随后调用 GET 查询。

已有账户的 CPF

如果该 CPF 已是账户持有人，且您的租户已开通自动携带，响应会返回 status: "PENDING_CONSENT"，并以 consentLink 取代 biometryLink — 此时没有需要新开的账户，而是需要持有人授权您操作其已有账户。未开通时（默认），该 accreditation 会以 existing_partner_account 失败，携带流程通过支持团队办理。参见下文已有账户的持有人（授权）。

第 2 步：交付人脸链接

通过您偏好的渠道（应用内、WhatsApp、SMS、邮件）将 biometryLink 交付给最终用户。采集流程在手机浏览器中运行，无需安装应用。

链接 7 天后过期（linkExpiresAt）。如已过期，使用重试端点（第 4 步）。
同一链接也会通过 accreditation.biometry.link.created webhook 送达。

第 3 步：等待完成

用户完成采集且生物识别通过后，审批是自动的 — 默认流程中 PF 无需人工审核。通过 webhook 跟踪：

accreditation.updated — PENDING_BIOMETRY → INTEGRATING；
accreditation.active — 账户已开立；accountId 可以使用。

如果生物识别被拒或过期，您会收到包含该人详情的 accreditation.updated，可进行重试。

也可以轮询查询：

curl -X GET "https://tenant.api.corpx.com/v1/accreditations/pf?document=12345678901" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany"

第 4 步：重试（链接过期或生物识别被拒）

如果链接过期或采集失败，为该人生成新链接：

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_9f8e7d6c5b4a/persons/12345678901/retry" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany"

响应包含新的 biometryLink 和新的 linkExpiresAt。accreditation.biometry.link.created 事件也会重新发出。

第 5 步：取消（放弃的待处理流程）

若用户在生物识别前放弃，可在状态仍为 PENDING_BIOMETRY（或 PENDING_CONSENT）时取消：

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_9f8e7d6c5b4a/cancel" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -d '{"reason":"customer abandoned onboarding"}'

结果为 FAILED，errorReason=cancelled（webhook：accreditation.updated / accreditation.failed）。生物识别确认后不可再取消（409 invalid_state）。

已有账户的持有人（授权）

当所填 CPF 已是账户持有人时，没有需要新开的账户。此时的路径是由持有人授权您操作其已有账户 — 该授权由持有人本人在我们托管的页面上完成，并需通过身份验证。

POST /v1/accreditations/pf 的调用方式不变：您无需事先做任何判断。变化的是响应。

需按合同开通

自动携带（portability）默认未开通。该能力会转移一个已有账户中资金的控制权，因此需要专门的合同，并由我们团队按租户逐一开通。

未开通时，已有账户的 CPF 仍会以 FAILED 结束，errorReason=existing_partner_account，并提示持有人向支持团队申请携带；此时流程由我们人工处理，不会签发 consentLink。

如需开通，请联系您的 CorpX 商务对接人。

授权模式下的响应（201）

{
  "accreditationId": "acr_5c4b3a2f1e0d",
  "type": "pf",
  "status": "PENDING_CONSENT",
  "persons": [
    {
      "personId": "prs_3b1c9a7f2e4d",
      "cpf": "12345678901",
      "name": "Maria da Silva",
      "biometryStatus": "PENDING",
      "consentStatus": "PENDING",
      "consentLink": "https://tenant.api.corpx.com/v1/accreditations/consent/cst_...",
      "consentExpiresAt": "2026-07-30T18:00:00Z"
    }
  ],
  "createdAt": "2026-07-23T18:00:00Z"
}

字段	说明
`status`	`PENDING_CONSENT` — 等待持有人授权。
`persons[].consentLink`	授权页面。像交付人脸链接一样交付给持有人。
`persons[].consentStatus`	`PENDING`、`ACCEPTED`、`DECLINED`、`DENIED` 或 `EXPIRED`。
`persons[].consentExpiresAt`	链接有效期（7 天）。整个流程 30 天后失效。

同一链接也会通过 accreditation.consent.link.created webhook 送达 — 如果您的集成通过 webhook 获取链接，请务必订阅该事件，因为 accreditation.updated 不携带任何链接。

重新提交 POST 不会重新签发授权链接

流程处于 PENDING_CONSENT 期间，对同一 CPF 重复调用 POST /v1/accreditations/pf 会返回 409 already_accredited — 其中 accountId: null、status: "PENDING_CONSENT"，并带上正在进行中的 accreditationId。这不表示您的租户已有账户，而是持有人的授权仍在等待中。

与其重新提交，请用以下方式取回链接：

GET /v1/accreditations/{accreditationId} 会在 persons[].consentLink 中返回当前链接，并附带 consentExpiresAt。
POST /v1/accreditations/{accreditationId}/persons/{cpf}/retry 会重新签发链接，有效期重置为 7 天（与第 4 步相同的端点），前提是 30 天的整体流程尚未失效。

如果确实要放弃该流程，请先用 POST /v1/accreditations/{accreditationId}/cancel（第 5 步）取消，再创建新的。

流程

持有人会看到什么

在任何采集之前，页面会说明是谁在申请权限，以及该授权允许的操作 — 包括动账与提现。
身份验证：活体自拍，按 CPF 与官方数据库核验。未通过则页面不会继续。
仅在身份确认之后，才会显示账号与当前余额 — 让持有人在清楚知道涉及哪笔资金的前提下授权。
明示授权，并记录日期、时间、设备以及当时展示的余额。

授权仅在通过身份验证的同一会话、同一设备上有效。将链接转给他人、重复提交页面的 POST、或复用较早的验证结果，均不构成有效授权。

授权之后

您会收到带 sharedAccount: true 的 accreditation.active，以及可正常操作的 accountId。两点很重要：

这是同一个账户，不是副本：余额、对账单与 Pix 密钥都是原有的。accountId 是该账户在您 tenant 内的标识符。
原先操作该账户的一方继续保留权限。 持有人授权的所有 tenant 都会收到每笔动账的 webhooks — 包括非经您 API 发起的操作（会带 external: true）。

如果持有人未授权，accreditation 以 FAILED 结束，errorReason 为以下之一：consent_declined、consent_expired、consent_facial_failed、castle_deny 或 consent_link_failed（详见 Onboarding Webhooks）。

撤销

持有人可随时通过支持撤销已授予的权限。撤销后，被撤销 tenant 对该账户的调用返回 403 — 该账户对持有人及其他获授权 tenant 仍然有效。

账户就绪

状态为 ACTIVE 时，账户已绑定到您的 tenant 并可以操作。在其他所有 API 端点使用该 accountId — PIX、对账单、boleto、二维码等。

提示

在您的系统中保存 accreditationId + accountId。此后所有银行操作都将使用 accountId 作为标识符。

流程​

第 1 步：创建 accreditation​

请求​

参数​

响应 (201)​

第 2 步：交付人脸链接​

第 3 步：等待完成​

第 4 步：重试（链接过期或生物识别被拒）​

第 5 步：取消（放弃的待处理流程）​

已有账户的持有人（授权）​

授权模式下的响应（201）​

流程​

持有人会看到什么​

授权之后​

账户就绪​

流程