Gateway
Docs Entrar Começar

Integração e API

Entre para ver e copiar as suas chaves aqui.

Use sempre HTTPS em produção. Os URLs abaixo já apontam para esta instalação.

Boas práticas de segurança

Autenticação (v1)

Em todos os pedidos a api/v1/*, envie:

Nos POST com corpo JSON, use Content-Type: application/json. Em POST /payments também é aceite autenticação por campos de formulário api_key e api_secret (não recomendado; prefira os cabeçalhos).

Códigos HTTP frequentes

Criar cobrança (checkout PIX ou cripto)

POST https://zommo.biz/api/v1/payments

amount_brl mínimo: 1,00. Opcional: webhook_url (URL válida), return_url, metadata (object), idempotency_key (evita cobranças duplicadas ao repetir o mesmo pedido).

{
  "amount_brl": 99.90,
  "webhook_url": "https://seusite.com/webhook",
  "return_url": "https://seusite.com/obrigado",
  "metadata": { "pedido": "123" },
  "idempotency_key": "opcional-uuid-ou-id-interno"
}

Resposta (sucesso): ok, payment.id, payment.status, payment.amount_brl, payment.checkout_url. Se repetir o mesmo idempotency_key, a resposta inclui "idempotent": true e o mesmo checkout_url.

Envie o comprador para checkout_url: na página ele escolhe PIX ou criptomoeda; não é necessário indicar o meio no JSON da cobrança.

Checkout “dentro do seu site” (modo inline)

Se preferir não redirecionar para o checkout hospedado, use payment_mode: "inline". Neste modo a API já cria a cobrança no provedor (PIX/cripto) e devolve um payload em inline para você renderizar (QR/code) no seu próprio site. O payment.checkout_url continua existindo por compatibilidade, mas não é necessário usar.

Inline PIX

POST https://zommo.biz/api/v1/payments

{
  "amount_brl": 99.90,
  "payment_mode": "inline",
  "payment_method": "pix",
  "webhook_url": "https://seusite.com/webhook",
  "return_url": "https://seusite.com/obrigado",
  "metadata": { "pedido": "123" },
  "idempotency_key": "pedido-123"
}

Campos de pagador são opcionais (o gateway pode exigir). Se quiser enviar: payer_name, payer_email, payer_document, payer_doc_type (cpf/cnpj).

Resposta: além de payment.*, vem inline.pix.emv (PIX copia e cola). Você pode gerar o QR no front usando qualquer biblioteca (ex.: qrcode.js) a partir desse texto.

Inline cripto

POST https://zommo.biz/api/v1/payments

{
  "amount_brl": 99.90,
  "payment_mode": "inline",
  "payment_method": "crypto",
  "pay_currency": "usdtbsc",
  "webhook_url": "https://seusite.com/webhook",
  "metadata": { "pedido": "123" },
  "idempotency_key": "pedido-123"
}

Resposta: inline.crypto.pay_address, inline.crypto.pay_amount, inline.crypto.pay_currency, inline.crypto.qr_uri (texto pronto para QR), e opcionalmente inline.crypto.invoice_url se o provedor devolver.

Moedas permitidas: btc, ltc, sol, eth, bnbbsc, usdtbsc.

Fluxo de pagamento em cripto (no checkout)

  1. Crie a cobrança pela API e obtenha checkout_url.
  2. O comprador abre o link e, na secção cripto, escolhe a moeda/rede e confirma.
  3. Após confirmação na rede, o pagamento fica pago e o webhook_url (se informado) recebe o evento payment.paid, como no PIX.

Moedas disponíveis no checkout (campo pay_currency no formulário):

Valor mínimo para cripto no checkout: R$ 5,00 em BRL na cobrança (regra da plataforma).

Consultar cobrança

GET https://zommo.biz/api/v1/payments?id=ID_DO_PAGAMENTO (mesmos cabeçalhos X-API-Key / X-API-Secret).

Resposta: payment.id, status, amount_brl, method, kind, created_at.

Extrato e indicadores

GET https://zommo.biz/api/v1/transactions?limit=50&offset=0&days=30

O objecto stats inclui, entre outros: period_days, recebido_liquido, volume_bruto, n_transacoes, ticket_medio, enviado_total (no período em dias indicado por days). movements lista movimentos com campos como tipo, rotulo, bruto, status, created_at.

Enviar PIX (sair do saldo)

POST https://zommo.biz/api/v1/payouts com Content-Type: application/json.

É obrigatório um identificador de idempotência, por uma destas formas:

Reenviar o mesmo identificador com o mesmo corpo devolve a mesma resposta sem novo débito. Corpo diferente com a mesma chave → 409.

{
  "amount_brl": 50.00,
  "pix_key": "00000000000",
  "pix_type": "cpf",
  "idempotency_key": "use-o-se-não-enviar-o-header"
}

amount_brl é o total debitado do saldo. A taxa de saída é descontada desse valor. Na resposta: payout.fee_brl, payout.net_brl (líquido enviado ao PIX), payout.total_debited_brl. Tipos PIX: cpf, cnpj, email, phone, random, evp. pending_approval: true indica saque em fila para aprovação manual, se a plataforma estiver nesse modo.

Webhook no seu servidor

Quando o pagamento é confirmado, é enviado um POST JSON para o webhook_url definido na criação da cobrança (requer URL válida e webhook secret não vazio nas chaves do lojista).

Cabeçalhos enviados:

Corpo do evento (exemplo):

{
  "event": "payment.paid",
  "payment": {
    "id": 123,
    "merchant_id": 1,
    "amount_brl": 99.90,
    "net_credited_brl": 95.00,
    "method": "pix",
    "status": "paid",
    "metadata": { }
  }
}

Valide sempre a assinatura antes de dar o produto ou serviço como pago. O campo metadata reproduz o que enviou ao criar a cobrança.

Notificações

Não é necessário configurar endpoints internos da plataforma: basta indicar o webhook_url ao criar a cobrança. Quando o pagamento for confirmado, o servidor recebe o evento assinado no URL indicado.