# 快速开始 (/zh/docs/cartao/getting-started)

<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints" title="API 参考" />

  <QuickLink href="/docs/cartao/authentication" title="身份认证" />

  <QuickLink href="/docs/cartao/test-cards" title="测试卡" />

  <QuickLink href="/docs/cartao/transaction-status" title="交易状态" />

  <QuickLink href="/docs/cartao/webhooks" title="Webhooks" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;证书 + 凭证&#x22;] --> B[&#x22;获取 token&#x22;]
  B --> C[&#x22;创建收款&#x22;]
  C --> D[&#x22;解读响应&#x22;]
  D --> E[&#x22;测试场景&#x22;]

  click B &#x22;/docs/cartao/endpoints/token/post_token&#x22; &#x22;POST /token&#x22;
  click C &#x22;/docs/cartao/endpoints/charges/post_charges&#x22; &#x22;POST /charges&#x22;
  click D &#x22;/docs/cartao/transaction-status&#x22; &#x22;交易状态&#x22;
  click E &#x22;/docs/cartao/test-cards&#x22; &#x22;测试卡&#x22;

  style A fill:#f59e0b,stroke:#d97706,color:#ffffff
  style E fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

本指南使用 **sandbox**(`https://api.sandbox.payzu.io/v1`)。生产环境的基础 URL 为 `https://api.payzu.io/v1`。

<Steps>
  <Step>
    ### 前提条件 [#前提条件]

    在发起第一次调用之前,您需要准备两项内容,均由 PayZu 团队提供:

    * **客户端 mTLS 证书**(`cliente.crt`、`cliente.key` 和 `ca.pem`)。请安装证书并配置您的系统,在**所有** API 调用中使用它,且始终通过 HTTPS。详见[身份认证](/docs/cartao/authentication)。
    * **凭证** `client_id` 和 `client_secret`,用于获取访问 token。
  </Step>

  <Step>
    ### 获取 token [#获取-token]

    使用 `client_id` 和 `client_secret` 通过 **Basic Auth** 调用 [`POST /token`](/docs/cartao/endpoints/token/post_token),并附带 mTLS 证书,然后在后续调用中将返回的 `access_token` 作为 Bearer token 使用。完整的请求和响应示例见[身份认证](/docs/cartao/authentication)。
  </Step>

  <Step>
    ### 创建第一笔收款 [#创建第一笔收款]

    通过 [`POST /charges`](/docs/cartao/endpoints/charges/post_charges) 创建收款。必填字段为 `amount`、`customer`、`paymentType`、`cart`、`creditCardPayment` 和 `externalId`。完整 schema 见接口参考。

    ```bash
    curl --request POST \
      --url https://api.sandbox.payzu.io/v1/charges \
      --header "Authorization: Bearer SEU_ACCESS_TOKEN" \
      --header 'Content-Type: application/json' \
      --cert cliente.crt \
      --key cliente.key \
      --cacert ca.pem \
      --data '{
        "amount": 10000,
        "externalId": "order-2026-0001",
        "paymentType": "creditcard",
        "customer": {
          "name": "John Smith"
        },
        "cart": [
          {
            "name": "Monthly plan",
            "quantity": 1,
            "sku": "PLAN-01",
            "unitPrice": 10000
          }
        ],
        "creditCardPayment": {
          "installments": 1,
          "authenticate": false,
          "card": {
            "number": "4111111111111111",
            "holder": "JOAO DA SILVA",
            "expiration": "12/2030",
            "cvv": "123"
          }
        }
      }'
    ```

    在生产环境中,请将基础 URL 换成 `https://api.payzu.io/v1`。

    <Callout type="info">
      金额字段(`amount`、`unitPrice`)始终以**分**为单位。`10000` 相当于 R$ 100,00。
    </Callout>

    当 `authenticate: false` 时,买家不会被引导至发卡行进行身份认证。如需认证流程,请参阅 [3D Secure](/docs/cartao/three-d-secure)。
  </Step>

  <Step>
    ### 解读响应 [#解读响应]

    响应包含收款的 `id`、传入的 `externalId`,以及带有 `status`、`reasonCode` 和 `reasonMessage` 的 `creditCardPayment` 对象。主要状态如下:

    | 代码 | 状态               | 含义                   |
    | -- | ---------------- | -------------------- |
    | 1  | Authorized       | 已获发卡行授权,可进行请款,但尚未完成。 |
    | 2  | PaymentConfirmed | 支付已确认并完成。            |
    | 3  | Denied           | 支付被授权方拒绝。            |

    如果 `creditCardPayment.status` 返回 `2`(PaymentConfirmed),您的第一笔收款已确认。完整的代码列表见[交易状态](/docs/cartao/transaction-status)。
  </Step>

  <Step>
    ### 测试场景并配置 webhooks [#测试场景并配置-webhooks]

    要在 sandbox 中模拟批准、拒绝和超时,请使用[测试卡](/docs/cartao/test-cards):卡号的末位数字决定交易结果。

    要在无需轮询 API 的情况下接收收款状态通知,请在创建收款时传入 `postbackUrl`。payload 结构与校验方法见 [Webhooks](/docs/cartao/webhooks)。
  </Step>
</Steps>

## 下一步 [#下一步]

<QuickLinks>
  <QuickLink href="/docs/cartao/three-d-secure" title="3D Secure" />

  <QuickLink href="/docs/cartao/antifraud" title="反欺诈" />

  <QuickLink href="/docs/cartao/recurrence" title="循环扣款" />

  <QuickLink href="/docs/cartao/international" title="跨境收款" />
</QuickLinks>