Desenvolvedores

Referência da API

Uma API REST pequena para faturas, links de pagamento, saldos e moedas aceitas. Ela usa JSON sobre HTTPS, e toda solicitação é feita com a sua chave secreta.

URL base

Produção: https://cryptomerchant.online/api/v1
Desenvolvimento local: http://localhost:3000/api/v1

Há uma descrição desta API legível por máquina em /openapi.json (OpenAPI 3.1). Você pode importá-la no Postman ou em um gerador de clientes.

Autenticação

Envie sua chave secreta no header Authorization de toda solicitação, como um token Bearer. Crie chaves no portal, em Desenvolvedores.

HTTP

Authorization: Bearer cm_live_…

As chaves começam com cm_live_ na mainnet e com cm_test_ na testnet.
A chave completa é exibida só uma vez, quando você a cria. Armazenamos apenas um hash dela, então guarde-a em um lugar seguro.
Use as chaves apenas no seu servidor. Nunca as coloque em uma página web, em um app para celular ou em um repositório de código público.
Se uma chave pode ter vazado, revogue-a no portal e crie uma nova.

Erros

Quando uma solicitação falha, a resposta tem um status de erro HTTP e um corpo JSON com um code legível por máquina e uma message legível por pessoas:

JSON

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

Status HTTP

400: A solicitação não é válida, por exemplo, falta um campo ou o valor é pequeno demais.
401: A chave de API está ausente, incorreta ou foi revogada.
403: Sua conta não pode fazer isso: ela ainda não está ativa ou está suspensa.
404: O objeto não existe ou pertence a outra empresa.
409: A fatura não pode fazer isso no status atual, por exemplo, cancelar uma que já tem um pagamento.
500: Algo deu errado do nosso lado. Tente de novo daqui a pouco.

Códigos que você pode ver

invalid_json: O corpo da solicitação não é um objeto JSON.
invalid_request: Um campo está ausente ou não é válido. A mensagem informa qual é o campo.
unauthorized: A chave de API está ausente, incorreta ou foi revogada.
account_suspended: Esta conta de lojista está suspensa.
merchant_not_live: Sua conta ainda não está ativa. Conclua primeiro a configuração no portal.
invalid_amount: O valor está ausente, não é um número ou não é maior que zero.
amount_too_small: O valor equivale a menos de 0,50 dólar americano.
invalid_asset: O ID da moeda não corresponde a nenhuma moeda conhecida.
asset_not_accepted: Você não aceita essa moeda.
invalid_state: A fatura não pode fazer isso no status atual.
not_found: Não existe nenhum objeto com esse ID.
server_error: Algo deu errado do nosso lado.

O objeto de fatura

As faturas têm este formato nas respostas da API e nos webhooks. Os valores são strings decimais, para que nenhuma precisão seja perdida.

idstring: ID da fatura, começando com inv_.
objectstring: Sempre invoice.
statusstring: O status atual. Veja a lista de status abaixo.
amountstring: O preço que você pediu, em currency.
currencystring: A moeda do preço, por exemplo USD.
amount_usdstring: O preço em dólares americanos.
descriptionstring | null: Sua descrição, exibida ao cliente.
order_idstring | null: Sua própria referência de pedido.
customer_emailstring | null: O e-mail do cliente, se você informou um.
metadataobject: O objeto que você enviou ao criar a fatura, retornado sem alterações.
coinobject | null: A moeda que o cliente escolheu, ou a moeda em que ele realmente pagou, com id, symbol e network. null até que uma moeda seja escolhida.
requested_coinobject | null: Normalmente null. Quando o cliente pagou em outra moeda ou por outra rede e o pagamento foi contabilizado, é a moeda que a fatura pediu, com os mesmos campos de coin. Veja moeda ou rede errada.
pay_addressstring | null: O endereço de depósito desta fatura. null até que uma moeda seja escolhida.
pay_amountstring | null: O valor exato a enviar, na moeda escolhida.
network_fee_amountstring: Parte de pay_amount: a taxa de gas que o cliente paga além do preço, na moeda. 0 quando não há.
network_fee_usdstring: A mesma taxa de gas em dólares americanos.
rate_usdstring | null: O preço garantido de uma unidade da moeda escolhida, em dólares americanos.
received_amountstring: Quanto chegou até agora, na moeda escolhida.
received_usdstring: O valor em dólares americanos do que chegou.
overpaid_amountstring: Quanto foi pago além do que a fatura pedia, na moeda escolhida.
refunded_amountstring: Quanto você reembolsou deste pagamento com links de reembolso, na moeda paga. 0 se nada foi reembolsado.
checkout_urlstring: A página da fatura. Envie seu cliente para cá para pagar.
redirect_urlstring | null: Para onde o cliente pode ir depois de pagar.
expires_atISO 8601: Quando a fatura expira se nenhum pagamento for detectado.
paid_atISO 8601 | null: Quando a fatura foi paga, ou null.
created_atISO 8601: Quando a fatura foi criada.

invoice

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Status das faturas

