API de pagamentos v2

Início rápido

1. Crie uma chave de API para o seu gateway no painel, em Desenvolvedores. 2. Crie um pagamento com o valor do pedido. 3. Redirecione o cliente para o checkout_url retornado. 4. Quando o webhook chegar (ou o cliente voltar), consulte o pagamento novamente e envie o pedido quando o status for "paid".

 curl https://coino.live/api/v2/payments \
  -H "Authorization: Bearer ck_live_..." \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"amount": "25.00", "currency": "EUR", "order_id": "1001",
       "success_url": "https://shop.example/thanks",
       "notify_url": "https://shop.example/coino-webhook"}' 

Autenticação

Envie sua chave secreta no cabeçalho Authorization de cada requisição. Cada chave pertence a um gateway e só vê os pagamentos desse gateway. Mantenha-a no seu servidor: nunca coloque uma chave em um navegador, app ou repositório público. Se uma chave vazar, revogue-a no painel e crie outra.

Authorization: Bearer ck_live_...
URL base: https://coino.live/api/v2

Todos os valores são strings decimais (nunca números), todos os horários são ISO 8601 em UTC e toda resposta é JSON com o resultado em "data".

Criar um pagamento

Os preços podem estar em USD ou em qualquer moeda listada por GET /currencies; outras moedas são convertidas para USD pela cotação atual quando o pagamento é criado. O cliente escolhe a criptomoeda e a rede na página de pagamento.

A resposta (201 ao criar, 200 para uma chave repetida) é o objeto de pagamento abaixo.

O objeto de pagamento

{
  "data": {
    "id": "01m62ewd502p9774d6trd7rhr7",
    "status": "paid",
    "amount": "22.32",
    "currency": "USD",
    "requested_amount": "20.00",
    "requested_currency": "EUR",
    "exchange_rate_usd": "1.115926958947",
    "received_usd": "22.32",
    "remaining_usd": "0.00",
    "order_id": "943",
    "description": "Order #943",
    "customer_email": "[email protected]",
    "metadata": {"cart": "abc"},
    "checkout_url": "https://coino.live/pay/01m62ewd502p9774d6trd7rhr7",
    "success_url": "https://shop.example/thanks",
    "cancel_url": "https://shop.example/cart",
    "asset": null,
    "quote": {
      "asset": "usdc-ethereum", "symbol": "USDC", "network": "Ethereum",
      "address": "0x8e2e…61bc", "amount": "22.330545",
      "network_fee": "0.000001", "rate_usd": "0.9995", "expires_at": "…"
    },
    "deposits": [{
      "asset": "usdc-ethereum", "symbol": "USDC", "network": "Ethereum",
      "tx_hash": "0xf13d…1439", "explorer_url": "https://etherscan.io/tx/0xf13d…1439",
      "amount": "22.330545", "network_fee": "0.000001",
      "platform_fee": "0.223305", "net": "22.107239",
      "usd_value": "22.32", "credited_at": "…"
    }],
    "expires_at": "…", "paid_at": "…", "created_at": "…"
  }
}

amount e currency são o que o cliente paga em USD; requested_amount e requested_currency são o que você pediu. quote é a criptomoeda, o endereço e o valor exibidos agora ao cliente; deposits lista cada transação recebida, com a taxa cobrada e o que foi adicionado ao seu saldo (net).

Um pagamento muito próximo do valor conta como pago, para que arredondamentos de carteiras não deixem pedidos em aberto.

Consultar e cancelar pagamentos

Consulte um pagamento novamente sempre que precisar do estado atual: após um webhook, quando o cliente voltar ou em uma tarefa agendada. IDs desconhecidos e pagamentos de outros gateways respondem 404.

Lista seus pagamentos, do mais recente, 50 por página. Os dois filtros são opcionais. meta.next_cursor e meta.prev_cursor navegam pelos resultados.

Cancela um pagamento em aberto que não recebeu nada, por exemplo quando o cliente esvazia o carrinho. Pagamentos com depósito não podem ser cancelados (422).

Webhooks

