Documentação da API

Gere cobranças PIX e por cartão (crédito/débito) pela API do negocios.social. Todas as requisições usam HTTPS e são autenticadas com sua api-key e secret (geradas no seu cadastro; a secret aparece uma única vez).

Base URL

https://api.negocios.social

Todos os endpoints do gateway começam com /gateway.

Autenticação

Use HTTP Basic Auth: a api-key como usuário e a secret como senha (enviadas no cabeçalho Authorization, sobre HTTPS). Nunca exponha a secret no navegador ou no app — use-a apenas no seu servidor.

curl -u "ak_sua_apikey:sk_sua_secret" \
  https://api.negocios.social/gateway/pix/charge/...

Limite de 60 requisições por minuto por api-key. Ao exceder, a API responde 429. Se sua chave tiver uma lista de IPs permitidos, requisições de outros IPs recebem 403.

Validar autenticação

GET /gateway/auth/check

Testa se sua api-key e secret são válidas, sem criar cobrança (nenhum efeito colateral). Ideal para validar a integração. Retorna 200 se as credenciais forem válidas; 401 (credenciais), 403 (IP) ou 429 (limite) caso contrário.

curl -u "ak_sua_apikey:sk_sua_secret" \
  https://api.negocios.social/gateway/auth/check

{
  "success": 1,
  "valid": true,
  "client_id": "66a4f0c2e1b2a3d4e5f60718",
  "pix_enabled": true,
  "card_enabled": false
}

pix_enabled e card_enabled indicam quais meios de pagamento estão habilitados para essa chave.

Criar cobrança PIX

POST /gateway/pix/charge

Parâmetros (corpo JSON)

Campo	Tipo	Descrição
`amount`	inteiro	Obrigatório. Valor em centavos (ex.: `10000` = R$ 100,00).
`label`	texto	Texto enviado ao banco e exibido ao pagador (junto do `external_reference`).
`description`	texto	Descrição interna da cobrança (não vai ao banco).
`external_reference`	texto	Seu identificador do pedido (para conciliação).
`expires_in`	inteiro	Validade do QR em segundos. Padrão `165600` (46h).
`payer.name`	texto	Nome do pagador.
`payer.document`	texto	CPF (11) ou CNPJ (14) do pagador.

Envie o cabeçalho opcional Idempotency-Key para evitar cobranças duplicadas em caso de reenvio — a mesma chave devolve a mesma cobrança.

Requisição

curl -X POST https://api.negocios.social/gateway/pix/charge \
  -u "ak_sua_apikey:sk_sua_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{
    "amount": 10000,
    "label": "Loja XYZ",
    "description": "Pedido #1234",
    "external_reference": "1234",
    "expires_in": 165600,
    "payer": { "name": "Fulano de Tal", "document": "12345678900" }
  }'

Resposta

{
  "success": 1,
  "id": "66a4f0c2e1b2a3d4e5f60718",
  "status": "pending",
  "amount": 10000,
  "qr_code": "00020126580014BR.GOV.BCB.PIX...6304ABCD",
  "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "expires_at": "2026-07-03T18:00:00.000Z"
}

Use qr_code (PIX copia-e-cola) ou qr_code_base64 (imagem PNG pronta para exibir) para apresentar o pagamento ao seu cliente.

Consultar cobrança

GET /gateway/pix/charge/:id

Consulte periodicamente (polling) para saber quando o pagamento foi confirmado. Quando o status virar paid, o valor é creditado no seu saldo.

O :id aceita o id da cobrança ou o seu external_reference. Se houver mais de uma cobrança com o mesmo external_reference, a mais recente é retornada.

# pelo id da cobrança
curl -u "ak_sua_apikey:sk_sua_secret" \
  https://api.negocios.social/gateway/pix/charge/66a4f0c2e1b2a3d4e5f60718

# ou pelo seu external_reference
curl -u "ak_sua_apikey:sk_sua_secret" \
  https://api.negocios.social/gateway/pix/charge/1234

{
  "success": 1,
  "id": "66a4f0c2e1b2a3d4e5f60718",
  "status": "paid",
  "amount": 10000,
  "external_reference": "1234",
  "paid_at": "2026-07-01T18:05:00.000Z",
  "expires_at": "2026-07-03T18:00:00.000Z"
}

Listar cobranças por período

GET /gateway/pix/charges?from=YYYY-MM-DD&to=YYYY-MM-DD

Datas obrigatórias. Janela máxima de 30 dias. Filtro opcional status.

