Introdução

A API PagNow permite integrar pagamentos PIX de forma rápida e segura. Todos os endpoints utilizam JSON e requerem autenticação via API Key.

Base URLProdução
https://api.pagnow.com/api/v1
HTTPS
Conexão segura obrigatória
JSON
Request e Response
REST
Arquitetura padrão

Autenticação

Todas as requisições devem incluir sua API Key no header. Você pode gerar sua chave no painel em Configurações → API Keys.

Header
1
X-API-Key: sk_live_sua_api_key_aqui

Importante

Nunca exponha sua API Key no frontend ou código público. Todas as requisições devem ser feitas pelo seu servidor backend.

Exemplo cURL

Terminal
1
2
3
curl -X GET "https://api.pagnow.com/api/v1/wallet/balance" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_sua_api_key_aqui"
POST
/pix

Criar Cobrança PIX

Cria uma nova cobrança PIX e retorna o QR Code para pagamento.

Parâmetros

ParâmetroTipo
amountobrigatório
integer
customerobrigatório
object
customer.nameobrigatório
string
customer.emailobrigatório
string
customer.documentobrigatório
string
customer.documentTypeobrigatório
string
externalRefopcional
string
expiresInDaysopcional
integer

Request Body

JSON
1
2
3
4
5
6
7
8
9
10
11
{
  "amount": 10000,
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "12345678901",
    "documentType": "cpf"
  },
  "externalRef": "ORDER-12345",
  "expiresInDays": 1
}

Response

200 OK
JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "WAITING_PAYMENT",
  "amount": 10000,
  "currency": "BRL",
  "pixQrCode": "00020126580014br.gov.bcb.pix...",
  "pixCopyPaste": "00020126580014br.gov.bcb.pix...",
  "pixExpiresAt": "2026-01-12T03:00:00.000Z",
  "externalRef": "ORDER-12345",
  "createdAt": "2026-01-11T03:00:00.000Z",
  "fee": 570,
  "netAmount": 9430
}
GET
/pix/:id

Consultar Transação

Retorna os detalhes de uma transação específica pelo ID.

Parâmetros

ParâmetroTipo
idobrigatório
string

Response

200 OK

Retorna todos os dados da transação incluindo status atualizado.

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PAID",
  "amount": 10000,
  "currency": "BRL",
  "pixQrCode": "00020126580014br.gov.bcb.pix...",
  "pixExpiresAt": "2026-01-12T03:00:00.000Z",
  "externalRef": "ORDER-12345",
  "createdAt": "2026-01-11T03:00:00.000Z",
  "paidAt": "2026-01-11T03:05:00.000Z",
  "fee": 570,
  "netAmount": 9430,
  "customerName": "João Silva",
  "customerEmail": "joao@email.com",
  "pixEnd2EndId": "E12345678901234567890123456789012"
}
GET
/pix/external/:externalRef

Buscar por Referência Externa

Busca uma transação pela sua referência externa (externalRef). Útil para integração com seu sistema.

Parâmetros

ParâmetroTipo
externalRefobrigatório
string

Response

200 OK

Retorna a transação correspondente ou erro 404 se não encontrada.

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PAID",
  "amount": 10000,
  "currency": "BRL",
  "pixQrCode": "00020126580014br.gov.bcb.pix...",
  "pixExpiresAt": "2026-01-12T03:00:00.000Z",
  "externalRef": "ORDER-12345",
  "createdAt": "2026-01-11T03:00:00.000Z",
  "paidAt": "2026-01-11T03:05:00.000Z",
  "fee": 570,
  "netAmount": 9430,
  "customerName": "João Silva",
  "customerEmail": "joao@email.com",
  "pixEnd2EndId": "E12345678901234567890123456789012"
}
GET
/pix

Listar Transações

Lista todas as transações com paginação e filtros.

Parâmetros

ParâmetroTipo
pageopcional
integer
limitopcional
integer
statusopcional
string
externalRefopcional
string
startDateopcional
string
endDateopcional
string

Response

200 OK
JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "PAID",
      "amount": 10000,
      "createdAt": "2026-01-11T03:00:00.000Z",
      "externalRef": "ORDER-12345"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
GET
/wallet/balance

Consultar Saldo

Retorna o saldo disponível e pendente da sua conta.

Response

200 OK

O saldo 'available' pode ser sacado. O 'pending' está em processamento.

JSON
1
2
3
4
5
6
{
  "available": 95000,
  "availableFormatted": "R$ 950,00",
  "pending": 10000,
  "pendingFormatted": "R$ 100,00"
}
POST
/withdrawals

Solicitar Saque PIX

Solicita um saque PIX para a chave informada. Processamento automático.

Parâmetros

ParâmetroTipo
amountobrigatório
integer
pixKeyobrigatório
string
pixKeyTypeobrigatório
string

Request Body

JSON
1
2
3
4
5
{
  "amount": 50000,
  "pixKey": "12345678901",
  "pixKeyType": "cpf"
}

