ByteMax API

开始使用

集成时，您会用到：

• API 密钥：每次调用都放在 Authorization 请求头中。
• Idempotency-Key：每个操作使用一个密钥。因网络故障或 5xx 需要重复同一操作时，请复用同一个密钥（金额与幂等性）。
• payment.url：引导付款人前往的支付链接。
• order.completed webhook：通知您订单已支付；请用 GET /orders/{id} 确认（webhook）。

每笔订单都有两方：

四步创建第一笔订单。

1. 1
   创建 API 密钥

   在您控制台的 API 页面创建密钥并保存在您的服务器上：它只显示一次，并且可以访问您的整个账户。建议启用允许的 IP 列表，并填入将要调用 API 的服务器地址。列表关闭时，任何 IP 都可以使用该密钥。

2. 2
   发送请求头

   每次调用都要发送 Authorization。POST 和 PATCH 还要发送 Content-Type: application/json 和 UTF-8 编码的 JSON 正文，即使正文是 {}。创建订单和退款时，还要加上 Idempotency-Key：参见金额与幂等性。

   每次调用

   Authorization: Bearer <API_KEY>

   POST 和 PATCH

   Content-Type: application/json

3. 3
   获取报价（可选）

   报价不会创建任何内容。用它来确认密钥是否有效，并查看兑换金额。

   curl --request GET "https://bytemax.exchange/api/v1/quote?source_currency=BRL&target_currency=CNY&source_amount_cents=10000" \
     --header "Authorization: Bearer <API_KEY>"

   响应 200

   {
     "source_currency": "BRL",
     "source_amount_cents": "10000",
     "target_currency": "CNY",
     "target_amount_cents": "12500"
   }

4. 4
   创建第一笔订单

   使用新的 Idempotency-Key 调用 POST /orders，会创建一笔真实订单。将付款人引导至 payment.url，付款人在那里付款。如果未付款，订单会在 expires_at 过期，即创建后 48 小时。

   curl --request POST "https://bytemax.exchange/api/v1/orders" \
     --header "Authorization: Bearer <API_KEY>" \
     --header "Idempotency-Key: order-8412" \
     --header "Content-Type: application/json" \
     --data '{"source_currency":"BRL","source_amount_cents":"10000","target_currency":"CNY"}'

   响应 201

   {
     "id": "ord_example",
     "status": "pending_payment",
     "source_currency": "BRL",
     "source_amount_cents": "10000",
     "target_currency": "CNY",
     "target_amount_cents": "12500",
     "refunded_source_amount_cents": "0",
     "blocked_source_amount_cents": "0",
     "payment": {
       "url": "https://bytemax.exchange/pt-br/payment/0123456789abcdef0123456789abcdef",
       "pix_copy_paste": "00020101021226820014br.gov.bcb.pix2560pix.example/qr/v2/0123456789abcdef0123456789abcdef5204000053039865406100.005802BR5907BYTEMAX6009SAO PAULO62070503***6304ABCD"
     },
     "created_at": "2026-09-10T13:05:00.000Z",
     "expires_at": "2026-09-12T13:05:00.000Z"
   }

支付流程

订单从等待支付开始，最终变为已完成（已支付）、已过期或已取消。可以通过 Webhook 或查询来跟踪。

1. 1
   报价（可选）

   GET /quote 告诉您付款人支付多少、您收到多少。这只是预估：订单使用创建时刻的报价，Pix 的最低金额和上限也在那时才检查。

2. 2
   创建订单

   POST /orders，传入两个币种以及两个金额之一：付款人支付的金额或您收到的金额。响应包含支付链接 payment.url，以及 payment.pix_copy_paste，即付款人可以粘贴到银行应用中的 Pix 代码。

3. 3
   把付款人引导到支付链接

   将付款人重定向到 payment.url，或把该链接发给付款人。付款完成后，页面会在 5 秒后自动带付款人返回您在控制台 API 页面配置的返回 URL；支付页面上的“返回商家”链接也指向该地址。未配置该 URL 时，付款人会回到来源网站。

4. 4
   跟踪订单

   注册一个 Webhook：订单支付后会收到 order.completed，GET /orders/{id} 可确认其当前状态。

