Como aceitar pagamentos em USDC no seu site

Para aceitar USDC no seu site, associe a encomenda a uma fatura Cryptanio e defina antecipadamente a rede e o token exato. Vamos usar o exemplo de uma loja que acordou receber USDC na Ethereum. O servidor cria uma fatura separada, o comprador recebe uma página de pagamento e a encomenda é confirmada após a verificação do resultado. Os fundos chegam ao seu endereço.

Este é um cenário com um ativo fixo: o comprador tem de enviar a variante de USDC indicada nos dados de pagamento, e não qualquer moeda com um nome semelhante. A escolha geral entre uma ligação de pagamento e uma integração no servidor é explicada no guia para aceitar criptomoedas num site.

1. Confirme qual USDC aceita

Compare a rede e o identificador do token com o catálogo oficial da Circle. O nome USDC e o logótipo apresentado pela carteira não bastam. O facto de a Circle suportar uma rede não prova que essa opção esteja ativada no seu projeto Cryptanio.

A Circle distingue o USDC nativo, emitido pelo próprio emissor nessa rede, do USDC bridged, criado por uma ponte de terceiros. Não considere estas formas intercambiáveis para a sua fatura; as diferenças estão descritas no artigo da Circle. Neste exemplo, escolhemos o USDC da Circle suportado na Ethereum. Para outra rede, volte a verificar o token e a sua disponibilidade.

A palavra native na expressão native USDC não significa a moeda principal da blockchain. Na Ethereum, o USDC continua a ser um token, enquanto a moeda principal é o ETH. Esta distinção será necessária ao preencher os dados do endereço.

2. Prepare um endereço para o ativo certo

Precisa de um projeto com o serviço «Pagamentos» ativo, do endereço público de uma carteira sua e de permissões para configurar o projeto. Abra «Pagamentos», selecione o projeto e a secção «Address» e, em seguida, «Adicionar endereços». No separador «Manualmente», selecione Ethereum e indique um endereço que controla.

Selecione «Um ativo» e preencha «Ativo» com o identificador do USDC suportado nessa rede, depois de o confirmar no catálogo da Circle. Um campo vazio significa a moeda principal, e não o USDC nativo. Mantenha «A chegar» ativado, adicione o endereço e verifique se a ligação está ativa e se a rede está disponível. Guardar o endereço no livro de endereços, por si só, não o liga à receção no serviço pretendido.

Para um conjunto manual de endereços, prepare um endereço livre que possa ser atribuído nos dados de pagamento. Não forneça a chave privada nem a frase de recuperação: não são necessárias para ligar um endereço público. Os princípios para verificar a combinação de rede e token são explicados no artigo «Qual é a diferença entre uma rede e um token?».

3. Crie uma fatura para a encomenda

Prepare uma chave de API de produção para uso no servidor, com acesso a este projeto, à secção invoices («Facturas») e a permissão «Ler e escrever». Guarde o seu próprio número de encomenda antes de fazer o pedido. Não forneça a chave ao comprador.

Abaixo está um exemplo suportado da API v1 para um ativo fixo. No pedido gerado, confira a rede, o ativo e o montante da sua encomenda. Um montante em USDC significa uma quantidade de tokens, e não o recebimento de dólares numa conta bancária:

#!/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

Transferir exemplo

Indique o seu projeto e os dados da encomenda. Para uma nova operação, use um Idempotency-Key único; ao repetir o mesmo pedido após uma falha, mantenha a chave anterior. Guarde a associação entre a encomenda e o ID da fatura criada, o checkout_url recebido e os dados de pagamento exatos da resposta. Não arredonde o montante devolvido nem o substitua pelo valor de uma tabela de preços.

4. Envie ao cliente a página de pagamento

Disponibilize a abertura do checkout_url recebido a partir da encomenda no seu site. Não construa o endereço da página a partir do ID da fatura nem substitua os dados atribuídos por um endereço de carteira permanente. Neste cenário, a rede e o ativo já estão definidos: o cliente deve conferi-los na carteira antes de enviar.

Peça ao cliente que envie o montante exato, tendo em conta as regras de comissão da carteira e o prazo de pagamento. Se tiver outra versão de USDC, mudar apenas o nome do token não tornará a transferência adequada. Primeiro, acordem a combinação correta; não prometa uma conversão automática nem uma ponte disponibilizada pela Cryptanio.

5. Confirme a encomenda e verifique todo o percurso

O servidor deve verificar o estado atual da fatura através de um webhook ou de consultas à API. Entregue a encomenda quando o estado for paid, mantendo a proteção contra execuções repetidas. Encontrar uma transação, receber uma captura de ecrã ou ver o comprador regressar ao site não substitui esta verificação.

Trate os pagamentos insuficientes, os pagamentos em excesso, os recebimentos tardios e as reversões de transações de acordo com o estado da fatura concreta. Em caso de dúvida, guarde o TXID e consulte o diagnóstico de encomendas não pagas. Não atribua outro ativo a esta encomenda apenas porque o montante é semelhante.

Verifique o processo completo com uma encomenda sua: os dados de pagamento, o envio, a confirmação e a entrega. No modo de produção são usados fundos reais e aplicam-se comissões de rede. Verificar apenas o aspeto da página ou eventos artificiais não prova que o USDC escolhido esteja efetivamente a chegar e a ser contabilizado corretamente.