创建 Payout

Quick Reference

What发起由钱包提供资金的付款（payout）

Why通过单一统一端点向拉美各地的供应商、合作伙伴和客户付款

Reading Time10 分钟

DifficultyIntermediate

Prerequisites身份验证 → 一个有余额的钱包 → 已注册的 merchant（当您的账户需要时）

POST/api/v1/bank/wallet/payout/Bearer Token创建从钱包扣款的 payout

Payout 的工作原理

Payout 是出账流程——资金离开平台，与收款相反。单一端点处理所有支付通道；type_payout 字段选择使用哪个通道，每种类型都需要其对应的目标对象。

Payout 流程

Payout 状态

状态	含义	终态？
`pending`	已创建，等待处理	否
`issued`	已发送至 provider	否
`realized`	已确认并结算	是
`returned`	被接收银行退回	是
`canceled`	已取消	是
`error`	处理失败	是
`expired`	已过期	是

请求头

Header	值	必填
`Authorization`	`Bearer {A55_ACCESS_TOKEN}`	是
`Content-Type`	`application/json`	是

请求体

字段	类型	必填	说明
`wallet_uuid`	string (UUID)	是	为 payout 提供资金的钱包
`type_payout`	string	是	支付通道：`pix`、`bank_transfer`、`ted`、`spei`、`cash_pickup`
`value`	number (float)	是	发送金额。必须大于零
`description`	string	是	payout 的自由文本描述
`currency`	string	否	ISO 4217 代码。省略时使用钱包货币
`merchant_id`	string (UUID)	否	payout 所属的 merchant。当您的账户使用 merchant 时必填
`transaction_reference`	string	否	外部幂等键（按钱包范围）。省略时生成 UUID
`schedule_date`	string	否	`YYYY-MM-DD` 用于排定 payout
`country_code`	string	否	目标地的 ISO 3166-1 alpha-2
`providers`	string[]	否	用于强制路由到特定 provider 的 UUID
`webhook_url`	string (URL)	否	状态变更时通知的 URL
`pix_destination`	object	条件性	当 `type_payout` 为 `pix` 时必填
`bank_destination`	object	条件性	当 `type_payout` 为 `bank_transfer`、`ted` 或 `spei` 时必填
`cash_destination`	object	条件性	当 `type_payout` 为 `cash_pickup` 时必填

`pix_destination`

字段	类型	必填	说明
`pix_address_key`	string	是	PIX 密钥值
`pix_address_key_type`	string	是	PIX 密钥类型（`cpf`、`cnpj`、`email`、`phone`、`evp`）
`beneficiary_name`	string	否	受益人全名
`beneficiary_tax_id`	string	否	受益人 CPF/CNPJ。email/phone/evp 密钥必填；cpf/cnpj 密钥可选（用密钥作为证件）

`bank_destination`（bank_transfer / ted / spei）

字段	类型	必填	说明
`country_code`	string	是	ISO-3166 alpha-2 或 alpha-3
`beneficiary_name`	string	是	受益人名
`beneficiary_last_name`	string	是	受益人姓
`document_type`	string	是	Cedula / RUC / DPI / RUT / CPF 等
`beneficiary_tax_id`	string	是	受益人证件号
`account_number`	string	条件性	账号、CBU/CVU、CCI、CLABE 等。除非使用 `bank_alias` 否则必填
`bank_alias`	string	条件性	阿根廷 CBU 别名（6-20 字符）。`account_number` 的替代项
`bank_code`	string	否	provider 银行代码。巴西 TED：8 位 ISPB 或 COMPE（如 `001`）
`account_type`	string	否	储蓄/活期/Cash/RUT 等（因国家而异）
`account_agency`	string	否	银行分行/网点（巴西 TED）
`bank_name`	string	否	银行名称
`beneficiary_email`	string	否	当 `account_type` 为 `Cash` 时必填
`beneficiary_phone`	string	否	受益人电话
`expiration_date`	string	否	`YYYY-MM-DD`（现金网络）

`cash_destination`（cash_pickup）