Response

200 OK
JSON
1
2
3
4
5
6
7
8
9
10
11
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PENDING",
  "amount": 50000,
  "fee": 0,
  "netAmount": 50000,
  "paymentMethod": "PIX",
  "pixKey": "123***901",
  "pixKeyType": "cpf",
  "createdAt": "2026-01-11T03:00:00.000Z"
}
GET
/withdrawals

Listar Saques

Lista todos os saques com paginação e filtros.

Parâmetros

ParâmetroTipo
pageopcional
integer
limitopcional
integer
statusopcional
string
paymentMethodopcional
string

Response

200 OK
JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "COMPLETED",
      "amount": 50000,
      "fee": 0,
      "netAmount": 50000,
      "paymentMethod": "PIX",
      "pixKey": "123***901",
      "pixKeyType": "cpf",
      "createdAt": "2026-01-11T03:00:00.000Z",
      "completedAt": "2026-01-11T03:05:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
GET
/withdrawals/:id

Consultar Saque

Retorna os detalhes de um saque específico pelo ID.

Parâmetros

ParâmetroTipo
idobrigatório
string

Response

200 OK

Retorna todos os dados do saque incluindo status atualizado.

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "COMPLETED",
  "amount": 50000,
  "fee": 0,
  "netAmount": 50000,
  "paymentMethod": "PIX",
  "pixKey": "12345678901",
  "pixKeyType": "cpf",
  "pixEnd2EndId": "E12345678901234567890123456789012",
  "createdAt": "2026-01-11T03:00:00.000Z",
  "completedAt": "2026-01-11T03:05:00.000Z"
}
POST
/withdrawals/:id/cancel

Cancelar Saque

Cancela um saque pendente. O valor é estornado para o saldo disponível.

Parâmetros

ParâmetroTipo
idobrigatório
string

Response

200 OK

Só é possível cancelar saques com status PENDING. Um webhook withdrawal.updated será enviado.

JSON
1
2
3
4
5
6
7
8
9
10
11
12
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "CANCELLED",
  "amount": 50000,
  "fee": 0,
  "netAmount": 50000,
  "paymentMethod": "PIX",
  "pixKey": "123***901",
  "pixKeyType": "cpf",
  "createdAt": "2026-01-11T03:00:00.000Z",
  "cancelledAt": "2026-01-11T03:10:00.000Z"
}
POST
/withdrawals/crypto

Solicitar Saque Crypto (USDT)

Solicita um saque em USDT para a wallet informada. O valor é descontado imediatamente do saldo.

Parâmetros

ParâmetroTipo
amountobrigatório
integer
cryptoCurrencyobrigatório
string
cryptoNetworkobrigatório
string
cryptoAddressobrigatório
string

Request Body

JSON
1
2
3
4
5
6
{
  "amount": 50000,
  "cryptoCurrency": "USDT",
  "cryptoNetwork": "TRC20",
  "cryptoAddress": "TXYZabcdefghijklmnopqrstuvwxyz123456"
}

Response

200 OK
JSON
1
2
3
4
5
6
7
8
9
10
11
12
{
  "id": "789e4567-e89b-12d3-a456-426614174001",
  "status": "PENDING",
  "amount": 50000,
  "fee": 0,
  "netAmount": 50000,
  "paymentMethod": "CRYPTO",
  "cryptoCurrency": "USDT",
  "cryptoNetwork": "TRC20",
  "cryptoAddress": "TXYZ***xyz123456",
  "createdAt": "2026-01-11T03:00:00.000Z"
}

Importante - Saques Crypto

  • O valor é descontado imediatamente do saldo disponível
  • O status inicial é PENDING
  • O administrador marca como pago quando o saque for processado
  • Um webhook withdrawal.updated é enviado quando o status muda
  • Redes suportadas: TRC20, ERC20, BEP20, POLYGON

Webhooks

Configure uma URL de webhook no painel para receber notificações automáticas quando o status das transações mudar.

Eventos

transaction.createdtransaction.updatedwithdrawal.updated

O evento transaction.created é enviado quando uma nova cobrança PIX é criada. O evento transaction.updated é enviado quando o status da transação muda (ex: PAID, EXPIRED, CANCELLED, REFUNDED). O evento withdrawal.updated é enviado quando o status de um saque muda (PIX ou Crypto: PENDING → COMPLETED ou CANCELLED).

Payload - transaction.created

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "event": "transaction.created",
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalRef": "ORDER-12345",
    "status": "WAITING_PAYMENT",
    "amount": 10000,
    "netAmount": 9430,
    "fee": 570,
    "currency": "BRL",
    "customerName": "João Silva",
    "customerEmail": "joao@email.com",
    "customerDocument": "12345678901",
    "pixQrCode": "00020126580014br.gov.bcb.pix...",
    "pixExpiresAt": "2026-01-12T03:00:00.000Z",
    "createdAt": "2026-01-11T03:00:00.000Z"
  },
  "tenant": {
    "id": "tenant-uuid",
    "name": "Sua Empresa"
  },
  "timestamp": "2026-01-11T03:00:00.000Z"
}

