Cryptanio
账户

如何在自己的网站接受 USDC 付款

为一笔订单配置在指定网络上的 USDC 付款：核对准确的代币，将地址连接到项目，创建账单，并在服务器端确认付款结果。

更新日期:

要在网站接受 USDC 付款，应将订单与 Cryptanio 账单关联，并提前确定网络和具体代币。下面以一家约定接受 Ethereum 网络 USDC 付款的商店为例。服务器为订单创建单独的账单，买家获得付款页面，核实结果后再确认订单。资金直接进入您的地址。

这是固定资产的付款场景：买家必须发送付款信息中指定的 USDC，而不能发送任意名称相似的币种。关于选择付款链接还是服务器集成，可参阅网站接受加密货币付款指南。

1. 确认您接受的是哪一种 USDC

将网络和代币标识符与 Circle 官方目录核对。仅凭 USDC 名称和钱包显示的图标并不足以判断。Circle 支持某个网络，也不代表您的 Cryptanio 项目已启用这一收款路径。

Circle 区分由发行方直接在该网络发行的 native USDC，以及由第三方跨链桥创建的 bridged USDC。在账单付款中，不应将这两种形式视为可以互换；区别见 Circle 的说明。这里选择 Ethereum 网络上受支持的 Circle USDC。如果使用其他网络，应重新核对该网络的代币及其可用性。

native USDC 中的 native 并不表示区块链的原生币。在 Ethereum 上，USDC 仍然是代币，原生币则是 ETH。填写地址信息时需要注意这一区别。

2. 准备接收指定资产的地址

您需要一个已启用“支付”服务的项目、自己钱包的公开地址，以及配置项目的权限。打开“支付”，选择项目和“地址”部分，再点击“添加地址( 地址 )”。在“手动”选项卡中选择 Ethereum，输入由您控制的地址。

选择“一个资产”，在“资产”中填写该网络受支持的 USDC 标识符，并与 Circle 目录核对。字段留空表示原生币，而不是 native USDC。保持“转入”开启，添加地址后检查连接是否处于启用状态、网络是否可用。仅仅将地址保存到地址簿，并不会把它连接到所需服务的收款功能。

如果使用手动地址池，应准备一个可分配给付款信息的空闲地址。不要提供私钥或助记词：连接公开地址不需要这些信息。核对网络与代币组合的基础知识，见《网络和代币有什么区别》。

3. 为订单创建账单

准备一个供服务器使用的正式环境 API 密钥，使其能访问该项目，并具有 invoices（“账单”）部分的“读与写”权限。发送请求前，先保存您自己的订单编号。不得将密钥交给买家。

下面是 API v1 支持的固定资产示例。请在生成的请求中核对订单的网络、资产和金额。USDC 金额表示代币数量，并不表示向银行账户收取美元：

#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
: "${CRYPTANIO_OPERATION_ID:?Set CRYPTANIO_OPERATION_ID}"
: "${CRYPTANIO_PROJECT_ID:?Set CRYPTANIO_PROJECT_ID}"
json_string() {
  local text="$1" char code index output='"'
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in
      '"'|'\') output+="\\$char" ;;
      *) printf -v code '%d' "'$char"
         if ((code < 32)); then printf -v char '\\u%04x' "$code"; fi
         output+="$char" ;;
    esac
  done
  printf '%s"' "$output"
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request POST \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CRYPTANIO_OPERATION_ID" \
  --data-binary '{"project":'"$(json_string "$CRYPTANIO_PROJECT_ID")"',"chain":"ethereum","asset":"USDC","amount":"12.50","reference":"order-42","expires_in":60,"customer":{"id":"customer-42"},"metadata":{"order":"42"}}' \
  "https://api.cryptanio.com/v1/invoices" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

下载示例

填写您自己的项目和订单信息。新操作应使用唯一的 Idempotency-Key；故障后重试同一请求时，应继续使用原来的密钥。保存订单与所创建账单 ID 的关联、返回的 checkout_url，以及响应中的准确付款信息。不要对返回金额进行四舍五入，也不要用价目表上的数字替换它。

4. 向客户提供付款页面

让客户从网站的订单页面打开返回的 checkout_url。不要根据账单 ID 自行拼接页面地址，也不要用固定钱包地址替换已分配的付款信息。在这一场景中，网络和资产已经选定，客户需要在发送前于钱包中核对这两项。

请客户按照准确金额发送，同时考虑钱包的手续费规则和付款期限。如果客户持有的是另一种版本的 USDC，仅更改代币名称并不能使转账符合要求。应先商定正确的转账路径，不要承诺 Cryptanio 会自动兑换或提供跨链桥。

5. 确认订单并检查完整流程

服务器必须通过 webhook 或 API 轮询核查账单的最新状态。只有状态为 paid 时才履行订单，并保留防止重复执行的机制。发现一笔交易、收到截图或买家返回网站，都不能替代这一步核查。

对于少付、多付、逾期到账和交易回滚，应按照具体账单的状态处理。如有争议，请保存 TXID，并参阅未付款订单排查指南。不要仅因金额相似，就把另一种资产的到账计入该订单。

用您自己的订单检查完整流程：付款信息、发送、确认和订单履行。在正式环境模式中，使用的是真实资金，也会产生网络手续费。仅检查页面外观或人工构造的事件，不能证明选定的 USDC 确实到账并被正确记录。

相关文章