字段	类型	必填	说明
`country_code`	string	是	目标国家
`bank_code`	string	是	现金网络代码（如 `010`、`456`）
`beneficiary_name`	string	是	受益人姓名
`beneficiary_email`	string	是	提取码将发送到此邮箱
`document_type`	string	是	受益人证件类型
`beneficiary_tax_id`	string	是	受益人证件号
`beneficiary_last_name`	string	否	受益人姓
`beneficiary_phone`	string	否	受益人电话
`expiration_date`	string	否	`YYYY-MM-DD` 提取过期日

响应字段

字段	类型	说明
`payout_uuid`	string	payout 内部标识符
`external_id`	string	provider 的 payout id
`status`	string	当前 payout 状态（见上表）
`type_payout`	string	使用的通道
`amount`	number (float)	payout 金额
`fee`	number (float)	provider 费用
`currency`	string	ISO 4217 货币
`description`	string	payout 描述
`country_code`	string	目标国家
`beneficiary_name`	string	受益人姓名
`transaction_reference`	string	使用的幂等键
`submitted_date`	string	发送至 provider 的日期
`confirmed_date`	string	确认日期
`schedule_date`	string	排定日期（如适用）
`payment_code`	string	现金提取码（仅现金 payout）
`authorization_code`	string	provider 授权码（如可用）
`authorization_date`	string	授权日期（如可用）
`transaction_id`	string	provider 交易 id（如可用）
`destination`	object	目标数据回显
`message`	array	provider/处理消息
`created`	string	创建时间戳（ISO 8601）
`updated`	string	最后更新时间戳（ISO 8601）

错误响应

状态码	代码	说明
400	`errors.payout.validate_error`	载荷校验失败（缺少 `type_payout`、`value <= 0`、缺少目标字段等）
400	`errors.payout.destination_invalid`	目标对象对所选 `type_payout` 无效
400	`errors.payout.provider_not_valid`	没有符合此 payout 的 provider
400	`errors.wallet.payout_already_exists`	该钱包已存在相同 `transaction_reference` 的 payout
400	`errors.wallet.daily_transaction_limit_exceeded`	将超出钱包每日限额
400	`errors.wallet.merchant_invalid`	merchant 不属于钱包的账户
401	`unauthorized`	Bearer 令牌无效或过期
404	`errors.wallet.not_found`	钱包未找到
404	`errors.payout.merchant_not_found`	merchant 未找到
422	`errors.payout.insufficient_balance`	钱包余额不足以支付此 payout

代码示例

PIX out（巴西）

cURL
Python
Node.js

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "pix",
    "value": 100.00,
    "currency": "BRL",
    "description": "供应商付款 #2048",
    "transaction_reference": "PAY-2048",
    "webhook_url": "https://your-app.com/webhooks/a55/payouts",
    "pix_destination": {
      "pix_address_key": "joao@example.com",
      "pix_address_key_type": "email",
      "beneficiary_name": "João Silva",
      "beneficiary_tax_id": "12345678901"
    }
  }'

import requests
import os

token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://sandbox.api.a55.tech")

response = requests.post(
    f"{base}/api/v1/bank/wallet/payout/",
    json={
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "type_payout": "pix",
        "value": 100.00,
        "currency": "BRL",
        "description": "供应商付款 #2048",
        "transaction_reference": "PAY-2048",
        "webhook_url": "https://your-app.com/webhooks/a55/payouts",
        "pix_destination": {
            "pix_address_key": "joao@example.com",
            "pix_address_key_type": "email",
            "beneficiary_name": "João Silva",
            "beneficiary_tax_id": "12345678901",
        },
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)
payout = response.json()
print(f"Payout {payout['payout_uuid']} — 状态: {payout['status']}")

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://sandbox.api.a55.tech";

const payout = await fetch(`${base}/api/v1/bank/wallet/payout/`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    type_payout: "pix",
    value: 100.0,
    currency: "BRL",
    description: "供应商付款 #2048",
    transaction_reference: "PAY-2048",
    webhook_url: "https://your-app.com/webhooks/a55/payouts",
    pix_destination: {
      pix_address_key: "joao@example.com",
      pix_address_key_type: "email",
      beneficiary_name: "João Silva",
      beneficiary_tax_id: "12345678901",
    },
  }),
}).then((r) => r.json());

console.log(`Payout ${payout.payout_uuid} — 状态: ${payout.status}`);

