PayZu Docs

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

前提条件

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

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

获取 token

使用 client_id 和 client_secret 通过 Basic Auth 调用 POST /token,并附带 mTLS 证书,然后在后续调用中将返回的 access_token 作为 Bearer token 使用。完整的请求和响应示例见身份认证。

创建第一笔收款

通过 POST /charges 创建收款。必填字段为 amount、customer、paymentType、cart、creditCardPayment 和 externalId。完整 schema 见接口参考。

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