5. 5
   需要时办理退款

   POST /orders/{id}/refunds，传入您要从已收款项中退还的金额（CNY或USD）。该金额从您的余额中扣除，ByteMax 按原订单的比例计算付款人收回的 BRL：退还已收款项的一半，付款人就收回所付雷亚尔的一半。如果响应为 202，说明退款仍在处理中：用 GET /orders/{id}/refunds/{refund_id} 跟踪，不要再创建另一笔。

订单状态

pending_payment

等待支付。Pix 代码可在 expires_at 之前支付，即创建后 48 小时内。

completed

已支付。CNY或USD 金额已计入您的余额。最终状态。

expired

未在 expires_at 之前支付。最终状态。

canceled

由 ByteMax 取消，例如付款无法被接受并已退还给付款人。最终状态。

退款状态

processing

处理中。请持续查询，直到进入最终状态。如果退款长时间处于 processing，说明 ByteMax 正在审核：请联系客服。

succeeded

已完成。最终状态。

failed

退款无法完成。CNY或USD 金额会退回您的余额。最终状态。

金额与幂等性

金额与 ID

所有金额均为以分为单位的正整数字符串，不得以零开头，也不得包含符号、小数点或科学计数法。BRL、CNY和USD均使用2位精度："20000"代表指定币种的200单位。仅发送一个金额：source_amount_cents或target_amount_cents。

最低金额和 Pix 上限在创建订单时检查，报价时不检查。付款人至少需支付 R$ 30.00（ORDER_MINIMUM_NOT_MET）。Pix 支付的上限随汇率变动：超过时 API 返回 PIX_RECEIPT_LIMIT_EXCEEDED，message 中会说明当前的 BRL 上限。在任何调用中，您发送的金额都不能超过 "100000000"（1,000,000.00）。

所有 ID 也都是字符串：请以文本形式存储和比较，不要转换为数字。退款 ID（例如 "9007199254741001"）可能超过 JavaScript 能精确表示的最大整数。

幂等性

• 每个操作使用一个 Idempotency-Key：每笔新订单或新退款都有自己的密钥。
• 因网络故障或收到 5xx 响应而需要重复同一操作时，请复用相同的密钥和相同的正文。API 会返回已创建的订单或退款及其当前状态，不会重复创建。
• 请在您的系统中把密钥和对应的购买记录一起保存。

密钥长度为 1 到 80 个字符，可包含字母、数字、.、_、: 和 -。不要使用仅大小写不同的密钥。密钥不会过期，订单密钥也涵盖通过旧版 API 创建的订单。重复请求时，订单返回 200；退款在处理中时返回 202，之后返回 200。

特殊情况：相同密钥搭配不同正文会返回 409 IDEMPOTENCY_CONFLICT。密钥被预留前的拒绝不会占用它。为创建订单预留密钥后，收费或持久化失败可能使密钥保持处理中，即使订单尚未创建。发生网络故障或 5xx 后，请用相同密钥重复相同意图；不要更改正文，也不要换用新密钥重试。该密钥的创建操作仍在处理中时，重复请求会返回 409 CONFLICT。

参考

共五个操作。示例使用 <API_KEY> 和虚构的 ID。

curl --request GET "https://bytemax.exchange/api/v1/quote?source_currency=BRL&target_currency=CNY&source_amount_cents=10000" \
  --header "Authorization: Bearer <API_KEY>"

{
  "source_currency": "BRL",
  "source_amount_cents": "10000",
  "target_currency": "CNY",
  "target_amount_cents": "12500"
}

curl --request POST "https://bytemax.exchange/api/v1/orders" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Idempotency-Key: order-8412" \
  --header "Content-Type: application/json" \
  --data '{"source_currency":"BRL","source_amount_cents":"10000","target_currency":"CNY"}'

{
  "id": "ord_example",
  "status": "pending_payment",
  "source_currency": "BRL",
  "source_amount_cents": "10000",
  "target_currency": "CNY",
  "target_amount_cents": "12500",
  "refunded_source_amount_cents": "0",
  "blocked_source_amount_cents": "0",
  "payment": {
    "url": "https://bytemax.exchange/pt-br/payment/0123456789abcdef0123456789abcdef",
    "pix_copy_paste": "00020101021226820014br.gov.bcb.pix2560pix.example/qr/v2/0123456789abcdef0123456789abcdef5204000053039865406100.005802BR5907BYTEMAX6009SAO PAULO62070503***6304ABCD"
  },
  "created_at": "2026-09-10T13:05:00.000Z",
  "expires_at": "2026-09-12T13:05:00.000Z"
}

