Как принимать оплату в USDC на своём сайте

Чтобы принимать USDC на сайте, свяжите заказ с инвойсом Cryptanio и заранее определите сеть и точный токен. Разберём магазин, который согласовал оплату в USDC в Ethereum. Сервер создаёт отдельный счёт, покупатель получает платёжную страницу, а заказ подтверждается после проверки результата. Средства поступают на ваш адрес.

Это сценарий фиксированного актива: покупатель должен отправить выданный вариант USDC, а не любую монету с похожим названием. Общий выбор между платёжной ссылкой и серверной интеграцией разобран в руководстве по приёму криптовалюты на сайте.

1. Уточните, какой USDC вы принимаете

Сопоставьте сеть и идентификатор токена с официальным каталогом Circle. Название USDC и логотип кошелька сами по себе недостаточны. Поддержка сети у Circle не доказывает, что этот маршрут включён в вашем проекте Cryptanio.

Circle различает native USDC, выпускаемый самим эмитентом в сети, и bridged USDC, созданный сторонним мостом. Эти формы не нужно считать взаимозаменяемыми для вашего счёта; различия описаны в материале Circle. Здесь выбирается поддерживаемый USDC Circle в Ethereum. Для другой сети заново проверьте её токен и доступность.

Слово native в выражении native USDC не означает основную монету блокчейна. В Ethereum USDC остаётся токеном, а основная монета — ETH. Это различие понадобится при заполнении адреса.

2. Подготовьте адрес для нужного актива

Нужны проект с активной услугой «Платежи», публичный адрес собственного кошелька и права на настройку проекта. Откройте «Платежи», выберите проект и раздел «Адреса», затем «Добавить адреса». На вкладке «Вручную» выберите Ethereum и укажите адрес, которым управляете.

Выберите «Один ассет» и заполните «Актив» идентификатором поддерживаемого USDC для этой сети, сверенным с каталогом Circle. Пустое поле означает основную монету, а не native USDC. Оставьте включёнными «Входящие», добавьте адрес и проверьте активность подключения и доступность сети. Само сохранение в адресной книге не подключает получение к нужной услуге.

Для ручного пула подготовьте свободный адрес для выдачи реквизитов. Не передавайте приватный ключ или seed-фразу: они не нужны для подключения публичного адреса. Основы проверки маршрута описаны в статье «Чем отличаются сеть и токен».

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 действительно поступает и правильно учитывается.