CredPix API v2 — Documentacao

Autenticacao

Todas as requisicoes exigem autenticacao via API Key (Bearer Token). Endpoints que criam recursos ou acessam saldo tambem exigem assinatura HMAC-SHA256.

1. Bearer Token

Envie sua API Key no header Authorization:

Authorization: Bearer cpx_live_SUA_CHAVE_AQUI

2. Assinatura HMAC-SHA256

Para endpoints protegidos (criar pagamento, solicitar saque, consultar saldo), envie dois headers adicionais:

Header	Descricao
X-CredPix-Timestamp	Unix timestamp em segundos (ex: `1709500000`). Janela de 5 minutos.
X-CredPix-Signature	HMAC-SHA256 hex de `timestamp.body` usando seu API Secret.

O timestamp nao pode ter diferenca superior a 5 minutos do servidor. Requisicoes fora dessa janela serao rejeitadas com erro timestamp_expired.

Exemplos de calculo da assinatura

import crypto from 'node:crypto';

const apiKey    = 'cpx_live_SUA_CHAVE_AQUI';
const apiSecret = 'SEU_SECRET_AQUI';
const timestamp = Math.floor(Date.now() / 1000).toString();
const body      = JSON.stringify({ amount: 100 });

const signature = crypto
  .createHmac('sha256', apiSecret)
  .update(timestamp + '.' + body)
  .digest('hex');

const res = await fetch('https://api.credpix.finance/v2/payment/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'X-CredPix-Timestamp': timestamp,
    'X-CredPix-Signature': signature,
  },
  body: body,
});

import hmac, hashlib, time, json, requests

api_key    = 'cpx_live_SUA_CHAVE_AQUI'
api_secret = 'SEU_SECRET_AQUI'
timestamp  = str(int(time.time()))
body       = json.dumps({"amount": 100})

signature = hmac.new(
    api_secret.encode(), (timestamp + '.' + body).encode(),
    hashlib.sha256
).hexdigest()

r = requests.post('https://api.credpix.finance/v2/payment/create',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json',
        'X-CredPix-Timestamp': timestamp,
        'X-CredPix-Signature': signature,
    },
    data=body
)

<?php
$apiKey    = 'cpx_live_SUA_CHAVE_AQUI';
$apiSecret = 'SEU_SECRET_AQUI';
$timestamp = (string)time();
$body      = json_encode(['amount' => 100]);

$signature = hash_hmac('sha256', $timestamp . '.' . $body, $apiSecret);

$ch = curl_init('https://api.credpix.finance/v2/payment/create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey",
        'Content-Type: application/json',
        "X-CredPix-Timestamp: $timestamp",
        "X-CredPix-Signature: $signature",
    ],
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);

# Gerar timestamp e assinatura
TIMESTAMP=$(date +%s)
BODY='{"amount":100}'
SIGNATURE=$(echo -n "${TIMESTAMP}.${BODY}" | \
  openssl dgst -sha256 -hmac "SEU_SECRET_AQUI" | cut -d' ' -f2)

curl -X POST https://api.credpix.finance/v2/payment/create \
  -H "Authorization: Bearer cpx_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -H "X-CredPix-Timestamp: $TIMESTAMP" \
  -H "X-CredPix-Signature: $SIGNATURE" \
  -d "$BODY"

Criar Pagamento PIX

POST /v2/payment/create HMAC

Cria um novo pagamento PIX e retorna o QR Code e o codigo copia-e-cola para pagamento.

Parametros (Body JSON)

Parametro	Tipo		Descricao
amount	number	Obrigatorio	Valor em reais (1.00 a 50000.00)
callbackUrl	string	Obrigatorio	URL HTTPS para receber webhook quando o pagamento for confirmado
externalId	string	Opcional	Seu ID interno. Garante idempotencia — mesma externalId retorna o pagamento existente

Resposta de Sucesso (200)

{
  "ok": true,
  "payment": {
    "id": "a1b2c3d4e5f6...",
    "externalId": "pedido_123",
    "amount": "100.00",
    "status": "pending",
    "pixCopiaECola": "00020126580014br.gov.bcb.pix...",
    "qrCodeBase64": "data:image/png;base64,iVBOR...",
    "expiresAt": "2026-03-05T15:30:00.000Z"
  }
}

O QR Code expira em 30 minutos. Apos expirar, o pagamento muda para status expired e nao pode mais ser pago.

▶ Testar Endpoint

