API da ByteMax

Começar

Três passos até a primeira chamada.

1. 1
   Crie a chave de API

   Na página API do seu painel, crie a chave e guarde no seu servidor: ela aparece uma vez só e dá acesso a toda a sua conta. Ative a lista de IPs permitidos antes de usar.

2. 2
   Envie estes cabeçalhos em toda chamada

   Ao criar ordens e reembolsos, inclua também Idempotency-Key. Veja Valores e idempotência.

   Authorization: Bearer <API_KEY>
   Content-Type: application/json

3. 3
   Faça uma cotação

   A cotação não cria nada. Use para conferir a chave e ver os valores da conversão.

   curl --request GET "https://bytemax.exchange/api/v1/quote?source_currency=BRL&target_currency=CNY&source_amount_atomic=10000" \
     --header "Authorization: Bearer <API_KEY>"

   Resposta 200

   {
     "source_currency": "BRL",
     "source_amount_atomic": "10000",
     "target_currency": "CNY",
     "target_amount_atomic": "12500000000"
   }

Fluxo de pagamento

Uma ordem começa aguardando pagamento, é paga pelo link e termina concluída, expirada ou cancelada. Acompanhe por webhook ou por consulta.

1. 1
   Cotação (opcional)

   GET /quote informa quanto o pagador paga e quanto você recebe. A ordem usa a cotação do momento em que é criada.

2. 2
   Crie a ordem

   POST /orders com a moeda paga (BRL), a moeda recebida (CNY) e um dos dois valores: quanto o pagador paga ou quanto você recebe. A resposta traz payment.url, o link de pagamento, e pix_copy_paste quando disponível.

3. 3
   Envie o pagador para o link

   Abra payment.url para o pagador. Ao concluir ou fechar o pagamento, ele volta para a URL de retorno configurada na página API do seu painel. Sem essa URL, o navegador volta pelo histórico.

4. 4
   Acompanhe a ordem

   Cadastre um webhook para receber order.updated a cada mudança, ou consulte GET /orders/{id}.

5. 5
   Reembolse se precisar

   POST /orders/{id}/refunds com o valor em CNY. Se a resposta for 202, o reembolso ainda está em processamento: acompanhe com GET /orders/{id}/refunds/{refund_id} e não crie outro.

Estados da ordem

pending_payment

Aguardando o pagamento. O link de pagamento está ativo.

processing

Pagamento identificado. A ordem está sendo processada.

completed

Concluída. Estado final.

expired

O prazo terminou sem pagamento. Estado final.

canceled

Cancelada. Estado final.

on_hold

Ordem retida. A retomada exige liberação explícita pela ByteMax.

Estados do reembolso

processing

Em andamento.

succeeded

Concluído. Estado final.

failed

Não foi possível concluir o reembolso. Estado final.

pending_reconciliation

Resultado ainda não confirmado. Consulte até mudar e não crie outro reembolso.

Valores e idempotência

Valores

Todo valor é uma string com um inteiro na menor unidade da moeda, sem sinal, ponto ou notação científica. BRL tem 2 casas: "10000" é R$ 100,00. CNY tem 8 casas: "12500000000" é ¥ 125,00. Informe exatamente um dos dois valores, source_amount_atomic ou target_amount_atomic. Hoje o único par é BRL → CNY: o pagador paga em reais e você recebe em yuans. O valor máximo por ordem é 1.000.000 unidades da moeda informada.

Idempotência

Envie Idempotency-Key ao criar ordens e reembolsos, com uma chave nova para cada operação nova. Repetir a mesma chave com o mesmo corpo devolve o resultado já criado, com 200: é assim que você repete uma chamada com segurança depois de uma falha de rede. A mesma chave com outro corpo devolve 409. Guarde a chave junto do pedido no seu sistema.

Referência

Cinco operações. Os exemplos usam <API_KEY> e IDs fictícios.

curl --request GET "https://bytemax.exchange/api/v1/quote?source_currency=BRL&target_currency=CNY&source_amount_atomic=10000" \
  --header "Authorization: Bearer <API_KEY>"

{
  "source_currency": "BRL",
  "source_amount_atomic": "10000",
  "target_currency": "CNY",
  "target_amount_atomic": "12500000000"
}

curl --request POST "https://bytemax.exchange/api/v1/orders" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Idempotency-Key: order-8412" \
  --header "Content-Type: application/json" \
  --data '{"source_currency":"BRL","source_amount_atomic":"10000","target_currency":"CNY"}'

{
  "id": "ord_example",
  "version": "1",
  "status": "pending_payment",
  "source_currency": "BRL",
  "source_amount_atomic": "10000",
  "target_currency": "CNY",
  "target_amount_atomic": "12500000000",
  "refunded_source_amount_atomic": "0",
  "blocked_source_amount_atomic": "0",
  "payment": {
    "url": "https://bytemax.exchange/pay/example",
    "pix_copy_paste": null
  },
  "created_at": "2026-09-10T13:05:00.000Z"
}

curl --request GET "https://bytemax.exchange/api/v1/orders/ord_example" \
  --header "Authorization: Bearer <API_KEY>"

{
  "id": "ord_example",
  "version": "1",
  "status": "pending_payment",
  "source_currency": "BRL",
  "source_amount_atomic": "10000",
  "target_currency": "CNY",
  "target_amount_atomic": "12500000000",
  "refunded_source_amount_atomic": "0",
  "blocked_source_amount_atomic": "0",
  "payment": {
    "url": "https://bytemax.exchange/pay/example",
    "pix_copy_paste": null
  },
  "created_at": "2026-09-10T13:05:00.000Z"
}

curl --request POST "https://bytemax.exchange/api/v1/orders/ord_example/refunds" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Idempotency-Key: order-8412" \
  --header "Content-Type: application/json" \
  --data '{"target_amount_atomic":"2500000000"}'

{
  "id": "ref_example",
  "order_id": "ord_example",
  "version": "1",
  "status": "processing",
  "source_currency": "BRL",
  "source_amount_atomic": "2000",
  "target_currency": "CNY",
  "target_amount_atomic": "2500000000",
  "created_at": "2026-09-10T13:05:00.000Z",
  "updated_at": "2026-09-10T13:05:00.000Z"
}

curl --request GET "https://bytemax.exchange/api/v1/orders/ord_example/refunds/ref_example" \
  --header "Authorization: Bearer <API_KEY>"

{
  "id": "ref_example",
  "order_id": "ord_example",
  "version": "1",
  "status": "processing",
  "source_currency": "BRL",
  "source_amount_atomic": "2000",
  "target_currency": "CNY",
  "target_amount_atomic": "2500000000",
  "created_at": "2026-09-10T13:05:00.000Z",
  "updated_at": "2026-09-10T13:05:00.000Z"
}

Erros e limites

Toda resposta de erro traz code e message, e às vezes details. Guarde o cabeçalho X-Request-Id: ele identifica a chamada quando você falar com o suporte. Campos desconhecidos e parâmetros repetidos são rejeitados com 400.

{
  "code": "UNSUPPORTED_CURRENCY_PAIR",
  "message": "Unsupported currency pair."
}

Limite de chamadas

5 chamadas por segundo e 300 por minuto por chave. Cada resposta informa o limite nos cabeçalhos abaixo. Ao receber 429, espere até o horário de X-RateLimit-Reset antes de repetir. Para acompanhar ordens, use webhooks em vez de consultar a cada poucos segundos.

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1757509560

Dúvidas na integração? Fale com o suporte.