Aceite pagamentos com cartão e receba USDC — com ou sem conta

Como um pagamento funciona

O fluxo é o mesmo em todos os modos. Só mudam o destino do dinheiro e as ferramentas ao redor.

URL base de toda chamada à API: https://api.utopay.app. Requisições e respostas são JSON (content-type: application/json). Valores são números na moeda do pedido; horários, milissegundos Unix.

Início rápido

Um pagamento real em uma requisição — sem cadastro. O comprador vai direto para o PayPal; se o PayPal não puder aceitar este pagamento, abre a nossa página com os outros métodos.

curl -X POST https://api.utopay.app/v1/pay \
  -H "content-type: application/json" \
  -d '{
    "amount": 100,
    "currency": "USD",
    "payout_wallet": "0xYourPolygonWalletAddress000000000000000000",
    "provider": "paypal",
    "success_url": "https://yoursite.com/thanks"
  }'
# → { "id": "ord_…", "checkout_url": "https://api.utopay.app/pay/ord_…/go?provider=paypal", … }

Redirecione o comprador para checkout_url. Cerca de 95.5 USDC chegam à sua carteira após o pagamento. Com conta, você chamaria POST /v1/payments com uma chave de API — mesmos campos, mais histórico, webhooks e saldo.

Comparar os modos

Sem conta

POST /v1/pay

Sem cabeçalho Authorization. O dinheiro sempre vai direto para payout_wallet — um endereço EVM que possa receber USDC na Polygon. Mesmo corpo de POST /v1/payments, mais:

• Sempre direct: "settlement": "custody" retorna 400 — sem conta não há saldo para creditar.
• Taxa fixa de 4.5%, sem programa de indicação, sem webhooks (callback_url é salvo mas não é chamado), sem modo de teste, checkout com design padrão.
• Acompanhamento: consulte o endpoint público GET /api/checkout/:id/status (sem chave) ou acompanhe sua carteira.

Conta e chaves de API

Uma conta comporta até 20 projetos (um por site). Cada um tem suas chaves, webhooks, carteira, marca, modo dos fundos e estatísticas; o saldo é compartilhado por toda a conta.

Authorization: Bearer utopay_sk_live_xxxxxxxxxxxxxxxxxxxx

A chave é exibida uma única vez; guardamos só o hash. Nunca coloque uma chave secreta em código de navegador ou de app.

Criar um pagamento

POST /v1/payments Bearer sk

curl -X POST https://api.utopay.app/v1/payments \
  -H "Authorization: Bearer utopay_sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "amount": 250,
    "currency": "EUR",
    "email": "[email protected]",
    "description": "Invoice #118",
    "provider": "revolut",
    "success_url": "https://yoursite.com/thanks"
  }'

{
  "id": "ord_Kd83mQp0aVxY",
  "status": "pending",
  "amount": 250, "currency": "EUR",
  "checkout_url": "https://api.utopay.app/pay/ord_Kd83mQp0aVxY/go?provider=revolut",
  "payment_page_url": "https://api.utopay.app/pay/ord_Kd83mQp0aVxY",
  "provider": "revolut",
  "routing": { "mode": "direct_to_provider", "requested_provider": "revolut", "reason": null },
  "settlement": "direct",
  "payout_coin": "USDC", "payout_network": "polygon",
  …  full list in Order object
}

Sempre redirecione o comprador para checkout_url. Guarde payment_page_url se quiser um link "escolher outro método" — ele sempre abre a nossa página.

Enviar o comprador direto a um método de pagamento

Funciona em todos os modos — com chave de API, sem conta, em links de pagamento do painel e no formulário sem código em /payment-links. Defina provider e o comprador vai direto para esse provedor (ex.: PayPal) sem ver o nosso formulário de pagamento.

routing na resposta diz o que aconteceu: mode é direct_to_provider ou payment_page; reason é null, provider_offline, provider_below_minimum, provider_currency, provider_disabled ou project_routing (escolhido entre os provedores preferidos do seu projeto).