▼

API Key

API Secret

Amount (R$)

External ID (Opcional)

Callback URL (Opcional)

Verificar Pagamento

GET /v2/payment/:id/status

Consulta o status de um pagamento pelo id retornado na criacao ou pelo seu externalId.

Parametros (Path)

Parametro	Tipo		Descricao
:id	string	Obrigatorio	ID do pagamento (`id`) ou `externalId`

Resposta de Sucesso (200)

{
  "ok": true,
  "payment": {
    "id": "a1b2c3d4e5f6...",
    "externalId": "pedido_123",
    "amount": "100.00",
    "status": "approved",
    "payer": {
      "name": "JOAO DA SILVA",
      "document": "***456789**"
    },
    "endToEndId": "E0001234520260305...",
    "createdAt": "2026-03-05T15:00:00.000Z",
    "updatedAt": "2026-03-05T15:02:30.000Z"
  }
}

Status possiveis

Status	Descricao
pending	Aguardando pagamento
approved	Pagamento confirmado
expired	QR Code expirado (30 min)
cancelled	Pagamento cancelado

▶ Testar Endpoint

▼

API Key

Payment ID ou External ID

Solicitar Saque PIX

POST /v2/withdrawal/create HMAC

Solicita um saque PIX para uma chave especificada. O valor e debitado do saldo imediatamente e o PIX e enviado em tempo real.

Este endpoint tem rate limit de 10 requisicoes por minuto. Saques via API devem ser habilitados pelo administrador.

Parametros (Body JSON)

Parametro	Tipo		Descricao
amount	number	Obrigatorio	Valor liquido do saque em reais (minimo 1.00)
pixKey	string	Obrigatorio	Chave PIX do destinatario
pixKeyType	string	Opcional	Tipo da chave: `cpf`, `cnpj`, `email`, `phone`, `evp`, `random`. Default: `evp`
callbackUrl	string	Obrigatorio	URL HTTPS para receber webhook com o resultado do saque
externalId	string	Opcional	Seu ID interno (idempotencia)

Resposta de Sucesso (200)

{
  "ok": true,
  "withdrawal": {
    "id": "txid_abc123...",
    "externalId": "saque_456",
    "amount": "500.00",
    "fee": "26.00",
    "gross": "526.00",
    "status": "approved",
    "pixKey": "[email protected]",
    "pixKeyType": "email",
    "destination": {
      "name": "MARIA SOUZA",
      "bank": "Nu Pagamentos"
    },
    "endToEndId": "E0001234520260305...",
    "gateway": "payzu"
  }
}

Calculo de taxas

O valor bruto debitado do saldo e: amount + (amount * taxa%) + R$1.00 fixo.
As taxas sao definidas por conta. Consulte /v2/account/balance para ver suas taxas atuais.

▶ Testar Endpoint

▼

API Key

API Secret

Amount (R$)

PIX Key Type

PIX Key

External ID (Opcional)

Callback URL (Opcional)

Verificar Saque

GET /v2/withdrawal/:id/status

Consulta o status de um saque pelo txid retornado na criacao ou pelo seu externalId.

Parametros (Path)

Parametro	Tipo		Descricao
:id	string	Obrigatorio	ID do saque (`id`) ou `externalId`

Resposta de Sucesso (200)

{
  "ok": true,
  "withdrawal": {
    "id": "txid_abc123...",
    "externalId": "saque_456",
    "amount": "500.00",
    "gross": "526.00",
    "status": "aprovado",
    "pixKey": "[email protected]",
    "destination": {
      "name": "MARIA SOUZA",
      "bank": "Nu Pagamentos"
    },
    "endToEndId": "E0001234520260305...",
    "gateway": "payzu",
    "createdAt": "2026-03-05T14:00:00.000Z"
  }
}

▶ Testar Endpoint

▼

API Key

Withdrawal ID ou External ID

Consultar Saldo

POST /v2/account/balance HMAC

Retorna o saldo atual, reservas, limites e taxas da sua conta. O body pode ser vazio ({}) mas a assinatura HMAC e obrigatoria.

Resposta de Sucesso (200)

{
  "ok": true,
  "account": {
    "balance": "15420.50",
    "reserved": "0.00",
    "available": "15420.50",
    "limits": {
      "withdrawal": "1000.00",
      "generate": "500.00"
    },
    "fees": {
      "withdrawalPct": 5,
      "withdrawalFixed": 1.0,
      "depositPct": 2
    }
  }
}