Payload - transaction.updated (Pagamento Confirmado)

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "event": "transaction.updated",
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalRef": "ORDER-12345",
    "status": "PAID",
    "amount": 10000,
    "netAmount": 9430,
    "fee": 570,
    "currency": "BRL",
    "customerName": "João Silva",
    "customerEmail": "joao@email.com",
    "customerDocument": "12345678901",
    "createdAt": "2026-01-11T03:00:00.000Z",
    "paidAt": "2026-01-11T03:05:00.000Z",
    "pixEnd2EndId": "E12345678901234567890123456789012"
  },
  "tenant": {
    "id": "tenant-uuid",
    "name": "Sua Empresa"
  },
  "timestamp": "2026-01-11T03:05:00.000Z"
}

Payload - withdrawal.updated (Saque PIX)

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "event": "withdrawal.updated",
  "withdrawal": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "COMPLETED",
    "amount": 50000,
    "fee": 0,
    "netAmount": 50000,
    "paymentMethod": "PIX",
    "pixKey": "123***901",
    "pixKeyType": "cpf",
    "pixEnd2EndId": "E12345678901234567890123456789012",
    "createdAt": "2026-01-11T03:00:00.000Z",
    "completedAt": "2026-01-11T03:05:00.000Z"
  },
  "tenant": {
    "id": "tenant-uuid",
    "name": "Sua Empresa"
  },
  "timestamp": "2026-01-11T03:05:00.000Z"
}

Payload - withdrawal.updated (Saque Crypto - USDT)

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "event": "withdrawal.updated",
  "withdrawal": {
    "id": "789e4567-e89b-12d3-a456-426614174001",
    "status": "COMPLETED",
    "amount": 50000,
    "fee": 0,
    "netAmount": 50000,
    "paymentMethod": "CRYPTO",
    "cryptoCurrency": "USDT",
    "cryptoNetwork": "TRC20",
    "cryptoAddress": "TXYZabcdefghijklmnopqrstuvwxyz123456",
    "createdAt": "2026-01-11T03:00:00.000Z",
    "completedAt": "2026-01-11T03:10:00.000Z"
  },
  "tenant": {
    "id": "tenant-uuid",
    "name": "Sua Empresa"
  },
  "timestamp": "2026-01-11T03:10:00.000Z"
}

Para saques crypto, o campo paymentMethod será "CRYPTO"e incluirá os campos cryptoCurrency, cryptoNetworke cryptoAddress. O status pode ser PENDING,COMPLETED ou CANCELLED (quando cancelado, o valor é estornado).

Confirmação e Retries

Responda com status HTTP 2xx para confirmar o recebimento. Em caso de falha, tentaremos reenviar até 10 vezes com backoff exponencial (5s, 15s, 45s, 2min, 5min, 15min, 30min, 1h, 2h, 4h).

Headers de Segurança

Cada webhook inclui headers para verificação de autenticidade:

HeaderDescrição
X-PagNow-EventTipo do evento (transaction.created, transaction.updated)
X-PagNow-DeliveryID único da entrega (para debug e retry)
X-PagNow-TimestampTimestamp Unix da requisição
X-PagNow-SignatureAssinatura HMAC SHA-256 para verificação

Verificando a Assinatura

Para garantir que o webhook veio da PagNow, verifique a assinatura HMAC:

Terminal
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// Node.js exemplo
const crypto = require('crypto');
 
function verifyWebhook(payload, timestamp, signature, secret) {
  const signedPayload = timestamp + '.' + JSON.stringify(payload);
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
 
// No seu endpoint de webhook:
const isValid = verifyWebhook(
  req.body,
  req.headers['x-pagnow-timestamp'],
  req.headers['x-pagnow-signature'],
  'seu_webhook_secret'
);
 
if (!isValid) {
  return res.status(401).json({ error: 'Invalid signature' });
}

Webhook Secret

Seu webhook secret está disponível no painel em Configurações → Webhooks. Mantenha-o seguro e nunca exponha no frontend.

Status de Transação

PENDINGTransação criada, aguardando processamento
WAITING_PAYMENTQR Code gerado, aguardando pagamento
PROCESSINGPagamento em processamento
PAIDPagamento confirmado
APPROVEDPagamento aprovado
EXPIREDQR Code expirado
CANCELLEDTransação cancelada
REFUSEDPagamento recusado
REFUNDEDPagamento estornado
CHARGEBACKChargeback recebido
DISPUTEEm disputa/contestação

Status de Saque

PENDINGAguardando processamento
PROCESSINGEm processamento
PENDING_ANALYSISEm análise de compliance
COMPLETEDSaque concluído com sucesso
CANCELLEDSaque cancelado (valor estornado)
REFUSEDSaque recusado

Não encontrou o que procurava?