openAberta: Criada. O cliente ainda não escolheu uma moeda.
awaiting_paymentAguardando pagamento: Uma moeda foi escolhida, o endereço de depósito foi atribuído e a cotação está garantida.
confirmingConfirmando: Um pagamento foi detectado on-chain e está aguardando confirmações.
underpaidPaga a menos: O pagamento confirmado ficou abaixo do valor em mais do que a sua tolerância. O cliente pode pagar o restante ou pedir reembolso.
paidPaga: Paga e confirmada. O valor, descontada a taxa, está no seu saldo. Um reembolso parcial mantém este status.
expiredExpirada: O tempo acabou antes de algum pagamento ser detectado.
cancelledCancelada: A fatura foi cancelada antes de algum pagamento ser detectado.
refundedReembolsada: O cliente recebeu o reembolso do que enviou em uma fatura paga a menos, ou você reembolsou tudo o que ficou com você de uma fatura paga.

Criar uma fatura

POST/invoices

Cria uma fatura e retorna o objeto de fatura com status 201. Envie seu cliente para o checkout_url dela.

Parâmetros do corpo

amountObrigatórionumber | string: O preço, como número ou string decimal. Precisa valer pelo menos 0,50 dólar americano.
currencyOpcionalstring: A moeda do preço, por exemplo USD. O padrão é USD.
descriptionOpcionalstring: O que o cliente está pagando, com até 300 caracteres. Exibido na página da fatura.
order_idOpcionalstring: Sua própria referência de pedido, com até 120 caracteres, para vincular a fatura a um pedido.
customer_emailOpcionalstring: O endereço de e-mail do cliente. Os pagamentos são agrupados por cliente no portal.
customer_nameOpcionalstring: O nome do cliente, com até 120 caracteres.
redirect_urlOpcionalstring: Uma URL completa para onde o cliente pode ir depois de pagar.
metadataOpcionalobject: Qualquer objeto JSON de até 4 KB. Retornado sem alterações na fatura e nos webhooks.
coinOpcionalstring: Pré-seleciona uma moeda pelo ID, por exemplo USDT.TRON. Precisa ser uma das suas moedas aceitas.

Com uma coin pré-selecionada, o endereço de depósito é atribuído e a cotação é garantida na hora, então pay_address e pay_amount já vêm preenchidos e você pode mostrar os dados de pagamento na sua própria interface.

curl

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

Node.js

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

Listar faturas

GET/invoices

Retorna suas faturas, das mais recentes para as mais antigas, uma página por vez.

Parâmetros de consulta

statusOpcionalstring: Apenas faturas com este status, por exemplo paid. Precisa ser um dos status acima.
limitOpcionalnumber: Quantas faturas retornar, de 1 a 100. O padrão é 20.
starting_afterOpcionalstring: Um ID de fatura. Retorna as faturas que vêm depois dela, para a próxima página.

As faturas ficam em data. Quando has_more for true, peça a próxima página com starting_after definido como o ID da última fatura que você recebeu.

curl

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Resposta

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

Consultar uma fatura

GET/invoices/{id}

Retorna uma fatura pelo ID.

curl

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Cancelar uma fatura

POST/invoices/{id}/cancel

Cancela uma fatura. Isso só funciona enquanto a fatura não foi paga e nenhum pagamento foi detectado para ela.

curl

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Saldos

GET/balances

Retorna o que a sua empresa tem em cada moeda, o total em dólares americanos e o seu saldo de gas.

data[].coin: O ID da moeda, por exemplo USDT.TRON.
data[].symbol: O símbolo da moeda, por exemplo USDT.
data[].network: A rede em que a moeda está.
data[].amount: Quanto você tem da moeda, como string decimal.
data[].usd: O valor dela em dólares americanos pelo preço atual.
total_usd: O valor de todas as suas moedas em dólares americanos.
gas_balance_usd: Seu saldo de gas em dólares americanos, usado para pagar taxas de gas.

curl

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Resposta

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

Moedas aceitas

GET/coins

Retorna as moedas que você aceita neste momento, cada uma com id, symbol, name, network e decimals. Use o id como coin ao criar uma fatura. Por exemplo:

curl

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Resposta

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

Criar um link de pagamento

POST/payment-links

Cria um link de pagamento e o retorna com status 201, incluindo o id e a url compartilhável.

Parâmetros do corpo

titleObrigatóriostring: O nome do que o cliente está pagando, com até 120 caracteres.
amountOpcionalnumber | string: Um preço fixo. Omita para que o cliente informe o valor.
currencyOpcionalstring: A moeda do preço. O padrão é USD.
descriptionOpcionalstring: Mais detalhes exibidos ao cliente, com até 300 caracteres.

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

Resposta

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

Listar links de pagamento

GET/payment-links

Retorna seus 100 links de pagamento mais recentes, dos mais novos para os mais antigos, em data.

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

O objeto de saque

Os webhooks de saque (payout.sent e payout.failed) trazem este objeto em data. Os saques da parte de um parceiro em uma divisão de receita usam o mesmo objeto, com partner_share definido como true.

idstring: ID do saque.
objectstring: Sempre payout.
coinstring: O ID da moeda, por exemplo USDT.TRON.
amountstring: O valor sacado, nessa moeda.
network_feestring: A taxa de gas do envio, nessa moeda.
to_addressstring: O endereço de carteira para o qual foi enviado.
statusstring: queued, running, done ou failed.
tx_hashstring | null: O ID da transação na blockchain, depois que o saque é enviado.
autoboolean: true se o saque foi feito automaticamente, sem ter sido solicitado por uma pessoa.
partner_shareboolean: true se este saque é a parte de um parceiro em uma divisão de receita, enviada para a carteira do parceiro.
created_atISO 8601: Quando o saque foi criado.

payout

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Em seguida, configure os webhooks para que o seu servidor fique sabendo dos pagamentos no momento em que acontecem.