GET /v1/providers?amount=&currency= público

Métodos disponíveis agora para este valor e moeda, com id, name, region, status, minimum_amount e minimum_currency. A lista muda — consulte-a em vez de fixá-la no código.

* Mínimos e disponibilidade vêm da rede de pagamentos e mudam; o valor é convertido para a moeda do mínimo antes da comparação. Alguns provedores podem pedir ao comprador uma verificação de identidade rápida e única.

Moedas e o que você recebe

currency é a moeda em que o comprador paga. Qualquer que seja, o dinheiro é convertido pelo provedor e circula como USDC na Polygon.

GET /v1/currencies público

Qualquer outro código retorna 400. Um provedor pode mostrar ao comprador o preço convertido para a moeda dele (ex.: Revolut em EUR) — o comprador ainda paga o equivalente ao seu valor. Alguns métodos aceitam só certas moedas; para eles, /v1/providers?currency=… os omite.

O que chega e onde

O USDC exato que chegou fica em received_amount do pedido após o pagamento; pode diferir um pouco da estimativa porque a cotação é definida pelo provedor. Saldos guardados podem ser trocados entre moedas e sacados em USDC, USDT, BTC, ETH e outras — veja Guardado na UTOPAY.

Status do pagamento

GET /v1/payments/:id Bearer sk

O pedido no mesmo formato. Enquanto não estiver paid, também consultamos o status real no provedor, então o polling é confiável mesmo se um callback atrasar — o crédito no saldo e o seu webhook acontecem exatamente uma vez em qualquer caso. Só o projeto da própria chave é visível (senão 404).

GET /v1/payments?limit=&offset=&status= Bearer sk

Pedidos do projeto, os mais recentes primeiro. limit 1–500 (padrão 50), status = pending | paid | failed.

GET /api/checkout/:id/status público

Sem chave: { "id", "status", "amount", "currency", "updated_at" }. Use para pedidos criados sem conta. Não trate uma visita a success_url como prova de pagamento — verifique o status.

Gateway cripto

O comprador paga direto em cripto — USDT, USDC, ETH, BTC e outras — para um endereço único do pedido. Tudo o que chega é repassado on-chain para a sua carteira na hora — ou, com settlement: "custody", creditado no seu saldo na UTOPAY (sem precisar de carteiras). Taxa de 1.5%, descontada do valor recebido; a taxa da blockchain é à parte.

GET /v1/crypto/coins público

Cada moeda/rede com ticker (o que você passa como coin, ex.: polygon/usdc, bep20/usdt, erc20/usdt, base/usdc, eth, btc, trc20/usdt), network, family (tipo de endereço), minimum e available. Funcionam as redes EVM, Tron, Bitcoin, Solana, TON e outras; available: false significa que a rede está temporariamente indisponível.

POST /v1/crypto/payments Bearer sk · POST /v1/crypto/pay sem conta

curl -X POST https://api.utopay.app/v1/crypto/pay \
  -H "content-type: application/json" \
  -d '{ "coin": "bep20/usdt", "amount": 100, "currency": "USD",
        "payout_address": "0xYourWallet0000000000000000000000000000000" }'
# → { "id": "ord_…", "kind": "crypto", "checkout_url": "https://api.utopay.app/pay/ord_…",
#     "crypto": { "coin": "bep20/usdt", "network": "BNB Smart Chain (BEP-20)", "symbol": "USDT",
#                 "address": "0x…", "amount_coin": 100.02, "minimum": 1.66, "detected": false, "underpaid": false } }

• Redirecione o comprador para checkout_url (valor, rede, endereço, QR, status ao vivo) — ou mostre crypto.address e crypto.amount_coin na sua própria página.
• Status: pending (com crypto.detected: true assim que a transferência é vista, antes das confirmações) → paid. Se chegar menos que o solicitado (falta de mais de 1%), o status é underpaid e o evento payment.underpaid — o dinheiro já está na sua carteira, a decisão é sua.
• Webhooks, GET /v1/payments/:id e chaves de teste funcionam como nos pagamentos com cartão. Transferências abaixo de minimum ou em outra moeda/rede não são processadas — a página de pagamento avisa o comprador.