curl -u "ak_sua_apikey:sk_sua_secret" \
  "https://api.negocios.social/gateway/pix/charges?from=2026-07-01&to=2026-07-15"

Cartão de crédito/débito

O cartão usa checkout hospedado: você cria a cobrança, recebe uma checkout_url e redireciona o comprador para essa página (hospedada com segurança). Os dados do cartão não passam pelo seu sistema. A confirmação é por polling, como no PIX.

Criar cobrança de cartão

POST /gateway/card/charge

Campo	Tipo	Descrição
`amount`	inteiro	Obrigatório. Valor em centavos — mín. R$ 5,00 (`500`), máx. R$ 500.000,00 (`50000000`).
`description`	texto	Descrição interna da cobrança.
`external_reference`	texto	Seu identificador do pedido.
`redirect_url`	texto	URL para onde o comprador volta após pagar/cancelar.
`expires_in`	inteiro	Validade do checkout em segundos. Padrão `165600` (46h).
`payer`	objeto	`name`, `document`, `email`, `phone`. Se omitido, é coletado na página.
`card`	objeto	Opcional — sobrescreve os padrões da sua api-key (abaixo).

Campos do objeto card (todos opcionais):

Campo	Valores	Descrição
`type`	`CREDIT` · `DEBIT`	Tipo do cartão.
`installments`	inteiro	Nº de parcelas — limitado ao teto da sua chave.
`fixed_installments`	booleano	`false` deixa o pagador escolher as parcelas.
`interest_type`	`BY_ISSUER` · `BY_SELLER`	Juros por conta do emissor (você recebe cheio) ou do lojista (sem juros ao comprador).
`authenticate`	`OPTIONAL` · `REQUIRED` · `NOT_REQUIRED`	Autenticação 3DS (antifraude).

O objeto card é opcional: sem ele, valem os padrões configurados na sua api-key. Envie apenas quando precisar variar por transação.

Requisição

curl -X POST https://api.negocios.social/gateway/card/charge \
  -u "ak_sua_apikey:sk_sua_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{
    "amount": 29900,
    "description": "Pedido #1234",
    "external_reference": "1234",
    "redirect_url": "https://sualoja.com/pedido/1234",
    "payer": { "name": "Fulano de Tal", "document": "12345678900", "email": "fulano@email.com" },
    "card": { "type": "CREDIT", "installments": 3, "interest_type": "BY_ISSUER" }
  }'

Resposta

{
  "success": 1,
  "id": "66a4f0c2e1b2a3d4e5f60718",
  "method": "card",
  "status": "pending",
  "amount": 29900,
  "checkout_url": "https://.../checkout/01KB3EXE7Z...",
  "installments": 3,
  "expires_at": "2026-07-07T12:30:00.000Z"
}

Redirecione o comprador para a checkout_url e guarde o id.

Consultar cobrança de cartão

GET /gateway/card/charge/:id

O :id aceita o id da cobrança ou o seu external_reference (a mais recente, em caso de repetição).

# pelo id da cobrança
curl -u "ak_sua_apikey:sk_sua_secret" \
  https://api.negocios.social/gateway/card/charge/66a4f0c2e1b2a3d4e5f60718

# ou pelo seu external_reference
curl -u "ak_sua_apikey:sk_sua_secret" \
  https://api.negocios.social/gateway/card/charge/1234

Faça polling até um status terminal. Valores de status: pending, paid, failed (recusado), expired, cancelled (cancelado/estornado).

Listar cobranças de cartão

GET /gateway/card/charges?from=YYYY-MM-DD&to=YYYY-MM-DD

curl -u "ak_sua_apikey:sk_sua_secret" \
  "https://api.negocios.social/gateway/card/charges?from=2026-07-01&to=2026-07-15"

Repasse e chargeback: vendas no cartão ficam retidas por um período (definido na sua conta) antes de entrar no saldo, como proteção a chargeback. Contestação antes da liberação cancela o valor retido (sem prejuízo); depois de liberado, gera um estorno no saldo.

Status & erros

Valores possíveis de status:

pending — aguardando pagamento
paid — pago (creditado no saldo)
expired — expirado sem pagamento
failed — recusado pelo emissor (cartão)
cancelled — cancelado ou estornado (cartão)

Toda resposta traz success (1 ou 0). Em erro, vem também error com a mensagem, e o código HTTP apropriado (400 dados inválidos, 401 credenciais, 403 IP, 429 limite, 502 provedor).

{ "success": 0, "error": "Credenciais inválidas." }

Valores monetários são sempre inteiros em centavos.