TED（巴西）

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "ted",
    "value": 500.00,
    "currency": "BRL",
    "description": "供应商结算",
    "transaction_reference": "PAY-2049",
    "bank_destination": {
      "country_code": "BR",
      "bank_code": "341",
      "account_type": "checking",
      "account_number": "12345-6",
      "account_agency": "0001",
      "bank_name": "Itaú",
      "beneficiary_name": "Maria",
      "beneficiary_last_name": "Costa",
      "document_type": "CPF",
      "beneficiary_tax_id": "98765432100"
    }
  }'

SPEI（墨西哥）

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "spei",
    "value": 1500.00,
    "currency": "MXN",
    "description": "Payout MXN",
    "transaction_reference": "PAY-2050",
    "bank_destination": {
      "country_code": "MX",
      "account_number": "012180012345678901",
      "beneficiary_name": "Carlos",
      "beneficiary_last_name": "Hernández",
      "document_type": "RFC",
      "beneficiary_tax_id": "HEGC800101XXX"
    }
  }'

银行转账（LATAM）

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "bank_transfer",
    "value": 250.00,
    "currency": "ARS",
    "description": "Payout 阿根廷",
    "transaction_reference": "PAY-2051",
    "bank_destination": {
      "country_code": "AR",
      "bank_alias": "mi.alias.cbu",
      "beneficiary_name": "Lucía",
      "beneficiary_last_name": "Gómez",
      "document_type": "DNI",
      "beneficiary_tax_id": "20304050607"
    }
  }'

现金提取（厄瓜多尔）

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "cash_pickup",
    "value": 200.00,
    "currency": "USD",
    "description": "现金提取 payout",
    "transaction_reference": "PAY-2052",
    "cash_destination": {
      "country_code": "EC",
      "bank_code": "456",
      "beneficiary_name": "Pedro",
      "beneficiary_email": "pedro@example.com",
      "document_type": "Cedula",
      "beneficiary_tax_id": "1234567890"
    }
  }'

完整响应示例

PIX payout 已接受

{
  "payout_uuid": "9b1f0c88-3a3c-4f2f-9d6e-1f0a2d4e88c1",
  "external_id": "MN-20260616-0001",
  "status": "issued",
  "type_payout": "pix",
  "amount": 100.00,
  "fee": 0.50,
  "currency": "BRL",
  "description": "供应商付款 #2048",
  "country_code": "BR",
  "beneficiary_name": "João Silva",
  "transaction_reference": "PAY-2048",
  "submitted_date": "2026-06-16",
  "confirmed_date": null,
  "schedule_date": null,
  "destination": {
    "pix_address_key": "joao@example.com",
    "pix_address_key_type": "email"
  },
  "message": [],
  "created": "2026-06-16T18:00:00Z",
  "updated": "2026-06-16T18:00:00Z"
}

现金提取已接受（含提取码）

{
  "payout_uuid": "5c2a13f0-5e74-4b21-9c6a-2bd9d9b0aa10",
  "external_id": "MN-20260616-0002",
  "status": "issued",
  "type_payout": "cash_pickup",
  "amount": 200.00,
  "fee": 1.20,
  "currency": "USD",
  "description": "现金提取 payout",
  "country_code": "EC",
  "beneficiary_name": "Pedro",
  "transaction_reference": "PAY-2052",
  "payment_code": "EC-PICKUP-7788",
  "message": [],
  "created": "2026-06-16T18:05:00Z",
  "updated": "2026-06-16T18:05:00Z"
}

务必通过 Webhook 确认

同步响应返回初始状态。payout 通常会从 issued 异步推进到 realized。设置 webhook_url 并将 Webhook 视为最终结果的事实来源。参见 Payout Webhook。

查询 payout →获取 payout 的当前状态和详情。Payout 列表 →列出并筛选钱包的 payout。Payout Webhook →在 payout 状态变更时接收通知。

Quick Reference

Payout 的工作原理​

Payout 流程​

Payout 状态​

请求头​

请求体​

pix_destination​

bank_destination（bank_transfer / ted / spei）​

cash_destination（cash_pickup）​

响应字段​

错误响应​

代码示例​

PIX out（巴西）​

TED（巴西）​

SPEI（墨西哥）​

银行转账（LATAM）​

现金提取（厄瓜多尔）​

完整响应示例​

PIX payout 已接受​

现金提取已接受（含提取码）​