API ConnectPay

A API REST da ConnectPay permite criar e gerenciar pagamentos via PIX e QR Code com integração simples. Esta referência cobre todos os endpoints, parâmetros e eventos disponíveis.

O que é a API ConnectPay

Uma interface HTTP/JSON sobre TLS que sua aplicação usa para criar cobranças, consultar status e receber notificações de pagamento. Toda a comunicação acontece através do domínio api.connectpay.site.

Casos de uso

• E-commerce: gerar QR Code de PIX no checkout e confirmar pagamento antes do envio.
• SaaS: cobrar assinaturas mensais com renovação automática via PIX recorrente.
• Apps: integrar pagamentos in-app com aprovação em segundos.
• PDV: emitir cobranças dinâmicas em pontos de venda físicos.

Autenticação

A ConnectPay autentica requisições via Bearer Token. Sua API Key deve ser enviada no header Authorization em todas as chamadas — nunca exponha a chave secreta no front-end.

Exemplo de uso

curl https://api.connectpay.site/v1/payments \
  -H "Authorization: Bearer sk_live_a1B2c3D4e5F6g7H8" \
  -H "Content-Type: application/json"

import { ConnectPay } from 'connectpay';

const cp = new ConnectPay('sk_live_a1B2c3D4e5F6g7H8');

import connectpay

cp = connectpay.ConnectPay(api_key="sk_live_a1B2c3D4e5F6g7H8")

Tipos de chave

Criar pagamento

Cria uma cobrança PIX ou QR Code dinâmico. A resposta inclui o payload do PIX copia-e-cola e um URL de imagem com o QR Code renderizado.

Parâmetros do corpo

Exemplo de requisição e resposta

POST /v1/payments
// Authorization: Bearer sk_live_...

{
  "amount": 4990,
  "currency": "BRL",
  "method": "pix",
  "customer": {
    "name": "Maria Almeida",
    "email": "maria@example.com",
    "tax_id": "123.456.789-00"
  },
  "expires_in": 900,
  "metadata": { "order_id": "ord_91A2" }
}

// 201 Created
{
  "id": "pay_01HXZK3M9G6PQ",
  "object": "payment",
  "status": "pending",
  "amount": 4990,
  "currency": "BRL",
  "method": "pix",
  "qr_code": "00020126580014BR.GOV.BCB.PIX0136...",
  "qr_code_image": "https://api.connectpay.site/qr/pay_01HXZK3M9G6PQ.png",
  "expires_at": "2026-05-19T14:30:00Z",
  "created_at": "2026-05-19T14:15:00Z",
  "customer": {
    "name": "Maria Almeida",
    "email": "maria@example.com"
  },
  "metadata": { "order_id": "ord_91A2" }
}

Consultar pagamento

Recupera um pagamento pelo seu identificador. Útil para verificar o status sem precisar esperar o webhook.

Parâmetros de path

Exemplo

curl https://api.connectpay.site/v1/payments/pay_01HXZK3M9G6PQ \
  -H "Authorization: Bearer sk_live_a1B2c3D4e5F6g7H8"

// 200 OK
{
  "id": "pay_01HXZK3M9G6PQ",
  "status": "paid",
  "amount": 4990,
  "currency": "BRL",
  "method": "pix",
  "paid_at": "2026-05-19T14:16:12Z",
  "end_to_end_id": "E18236120202605191416abcdef",
  "metadata": { "order_id": "ord_91A2" }
}

Valores possíveis para status

• pending — aguardando pagamento do cliente.
• paid — pagamento confirmado e liquidado.
• expired — não foi pago dentro de expires_at.
• refunded — pagamento reembolsado total ou parcialmente.
• canceled — cancelado via API antes do pagamento.

Testar a API

Use o widget abaixo para simular uma chamada de criação de pagamento no ambiente sandbox. Nenhum dado real é processado.

// a resposta da API aparecerá aqui

Webhooks

Webhooks notificam seu servidor sobre eventos em tempo real — pagamentos confirmados, expirados, reembolsados. Configure um endpoint público no seu dashboard e a ConnectPay envia um POST JSON sempre que algo acontece.

Exemplo de payload

// POST https://sua-aplicacao.com/webhooks/connectpay
// X-ConnectPay-Signature: t=1716126123,v1=a4b6c8d2...

{
  "id": "evt_01HY9K3M0XQ2A",
  "type": "payment.paid",
  "created_at": "2026-05-19T14:16:12Z",
  "data": {
    "id": "pay_01HXZK3M9G6PQ",
    "status": "paid",
    "amount": 4990,
    "currency": "BRL",
    "paid_at": "2026-05-19T14:16:12Z",
    "end_to_end_id": "E18236120202605191416abcdef",
    "metadata": { "order_id": "ord_91A2" }
  }
}

{
  "id": "evt_01HY9KX3MV8B1",
  "type": "payment.expired",
  "created_at": "2026-05-19T14:30:00Z",
  "data": {
    "id": "pay_01HXZK3M9G6PQ",
    "status": "expired",
    "expires_at": "2026-05-19T14:30:00Z",
    "metadata": { "order_id": "ord_91A2" }
  }
}

Tipos de evento

Integração do cliente

Quer integrar a ConnectPay no seu e-commerce, SaaS ou app? Siga o passo a passo abaixo — em média leva menos de 30 minutos do cadastro até a primeira transação.

1. Crie sua conta Cadastre seu CNPJ no painel da ConnectPay. Verificação automática via Receita Federal em segundos.
2. Obtenha sua API Key No painel, vá em Configurações → Chaves de API e gere uma chave de produção e uma de sandbox.
3. Integre os endpoints Use a chave para chamar POST /v1/payments e gerar QR Codes. Configure seu webhook em Configurações → Webhooks.
4. Teste no sandbox Simule pagamentos com chaves sk_test_… e CPF de teste. Nenhum valor é processado.
5. Vá para produção Troque para chaves sk_live_…, ative o webhook de produção e comece a receber.

SDKs e plugins

Bibliotecas oficiais para as linguagens e plataformas mais usadas. Todas são open source no GitHub e mantidas pela equipe.

SDKs oficiais

Plugins e e-commerce

Perguntas frequentes