curl --request GET "https://bytemax.exchange/api/v1/orders/ord_example" \
  --header "Authorization: Bearer <API_KEY>"

{
  "id": "ord_example",
  "status": "pending_payment",
  "source_currency": "BRL",
  "source_amount_cents": "10000",
  "target_currency": "CNY",
  "target_amount_cents": "12500",
  "refunded_source_amount_cents": "0",
  "blocked_source_amount_cents": "0",
  "payment": {
    "url": "https://bytemax.exchange/pt-br/payment/0123456789abcdef0123456789abcdef",
    "pix_copy_paste": "00020101021226820014br.gov.bcb.pix2560pix.example/qr/v2/0123456789abcdef0123456789abcdef5204000053039865406100.005802BR5907BYTEMAX6009SAO PAULO62070503***6304ABCD"
  },
  "created_at": "2026-09-10T13:05:00.000Z",
  "expires_at": "2026-09-12T13:05:00.000Z"
}

curl --request POST "https://bytemax.exchange/api/v1/orders/ord_example/refunds" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Idempotency-Key: refund-8412-1" \
  --header "Content-Type: application/json" \
  --data '{"target_amount_cents":"2500"}'

{
  "id": "9007199254741001",
  "order_id": "ord_example",
  "status": "processing",
  "source_currency": "BRL",
  "source_amount_cents": "2000",
  "target_currency": "CNY",
  "target_amount_cents": "2500",
  "created_at": "2026-09-10T13:05:00.000Z",
  "updated_at": "2026-09-10T13:05:00.000Z"
}

curl --request GET "https://bytemax.exchange/api/v1/orders/ord_example/refunds/9007199254741001" \
  --header "Authorization: Bearer <API_KEY>"

{
  "id": "9007199254741001",
  "order_id": "ord_example",
  "status": "processing",
  "source_currency": "BRL",
  "source_amount_cents": "2000",
  "target_currency": "CNY",
  "target_amount_cents": "2500",
  "created_at": "2026-09-10T13:05:00.000Z",
  "updated_at": "2026-09-10T13:05:00.000Z"
}

错误与限制

每个错误响应都包含 code 和 message。请根据 code 编写处理逻辑：message 是供您记录日志的文本，可能会变化。请保留 X-Request-Id 响应头：联系客服时它用于识别这次调用。未知字段和重复参数会以 400 拒绝。维护或故障期间，响应可能不带 code：请把任何 5xx 或非 JSON 的正文视为临时故障。

{
  "code": "INVALID_INPUT",
  "message": "Use source_currency BRL and the supplier wallet currency, CNY or USD."
}

HTTP 状态码

错误代码

以下为最常见的代码。也可能出现其他代码：未知代码若状态码为 4xx，请视为重试也不会通过的拒绝；若为 5xx，请视为临时故障。

WALLET_CURRENCY_MISMATCHHTTP 409

目标币种必须与您账户的余额币种一致。

UNAUTHORIZEDHTTP 401

API 密钥缺失、格式错误或已失效。请检查 Authorization: Bearer <API_KEY> 请求头；如果您创建了新密钥，旧密钥即停止工作。

API_IP_NOT_ALLOWEDHTTP 403

调用来自允许的 IP 列表之外的地址。请在 API 页面添加您服务器的地址。

USER_BLOCKEDHTTP 403

您的账户已被封锁或关闭。联系客服。

KYC_KYB_REQUIREDHTTP 403

您的账户暂时无法创建订单。请在控制面板中完成身份验证；如果已经审核通过，请联系客服。

INVALID_INPUTHTTP 400

请求格式错误：某个字段、参数或请求头缺失、未知、重复或无效；正文不是 JSON；货币对不是 BRL → CNY或USD；或金额超过 "100000000"（1,000,000.00）。message 会说明需要修正的内容。金额必须是大于零的纯数字字符串，例如 "10000"。

JSON_REQUIREDHTTP 415

