# API 端点 (/zh/docs/cartao/endpoints)

<QuickLinks>
  <QuickLink href="/docs/cartao/getting-started" title="快速开始" />

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

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

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

## 典型集成流程 [#典型集成流程]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;POST /token&#x22;] --> B[&#x22;POST /charges&#x22;]
  B --> C[&#x22;状态 webhook&#x22;]
  C --> D[&#x22;GET /charges/{chargeId}&#x22;]
  D --> E[&#x22;PUT /charges/{chargeId}/reverse&#x22;]

  click A &#x22;/docs/cartao/endpoints/token/post_token&#x22; &#x22;获取 token&#x22;
  click B &#x22;/docs/cartao/endpoints/charges/post_charges&#x22; &#x22;创建收款&#x22;
  click C &#x22;/docs/cartao/webhooks&#x22; &#x22;Webhooks&#x22;
  click D &#x22;/docs/cartao/endpoints/charges/get_charges__chargeId_&#x22; &#x22;查询收款&#x22;
  click E &#x22;/docs/cartao/endpoints/charges/put_charges__chargeId__reverse&#x22; &#x22;收款退款&#x22;

  style B fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

流程是:获取 token,创建收款,通过 webhook 接收处理结果,需要时查询状态,必要时发起退款。

## Token [#token]

API 身份认证:用 `client_id` 和 `client_secret` 换取 JWT token。

<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints/token/post_token" title="获取 API token" method="POST" path="/token" />
</QuickLinks>

## 收款 [#收款]

创建、查询和退款信用卡收款。

<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints/charges/post_charges" title="创建收款" method="POST" path="/charges" />

  <QuickLink href="/docs/cartao/endpoints/charges/get_charges" title="收款列表" method="GET" path="/charges" />

  <QuickLink href="/docs/cartao/endpoints/charges/get_charges__chargeId_" title="查询收款" method="GET" path="/charges/{chargeId}" />

  <QuickLink href="/docs/cartao/endpoints/charges/put_charges__chargeId__reverse" title="收款退款" method="PUT" path="/charges/{chargeId}/reverse" />
</QuickLinks>

## 循环扣款 [#循环扣款]

管理通过 `POST /charges` 中的 `recurrence` 节点创建的订阅。

<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints/recurrences/get_charges_recurrences__recurrentPaymentId_" title="查询循环扣款" method="GET" path="/charges/recurrences/{recurrentPaymentId}" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__amount" title="修改循环扣款金额" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/amount" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__deactivate" title="停用循环扣款" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/deactivate" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__reactivate" title="重新激活循环扣款" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/reactivate" />
</QuickLinks>

## 汇率 [#汇率]

用于国际收款的参考汇率与换算。

<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints/currencies/get_currency_rate" title="获取汇率" method="GET" path="/currencies/{code}/rate" />

  <QuickLink href="/docs/cartao/endpoints/currencies/get_currency_convert" title="金额换算" method="GET" path="/currencies/{code}/convert" />

  <QuickLink href="/docs/cartao/endpoints/currencies/get_currency_rates" title="汇率列表" method="GET" path="/currencies/rates" />
</QuickLinks>

## 约定 [#约定]

| 项目                | 值                                                                                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base URL(生产环境)    | `https://api.payzu.io/v1`                                                                                                                            |
| Base URL(sandbox) | `https://api.sandbox.payzu.io/v1`                                                                                                                    |
| 身份认证              | mTLS(客户端证书)+ `Authorization: Bearer YOUR_TOKEN`,通过 [`POST /token`](/docs/cartao/endpoints/token/post_token) 获取。参见[身份认证](/docs/cartao/authentication) |
| Content-Type      | `application/json`                                                                                                                                   |
| 金额                | 以分为单位(`10000` = R$ 100,00)。汇率(`rate.bid`、`rate.ask`)为小数                                                                                              |