DOCUMENTACAO DE SAQUES

A documentacao de saques PIX via API so e exibida para contas com essa funcionalidade habilitada. Teste o endpoint de saldo abaixo com suas credenciais — se sua conta tiver saques habilitados, a documentacao aparecera automaticamente.

▶ Testar Endpoint

▼

API Key

API Secret

Webhooks de Saida

Quando um evento ocorre (pagamento confirmado, saque concluido), a CredPix envia um POST para a sua URL de callback.

Como configurar

Existem duas formas de receber webhooks:

1. Por requisicao (recomendado): Envie o parametro callbackUrl ao criar um pagamento ou saque. O webhook sera enviado para essa URL quando o evento ocorrer.

// Exemplo: criar pagamento com callback
{
  "amount": 100,
  "callbackUrl": "https://seu-site.com/webhook/credpix",
  "externalId": "pedido_123"
}

2. URL global da conta: Configure uma URL padrao no painel do MiniApp (app.credpix.finance > Configuracoes > API). Todos os pagamentos sem callbackUrl usarao essa URL.

A callbackUrl deve usar HTTPS obrigatoriamente. URLs HTTP serao rejeitadas. Sua URL deve retornar status 2xx para confirmar o recebimento.

Formato do Payload

// Exemplo: payment.confirmed
{
  "event": "payment.confirmed",
  "timestamp": "2026-03-05T15:02:30.000Z",
  "data": {
    "id": "a1b2c3d4e5f6...",
    "externalId": "pedido_123",
    "amount": "100.00",
    "status": "approved",
    "payer": {
      "name": "JOAO DA SILVA",
      "document": "***456789**"
    },
    "endToEndId": "E0001234520260305..."
  }
}

Headers de verificacao

Header	Descricao
X-CredPix-Signature	HMAC-SHA256 do body completo usando seu `api_secret`. Valide este header para garantir autenticidade.
Content-Type	`application/json`

Verificacao do webhook (Node.js)

import crypto from 'node:crypto';

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature), Buffer.from(expected)
  );
}

Politica de retry

Se sua URL retornar status diferente de 2xx, a CredPix fara ate 3 tentativas:

1a tentativa: imediata
2a tentativa: apos 5 segundos
3a tentativa: apos 30 segundos

Apos 3 falhas, o webhook e marcado como failed no log.

Eventos disponiveis

Evento	Descricao
payment.confirmed	Pagamento PIX foi confirmado pelo banco
withdrawal.completed	Saque PIX foi enviado com sucesso
withdrawal.failed	Saque PIX falhou (saldo estornado)

Erros & Limites

Rate Limits

Escopo	Limite	Janela
Geral (todos endpoints)	60 requisicoes	1 minuto
Saques (/withdrawal/create)	10 requisicoes	1 minuto

Ao exceder o limite, a API retorna 429 Too Many Requests.

Codigos de Erro

Codigo HTTP	Erro	Descricao
400	`invalid_amount`	Valor fora do intervalo permitido (1-50000)
400	`invalid_callback_url`	URL de callback invalida ou nao usa HTTPS
400	`missing_pix_key`	Chave PIX nao informada
400	`invalid_pix_key_type`	Tipo de chave invalido
400	`amount_exceeds_limit`	Valor excede o limite de geracao da conta
400	`exceeds_withdrawal_limit`	Valor excede o limite de saque da conta
400	`insufficient_balance`	Saldo insuficiente (considerando taxas)
401	`missing_api_key`	Header Authorization ausente
401	`invalid_api_key`	API Key nao encontrada ou inativa
401	`missing_signature`	Headers de assinatura HMAC ausentes
401	`timestamp_expired`	Timestamp fora da janela de 5 minutos
401	`invalid_signature`	Assinatura HMAC nao confere
403	`withdrawal_not_enabled`	Saque via API nao habilitado para a conta
404	`payment_not_found`	Pagamento nao encontrado
404	`withdrawal_not_found`	Saque nao encontrado
429	`rate_limit_exceeded`	Limite de requisicoes excedido
500	`internal_error`	Erro interno do servidor
502	`gateway_error`	Erro na comunicacao com o gateway de pagamento
502	`gateway_no_brcode`	Gateway nao retornou o codigo PIX

Formato padrao de erro

{
  "ok": false,
  "error": "invalid_amount",
  "message": "amount must be between 1.00 and 50000.00"
}