每个 POST 和 PATCH 都要带 Content-Type: application/json，即使正文是 {}。

ORDER_MINIMUM_NOT_METHTTP 400

付款人支付的金额低于 R$ 30.00 的最低限额。只传 CNY或USD 金额时同样适用。

PIX_RECEIPT_LIMIT_EXCEEDEDHTTP 400

付款人支付的金额超过当前的 Pix 上限，具体数值见 message。请用更低的金额重新创建订单，可以继续使用相同的 Idempotency-Key。

IDEMPOTENCY_CONFLICTHTTP 409

该密钥已用于正文不同的请求。新的操作请使用新密钥。

CONFLICTHTTP 409

使用该密钥的订单仍在创建中。请等待几秒，再使用相同的 Idempotency-Key 重试。

ORDER_NOT_FOUNDHTTP 404

您的账户中没有该 ID 的订单。已过期的订单会在创建 6 个月后移除。

ORDER_NOT_REFUNDABLEHTTP 409

订单尚未支付、已过期或已取消。只有 completed 状态的订单可以退款。

REFUND_NOT_FOUNDHTTP 404

该订单下没有此 ID 的退款。只显示由您的账户发起的退款。

REFUND_AMOUNT_NOT_AVAILABLEHTTP 400

金额超过仍可退款的部分：订单的一部分已经退款，或因争议被冻结。

REFUND_INVALID_AMOUNT_OR_RATIOHTTP 400

金额过小，无法换算为 BRL 退款。

REFUND_IN_PROGRESSHTTP 409

该订单的另一笔退款尚未结束。请等它进入最终状态。

INSUFFICIENT_BALANCEHTTP 400

您的 CNY或USD 余额不足以支付这笔退款。

PAYMENT_METHOD_RETIREDHTTP 410

订单通过已停用的方式支付。如需退款，请联系客服。

NOT_FOUNDHTTP 404

API 中不存在该地址或方法。没有列出订单或取消订单的操作。

PAYLOAD_TOO_LARGEHTTP 413

正文超过 1 MB。

SECURITY_BLOCKEDHTTP 403

安全过滤器因 URL 或正文中的异常字符序列而拒绝了请求。立即重复同一请求会收到 429 RATE_LIMIT_EXCEEDED。如果您的数据属正常内容，请联系客服并提供 X-Request-Id。

RATE_LIMIT_EXCEEDEDHTTP 429

超过调用限制。请等待 Retry-After 指定的时间。

SERVICE_UNAVAILABLEHTTP 503

操作所需的服务暂时不可用，或兑换已暂停。请几秒后使用相同的 Idempotency-Key 重试，并逐次延长等待时间。

INTERNAL_ERRORHTTP 500

意外故障。请几秒后使用相同的 Idempotency-Key 重试。如果问题持续，请联系客服并提供 X-Request-Id。

调用限制

每个 IP 地址每分钟最多向 ByteMax 发送 300 次请求（API 和网站合计）。GET /quote 每个账户每分钟 300 次，创建退款每个账户每分钟 30 次（包括在控制台发起的退款）。收到 429 时，请等待 Retry-After 指定的秒数后再重试。报价和退款的响应还会在下面的 RateLimit-* 响应头中报告账户限额；RateLimit-Reset 表示距离窗口重新开始的秒数。跟踪订单请使用 Webhook，而不是每隔几秒查询一次。

HTTP/1.1 429 Too Many Requests
Retry-After: 60
RateLimit-Policy: 300;w=60
RateLimit-Limit: 300
RateLimit-Remaining: 0
RateLimit-Reset: 60

集成摘要

一笔已支付订单的完整流程：

1. 1
   创建订单

   调用 POST /orders，为这笔购买使用一个新的 Idempotency-Key。

2. 2
   保存 id

   在您的系统中将订单 id 与这笔购买一起保存。

3. 3
   将付款人重定向到 payment.url

   或在您的结账页面显示 payment.pix_copy_paste。

4. 4
   接收 order.completed

   在您的 Webhook 中验证签名，并保存事件 id。

5. 5
   查询 GET /orders/{id}

   事件仅作通知；查询返回当前状态。

6. 6
   status 为 completed 时交付

   每笔订单只交付一次，即使事件重复送达。

集成有疑问？联系客服。