A Coino Live envia um POST para notify_url (ou para a URL de webhook do gateway) sempre que um pagamento muda de status. Os webhooks só são enviados quando seu gateway tem um segredo de assinatura: crie-o nas configurações do gateway.

 POST /coino-webhook
X-Coino-Event: payment.paid
X-Coino-Delivery: 01m62f23xhkz39ahqv4h64ttfk
X-Coino-Signature: t=1761696953,v1=5f2c…

{"id": "01m62f23xhkz39ahqv4h64ttfk", "event": "payment.paid",
 "created_at": "…", "data": { …the payment object… }} 

Verifique a assinatura: calcule o HMAC-SHA256 de "<t>.<raw body>" com seu segredo de assinatura, compare com v1 em tempo constante e recuse carimbos de tempo com mais de cinco minutos.

// PHP
$header = $_SERVER['HTTP_X_COINO_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $header), $sig);
$ok = isset($sig['t'], $sig['v1'])
    && abs(time() - (int) $sig['t']) <= 300
    && hash_equals(hash_hmac('sha256', $sig['t'] . '.' . $body, $secret), $sig['v1']);

// Node.js
const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const ok = Math.abs(Date.now() / 1000 - t) <= 300
  && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

# Python
t, v1 = (p.split('=', 1)[1] for p in header.split(','))
expected = hmac.new(secret.encode(), f'{t}.{raw_body}'.encode(), 'sha256').hexdigest()
ok = abs(time.time() - int(t)) <= 300 and hmac.compare_digest(expected, v1)

Moedas, criptomoedas e saldos

Moedas em que um pagamento pode ser precificado, cada uma com seu valor em USD: {"code": "EUR", "usd_per_unit": "1.09"}. Oculte o pagamento em cripto quando a moeda da sua loja não estiver na lista.

Criptomoedas com que os clientes podem pagar agora: code (por exemplo "usdt-tron"), symbol, name, network, decimals e price_usd.

O saldo da sua conta por criptomoeda, após as taxas: asset, symbol, network, balance e usd_value (null enquanto não houver cotação).

Contas de custódia

Para apps com contas de usuário: cada usuário recebe endereços de depósito permanentes, e os depósitos são creditados no saldo desse usuário no seu gateway.

Saques

Paga do seu saldo para um endereço: asset, amount e address são obrigatórios; custody_user debita o saldo de um utilizador de custódia; reference (única por gateway) torna o pedido seguro para repetir. Desativado por padrão: ative os levantamentos pela API nas definições do gateway, onde também define um limite diário em USD e os endereços IP dos servidores autorizados (os dois endpoints só respondem a esses IPs). Uma reference reutilizada para outro levantamento é recusada com 409. Levantamentos grandes podem aguardar revisão.

Status: pending_review, approved, processing, broadcast, completed, rejected (veja error), cancelled ou failed. tx_hash é preenchido após o envio.

Erros e limites

{"message": "The minimum payment is 1.00 USD."}

{"message": "amount must be a decimal string with at most 2 decimals, e.g. \"25.00\".",
 "errors": {"amount": ["amount must be a decimal string with at most 2 decimals, e.g. \"25.00\"."]}}

Bibliotecas de código

Bibliotecas oficiais para esta API, sem dependências. Verificam as assinaturas dos webhooks, dão um erro claro para cada recusa e repetem erros de rede só quando repetir o pedido é seguro.

// PHP
$coino = new \CoinoLive\Client('ck_live_...');
$payment = $coino->payments->create(['amount' => '25.00', 'currency' => 'EUR', 'order_id' => '1001']);

// Node.js
const coino = new CoinoLive('ck_live_...');
const payment = await coino.payments.create({ amount: '25.00', currency: 'EUR', order_id: '1001' });

# Python
coino = coinolive.Client("ck_live_...")
payment = coino.payments.create(amount="25.00", currency="EUR", order_id="1001") 

Cada download inclui um README com todas as chamadas, o tratamento de webhooks e as classes de erro.

Integrações com plataformas

Plugins prontos construídos sobre esta API. Instale um, cole uma chave de API e ative: os pedidos são atualizados automaticamente e cada plugin mostra seu saldo e seus pagamentos no próprio painel.

Outras plataformas: use a API diretamente, como descrito acima.