Exemplos de integração

Crie o pedido no seu servidor (nunca com chave secreta no navegador), redirecione o comprador para checkout_url e marque o pedido como pago a partir do webhook. Guia passo a passo: aceitar cripto em um site; redes e tickers do Tether: aceitar USDT.

const res = await fetch('https://api.utopay.app/v1/crypto/payments', {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.UTOPAY_SK}`, 'content-type': 'application/json' },
  body: JSON.stringify({ coin: 'bep20/usdt', amount: 49.9, currency: 'EUR', description: 'Order #1042',
    success_url: 'https://shop.example/thanks', cancel_url: 'https://shop.example/cart' })
});
const order = await res.json();
if (!res.ok) throw new Error(order.error);
// save order.id with your order, then redirect the buyer
reply.redirect(order.checkout_url);

import os, requests

r = requests.post('https://api.utopay.app/v1/crypto/payments',
    headers={'Authorization': f'Bearer {os.environ["UTOPAY_SK"]}'},
    json={'coin': 'erc20/usdt', 'amount': 120, 'currency': 'USD', 'description': 'Invoice 77'},
    timeout=20)
order = r.json()
r.raise_for_status()
print(order['id'], order['checkout_url'], order['crypto']['address'], order['crypto']['amount_coin'])

$ch = curl_init('https://api.utopay.app/v1/crypto/payments');
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('UTOPAY_SK'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['coin' => 'polygon/usdt', 'amount' => 25, 'currency' => 'USD']),
]);
$order = json_decode(curl_exec($ch), true);
header('Location: ' . $order['checkout_url']);

Liquidação direta

O dinheiro nunca fica conosco: cada pagamento é dividido on-chain no momento em que o USDC chega.

• Ativar: painel → projeto → Fundos e repasses → Direto na carteira, cole um endereço USDC (Polygon). Ou por requisição: "settlement": "direct".
• Você recebe USDC em cada pagamento; além disso, histórico, estatísticas, webhooks e alertas no Telegram. Nada para sacar.
• Uma carteira por projeto — precisa de várias carteiras, crie vários projetos.

Guardado na UTOPAY

O USDC chega à carteira da plataforma UTOPAY. Em paid sua parte é creditada no saldo interno — depois você guarda, troca, converte ou saca.

• Ativar: Fundos e repasses → Guardado na UTOPAY (sem carteira), ou "settlement": "custody" por requisição.
• Crédito: amount × 95.5% na moeda do pedido (USD, EUR, GBP, CAD, INR, SEK); qualquer outra moeda, em USD pela cotação atual. Creditado exatamente uma vez.
• Um saldo por conta: todos os projetos neste modo somam; o extrato mostra o projeto de origem.

Redes de saque: USDC_POLYGON, USDT_POLYGON, USDT_TRC20, USDT_ERC20, ETH, BTC, BNB, TRX. O valor é reservado na hora (pending); a equipe da UTOPAY envia a transferência, normalmente em até um dia útil (done com txid). Solicitações recusadas são estornadas. Saques não podem ser iniciados com chave de API.

Links de pagamento

Sem código: crie um link, envie por chat ou email e receba. Painel → projeto → Links de pagamento → + Link.

• Valor fixo ou vazio — o comprador digita. Moeda — qualquer uma da lista.
• Método (opcional): fixe um provedor. Com valor fixo, o link envia o comprador direto para ele; com valor livre, o comprador vê só o campo do valor e um botão "Pagar com PayPal". Se o método estiver indisponível, aparece o seletor de métodos normal.
• URL de retorno — para onde o comprador vai após o pagamento. Links de uso único passam a used após o primeiro pedido (abrir de novo leva a esse pedido); links reutilizáveis funcionam até serem arquivados.
• Os fundos seguem o modo dos fundos do projeto. Pedidos de links aparecem no histórico e disparam webhooks como os pedidos da API.

O link público é https://api.utopay.app/i/lnk_…. Sem conta, use o formulário em /payment-links — ele cria um pedido /v1/pay com a mesma escolha de método.

Webhooks e alertas

Com conta. Quando um pedido muda de estado, a UTOPAY o envia via POST para cada endpoint do projeto, assinado com HMAC-SHA256.

Cadastrar: painel → Webhooks → + Endpoint, ou POST /api/merchants/:id/webhooks com { "url": "https://you.com/hooks/utopay" }. O segredo whsec_… aparece no painel.

POST https://you.com/hooks/utopay
content-type: application/json
x-utopay-event: payment.succeeded
x-utopay-signature: t=1759660123,v1=<hex hmac-sha256>
user-agent: UTOPAY-Webhooks/1.0

{
  "event": "payment.succeeded",
  "created_at": 1759660123456,
  "data": { /* the Order object */ }
}

import crypto from 'node:crypto';
// use the RAW body, not re-serialised JSON
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const a = Buffer.from(v1 || ''), b = Buffer.from(expected);
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

// raw body + x-utopay-signature header + your whsec_… secret
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_UTOPAY_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $raw, getenv('UTOPAY_WHSEC'));
if (!hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int)($sig['t'] ?? 0)) > 300) {
  http_response_code(400); exit;
}
$event = json_decode($raw, true);
if ($event['event'] === 'payment.succeeded') { /* mark $event['data']['id'] as paid */ }
http_response_code(200);

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    t, v1 = parts.get('t', ''), parts.get('v1', '')
    expected = hmac.new(secret.encode(), f'{t}.'.encode() + raw_body, hashlib.sha256).hexdigest()
    fresh = t.isdigit() and abs(time.time() - int(t)) < 300
    return fresh and hmac.compare_digest(expected, v1)

• Responda com qualquer 2xx em até 10 s. Novas tentativas após 30 s, 2 min, 15 min, 1 h, 6 h — 6 tentativas. As entregas aparecem no painel.
• Seja idempotente — elimine duplicatas por data.id.
• Telegram: pedidos pagos chegam ao seu chat com valor, descrição e id (Notificações).

Modo de teste

1. Crie uma chave secreta de teste (utopay_sk_test_…) e chame POST /v1/payments normalmente — todas as validações (moeda, provedor) são as mesmas.
2. checkout_url aponta para uma página sandbox (/sandbox/ord_test_…). Clique em Simulate payment ou Simulate failure.
3. Webhooks e Telegram disparam como em produção, com "is_test": true. Nenhum dinheiro se move, nenhum saldo é creditado.

Equipe, marca, roteamento

Equipe: convide por email (Equipe). Funções admin, developer, finance, viewer; quem criou é owner.

Marca: nome, logo, cor de fundo e do botão em Configurações — aplicados à página de pagamento, às páginas de links e à tela de pagamento concluído.

Roteamento do projeto: em Roteamento, liste os provedores preferidos por prioridade. Para pagamentos via API sem provider, é usado o primeiro que estiver online e aceitar o valor e a moeda (routing.reason = "project_routing"); se nenhum servir, o comprador escolhe na nossa página. Um provider explícito sempre prevalece.

Objeto do pedido

Retornado por create/get/list e dentro dos webhooks.

Todos os endpoints públicos

Taxas

• Você recebe 95.5% — igual com ou sem conta, nos modos direto e guardado, para qualquer moeda e método. Sem taxa de adesão ou mensalidade.
• Grandes lojistas podem ter uma taxa individual — fale conosco. A divisão exata de cada pedido está em fees.

Programa de indicação

• Nível 1: 25% da nossa taxa sobre os lojistas que você indicou; nível 2: 10% sobre os lojistas que eles indicaram.
• Pago on-chain a cada pagamento na carteira de indicação definida em Indicações. Sai da nossa taxa — os indicados não pagam nada a mais.

Erros

Todo erro é { "error": "message" } com o status HTTP correspondente.