Começando
Documentação completa da CC PAG Global API v2. Todos os endpoints, parâmetros e exemplos de integração.
https://api.ccpaglobal.com/v2/
Autenticação
Todas as requisições exigem client_id e client_secret no corpo ou query string. Nunca exponha o client_secret em código client-side.
Credenciais de Produção
Acesse o painel em ccpaglobal.com/keys → menu API → Credenciais para gerar suas chaves.
Acesso Sandbox
Solicite credenciais de sandbox ao nosso time de suporte através do seu gerente de conta.
Exemplo de Integração
Exemplo completo de geração de QR Code PIX:
$ch = curl_init('https://api.ccpaglobal.com/v2/pix/qrcode.php');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'client_id' => getenv('CCPAG_CLIENT_ID'),
'client_secret' => getenv('CCPAG_CLIENT_SECRET'),
'nome' => 'James Kirk',
'cpf' => '12345678901',
'valor' => 100.00,
'descricao' => 'Service payment',
'urlnoty' => 'https://yoursite.com/webhook.php',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
if (isset($data['qrcode'])) {
echo "QR Code: " . $data['qrcode'];
echo "Transaction ID: " . $data['transactionId'];
} else {
echo "Error: " . ($data['message'] ?? 'Unknown');
}
import os
import requests
url = 'https://api.ccpaglobal.com/v2/pix/qrcode.php'
payload = {
'client_id': os.getenv('CCPAG_CLIENT_ID'),
'client_secret': os.getenv('CCPAG_CLIENT_SECRET'),
'nome': 'James Kirk',
'cpf': '12345678901',
'valor': 100.00,
'descricao': 'Service payment',
'urlnoty': 'https://yoursite.com/webhook.py',
}
response = requests.post(url, data=payload)
data = response.json()
if response.status_code == 200 and 'qrcode' in data:
print(f"QR Code: {data['qrcode']}")
print(f"Transaction ID: {data['transactionId']}")
else:
print(f"Error: {data.get('message', 'Unknown')}")
require 'net/http'
require 'json'
uri = URI('https://api.ccpaglobal.com/v2/pix/qrcode.php')
params = {
client_id: ENV['CCPAG_CLIENT_ID'],
client_secret: ENV['CCPAG_CLIENT_SECRET'],
nome: 'James Kirk',
cpf: '12345678901',
valor: 100.00,
descricao: 'Service payment',
urlnoty: 'https://yoursite.com/webhook.rb',
}
response = Net::HTTP.post_form(uri, params)
data = JSON.parse(response.body)
if response.code == '200' && data['qrcode']
puts "QR Code: #{data['qrcode']}"
puts "Transaction ID: #{data['transactionId']}"
else
puts "Error: #{data['message'] || 'Unknown'}"
end
const axios = require('axios');
const payload = {
client_id: process.env.CCPAG_CLIENT_ID,
client_secret: process.env.CCPAG_CLIENT_SECRET,
nome: 'James Kirk',
cpf: '12345678901',
valor: 100.00,
descricao: 'Service payment',
urlnoty: 'https://yoursite.com/webhook.js',
};
axios.post('https://api.ccpaglobal.com/v2/pix/qrcode.php', payload)
.then(({ data }) => {
console.log(`QR Code: ${data.qrcode}`);
console.log(`Transaction ID: ${data.transactionId}`);
})
.catch(({ response }) => {
console.error(`Error: ${response?.data?.message ?? 'Unknown'}`);
});
Próximos Passos
- Gerar QR Code PIX — crie cobranças por QR Code
- Transferência PIX — envie pagamentos
- Status da Transação — consulte o estado de qualquer transação
- Webhooks — configure notificações automáticas
Respostas HTTP
A API usa códigos de status HTTP padrão para indicar sucesso ou falha de cada requisição.
Sucesso
| Código | Descrição |
|---|---|
200 | OK — requisição processada com sucesso |
201 | Created — recurso criado com sucesso |
Erros
| Código | Descrição |
|---|---|
400 | Bad Request — parâmetros inválidos ou ausentes |
401 | Unauthorized — credenciais inválidas |
403 | Forbidden — IP não autorizado ou acesso negado |
404 | Not Found — recurso não encontrado |
422 | Unprocessable — saldo insuficiente |
500 | Internal Server Error — erro interno do servidor |
Exemplo de Resposta de Erro
{
"statusCode": 400,
"message": "Invalid CPF or missing required parameters",
"errors": [
"Field 'valor' is required",
"CPF must contain digits only"
]
}
Credenciais de Acesso
Gerencie suas chaves de API no painel CC PAG Global.
Nunca exponha o client_secret em código client-side — JavaScript do navegador, apps mobile, etc. Use exclusivamente em requisições server-side.
Obtendo Credenciais
- Acesse ccpaglobal.com/keys
- Copie seu
client_ideclient_secret - Armazene em variáveis de ambiente — nunca em código-fonte
- Passe as credenciais em cada requisição à API
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
client_id | string | Identificador único do cliente |
client_secret | string | Chave secreta — mantenha privada |
Gerar QR Code
Cria um QR Code PIX para recebimento de pagamentos (cash-in).
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
client_id | string | Seu client ID (obrigatório) |
client_secret | string | Sua chave secreta (obrigatório) |
nome | string | Nome completo do pagador (obrigatório) |
cpf | string | CPF do pagador — apenas dígitos (obrigatório) |
valor | float | Valor em reais — formato decimal (obrigatório) |
descricao | string | Descrição do pagamento (obrigatório) |
urlnoty | string | URL de webhook para notificação (opcional) |
Exemplo de Requisição
$ch = curl_init('https://api.ccpaglobal.com/v2/pix/qrcode.php');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'client_id' => getenv('CCPAG_CLIENT_ID'),
'client_secret' => getenv('CCPAG_CLIENT_SECRET'),
'nome' => 'Ellen Ripley',
'cpf' => '98765432100',
'valor' => 299.90,
'descricao' => 'Premium plan — Order #4821',
'urlnoty' => 'https://yoursite.com/webhook/ccpag',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
if (isset($data['qrcode'])) {
echo "QR Code: " . $data['qrcode'] . PHP_EOL;
echo "Transaction ID: " . $data['transactionId'] . PHP_EOL;
} else {
echo "Error: " . ($data['message'] ?? 'Unknown');
}
import os, requests
payload = {
'client_id': os.getenv('CCPAG_CLIENT_ID'),
'client_secret': os.getenv('CCPAG_CLIENT_SECRET'),
'nome': 'Ellen Ripley',
'cpf': '98765432100',
'valor': 299.90,
'descricao': 'Premium plan — Order #4821',
'urlnoty': 'https://yoursite.com/webhook/ccpag',
}
r = requests.post('https://api.ccpaglobal.com/v2/pix/qrcode.php', data=payload)
data = r.json()
if r.status_code == 200 and 'qrcode' in data:
print(f"QR Code: {data['qrcode']}")
print(f"Transaction ID: {data['transactionId']}")
else:
print(f"Error: {data.get('message', 'Unknown')}")
curl -X POST https://api.ccpaglobal.com/v2/pix/qrcode.php \ -d "client_id=$CCPAG_CLIENT_ID" \ -d "client_secret=$CCPAG_CLIENT_SECRET" \ -d "nome=Ellen Ripley" \ -d "cpf=98765432100" \ -d "valor=299.90" \ -d "descricao=Premium plan — Order #4821" \ -d "urlnoty=https://yoursite.com/webhook/ccpag"
Resposta de Sucesso
{
"statusCode": 200,
"message": "QR Code generated successfully",
"qrcode": "00020126850014br.gov.bcb.pix...",
"transactionId": "4392d1d7e408d3cec04fm1zf3gv7vkq1",
"amount": 299.90,
"reference_code": "4392d1d7e408d3cec04fm1zf3gv7vkq1",
"gateway": "ccpaglobal"
}
Use o transactionId retornado para consultar o status do pagamento em Status da Transação.
Transferência PIX
Realiza transferências PIX para chaves de terceiros (cash-out).
Para realizar transferências via API, o IP do servidor deve estar na whitelist. Descubra seu IP em ccpaglobal.com/meuip e cadastre em ccpaglobal.com/keys.
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
client_id | string | Seu client ID (obrigatório) |
client_secret | string | Sua chave secreta (obrigatório) |
nome | string | Nome do beneficiário (obrigatório) |
cpf | string | CPF do beneficiário — apenas dígitos (obrigatório) |
valor | float | Valor da transferência em reais (obrigatório) |
chave_pix | string | Chave PIX do destinatário (obrigatório) |
descricao | string | Descrição da transferência (opcional) |
urlnoty | string | URL de webhook (opcional) |
Resposta de Sucesso
{
"statusCode": 200,
"message": "Payment processed successfully",
"transactionId": "e7f8a9b3c4d5e6f7g8h9i0j1k2l3m4n5"
}
Alguns pagamentos retornam status: "PENDING". Use o endpoint de Status para confirmar a liquidação.
Status da Transação
Consulta o estado atual de qualquer transação — depósito ou transferência.
Ideal para polling ou validação manual. Recomendamos intervalo de 5–10 segundos entre consultas.
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
client_id | string | Seu client ID (obrigatório) |
client_secret | string | Sua chave secreta (obrigatório) |
transaction_id | string | ID retornado ao criar QRCode ou pagamento * |
reference_code | string | Código de referência alternativo * |
* Informe ao menos um dos dois.
Exemplo de Requisição
$txId = '0eaf56ba401c9bfa5d61mkm3ch551oyt';
$url = 'https://api.ccpaglobal.com/v2/pix/status.php?' . http_build_query([
'client_id' => getenv('CCPAG_CLIENT_ID'),
'client_secret' => getenv('CCPAG_CLIENT_SECRET'),
'transaction_id' => $txId,
]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "Status: " . $data['transaction']['status'];
if ($data['transaction']['status'] === 'PAID') {
echo " — Paid at: " . $data['transaction']['paid_at'];
}
import os, requests
r = requests.get('https://api.ccpaglobal.com/v2/pix/status.php', params={
'client_id': os.getenv('CCPAG_CLIENT_ID'),
'client_secret': os.getenv('CCPAG_CLIENT_SECRET'),
'transaction_id': '0eaf56ba401c9bfa5d61mkm3ch551oyt',
})
tx = r.json()['transaction']
print(f"Status: {tx['status']}")
if tx['status'] == 'PAID':
print(f"Paid at: {tx['paid_at']}")
curl "https://api.ccpaglobal.com/v2/pix/status.php\ ?client_id=$CCPAG_CLIENT_ID\ &client_secret=$CCPAG_CLIENT_SECRET\ &transaction_id=0eaf56ba401c9bfa5d61mkm3ch551oyt"
Resposta — PAID
{
"statusCode": 200,
"transaction": {
"transactionId": "e7f8a9b3c4d5",
"status": "PAID",
"type": "DEPOSIT",
"amount": 299.90,
"tax": 1.50,
"nome": "Ellen Ripley",
"document": "98765432100",
"paid_at": "2026-06-04 14:31:07"
},
"gateway": "ccpaglobal"
}
Status Possíveis
| Status | Descrição |
|---|---|
PENDING | Aguardando confirmação |
PAID | Confirmado e processado |
FAILED | Falhou no processamento |
CANCELLED | Cancelado |
Consultar Saldo
Retorna o saldo disponível e bloqueado da sua conta em tempo real.
Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
client_id | string | Sim | ID do cliente |
client_secret | string | Sim | Chave secreta do cliente |
Exemplo
$url = 'https://api.ccpaglobal.com/v2/account/balance.php?' . http_build_query([
'client_id' => getenv('CCPAG_CLIENT_ID'),
'client_secret' => getenv('CCPAG_CLIENT_SECRET'),
]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "Available: R$ " . $data['balance']['available'];
import os, requests
r = requests.get('https://api.ccpaglobal.com/v2/account/balance.php', params={
'client_id': os.getenv('CCPAG_CLIENT_ID'),
'client_secret': os.getenv('CCPAG_CLIENT_SECRET'),
})
data = r.json()
print(f"Available: R$ {data['balance']['available']}")
curl "https://api.ccpaglobal.com/v2/account/balance.php\ ?client_id=$CCPAG_CLIENT_ID&client_secret=$CCPAG_CLIENT_SECRET"
const axios = require('axios');
axios.get('https://api.ccpaglobal.com/v2/account/balance.php', {
params: {
client_id: process.env.CCPAG_CLIENT_ID,
client_secret: process.env.CCPAG_CLIENT_SECRET,
}
}).then(({ data }) => {
console.log(`Available: R$ ${data.balance.available}`);
});
Resposta
{
"statusCode": 200,
"balance": {
"available": 4820.50,
"blocked": 0.00,
"total": 4820.50
},
"user": {
"username": "acme_corp",
"name": "Acme Corp LTDA"
}
}
Evento de Pagamento
Webhook enviado automaticamente quando um PIX é recebido e confirmado.
Seu endpoint deve retornar HTTP 200 para confirmar o recebimento. Qualquer outro código faz a API reenviar a notificação.
Payload
{
"transactionType": "RECEIVEPIX",
"transactionId": "a502e53d7e7d7c8afd0fmenrr80g57h0",
"amount": 299.90,
"status": "PAID",
"document": "98765432100",
"nome": "Ellen Ripley"
}
Processamento
<?php
$data = json_decode(file_get_contents('php://input'), true);
file_put_contents('webhook.log',
date('Y-m-d H:i:s') . ' ' . json_encode($data) . PHP_EOL,
FILE_APPEND
);
if ($data['transactionType'] === 'RECEIVEPIX' && $data['status'] === 'PAID') {
releaseProduct($data['transactionId'], $data['amount']);
http_response_code(200);
echo 'OK';
} else {
http_response_code(200);
echo 'Received';
}
?>
from flask import Flask, request
import json
from datetime import datetime
app = Flask(__name__)
@app.route('/webhook/ccpag', methods=['POST'])
def webhook():
data = request.get_json()
if not data:
return 'Invalid JSON', 400
with open('webhook.log', 'a') as f:
f.write(f"{datetime.now()} — {json.dumps(data)}\n")
if data.get('transactionType') == 'RECEIVEPIX' and data.get('status') == 'PAID':
release_product(data['transactionId'], data['amount'])
return 'OK', 200
const express = require('express');
const fs = require('fs');
const app = express();
app.use(express.json());
app.post('/webhook/ccpag', (req, res) => {
const data = req.body;
fs.appendFileSync('webhook.log',
`${new Date().toISOString()} — ${JSON.stringify(data)}\n`
);
if (data.transactionType === 'RECEIVEPIX' && data.status === 'PAID') {
releaseProduct(data.transactionId, data.amount);
}
res.status(200).send('OK');
});
app.listen(3000);
Evento de Transferência
Webhook enviado quando uma transferência PIX é processada.
Payload
{
"transactionType": "PAYMENT",
"transactionId": "798176179",
"amount": 850.00,
"paymentType": "PIX",
"dateApproval": "2026-06-04 14:31:07",
"statusCode": {
"statusId": 1,
"description": "Transfer completed successfully"
}
}
Status Codes
| statusId | Descrição |
|---|---|
1 | Transferência concluída |
2 | Transferência em processamento |
3 | Transferência falhou |
Assinatura de Webhook HMAC-SHA256
Valide a autenticidade de cada webhook usando assinatura criptográfica.
Se não ativado no painel, os webhooks chegam sem o header de assinatura — nenhuma integração existente é afetada.
Como Funciona
- Acesse ccpaglobal.com/keys → Ativar Assinatura de Webhook
- Confirme com seu PIN e copie o
webhook_secret— exibido uma única vez - Todo webhook passará a incluir o header:
X-CCPAG-Signature: sha256=b94d27b9934d3e08a52e52d7da7dabfac484efe04b959a508a20e1aa9e8e5fa3
Validação
Recalcule a assinatura com HMAC-SHA256 usando o corpo bruto do request e compare com o header. Use comparação segura para evitar timing attacks.
<?php
$secret = getenv('CCPAG_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_CCPAG_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $header)) {
http_response_code(401);
exit('Invalid signature');
}
$data = json_decode($body, true);
if ($data['transactionType'] === 'RECEIVEPIX' && $data['status'] === 'PAID') {
releaseProduct($data['transactionId'], $data['amount']);
}
http_response_code(200);
echo 'OK';
import hmac, hashlib, os
from flask import Flask, request, abort
app = Flask(__name__)
WEBHOOK_SECRET = os.getenv('CCPAG_WEBHOOK_SECRET')
@app.route('/webhook', methods=['POST'])
def webhook():
body = request.get_data()
sig = request.headers.get('X-CCPAG-Signature', '')
expected = 'sha256=' + hmac.new(
WEBHOOK_SECRET.encode(), body, hashlib.sha256
).hexdigest()
if not hmac.compare_digest(expected, sig):
abort(401, 'Invalid signature')
data = request.get_json()
if data.get('transactionType') == 'RECEIVEPIX' and data.get('status') == 'PAID':
release_product(data['transactionId'], data['amount'])
return 'OK', 200
const express = require('express');
const crypto = require('crypto');
const app = express();
const SECRET = process.env.CCPAG_WEBHOOK_SECRET;
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const sig = req.headers['x-ccpag-signature'] || '';
const expected = 'sha256=' + crypto
.createHmac('sha256', SECRET)
.update(req.body)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
return res.status(401).send('Invalid signature');
}
const data = JSON.parse(req.body);
if (data.transactionType === 'RECEIVEPIX' && data.status === 'PAID') {
releaseProduct(data.transactionId, data.amount);
}
res.status(200).send('OK');
});
app.listen(3000);
Use sempre o corpo bruto do request para calcular a assinatura — nunca o JSON já parseado. Qualquer diferença de ordem ou espaçamento invalida a assinatura.
Comportamento sem HMAC
| Situação | Header presente? | Ação recomendada |
|---|---|---|
| HMAC ativado | Sim | Validar assinatura antes de processar |
| HMAC não configurado | Não | Processar normalmente (comportamento legado) |