Começando

Documentação completa da CC PAG Global API v2. Todos os endpoints, parâmetros e exemplos de integração.

Base URL

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:

exemplo_integracao
$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

Respostas HTTP

A API usa códigos de status HTTP padrão para indicar sucesso ou falha de cada requisição.

Sucesso

CódigoDescrição
200OK — requisição processada com sucesso
201Created — recurso criado com sucesso

Erros

CódigoDescrição
400Bad Request — parâmetros inválidos ou ausentes
401Unauthorized — credenciais inválidas
403Forbidden — IP não autorizado ou acesso negado
404Not Found — recurso não encontrado
422Unprocessable — saldo insuficiente
500Internal Server Error — erro interno do servidor

Exemplo de Resposta de Erro

400 bad_request
{
  "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.

Segurança crítica

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

  1. Acesse ccpaglobal.com/keys
  2. Copie seu client_id e client_secret
  3. Armazene em variáveis de ambiente — nunca em código-fonte
  4. Passe as credenciais em cada requisição à API

Parâmetros

ParâmetroTipoDescrição
client_idstringIdentificador único do cliente
client_secretstringChave secreta — mantenha privada

Gerar QR Code

Cria um QR Code PIX para recebimento de pagamentos (cash-in).

POST https://api.ccpaglobal.com/v2/pix/qrcode.php

Parâmetros

ParâmetroTipoDescrição
client_idstringSeu client ID (obrigatório)
client_secretstringSua chave secreta (obrigatório)
nomestringNome completo do pagador (obrigatório)
cpfstringCPF do pagador — apenas dígitos (obrigatório)
valorfloatValor em reais — formato decimal (obrigatório)
descricaostringDescrição do pagamento (obrigatório)
urlnotystringURL de webhook para notificação (opcional)

Exemplo de Requisição

gerar_qrcode
$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

200 OK
{
  "statusCode": 200,
  "message": "QR Code generated successfully",
  "qrcode": "00020126850014br.gov.bcb.pix...",
  "transactionId": "4392d1d7e408d3cec04fm1zf3gv7vkq1",
  "amount": 299.90,
  "reference_code": "4392d1d7e408d3cec04fm1zf3gv7vkq1",
  "gateway": "ccpaglobal"
}
Próximo passo

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).

Liberação de IP obrigatória

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.

POST https://api.ccpaglobal.com/v2/pix/payment.php

Parâmetros

ParâmetroTipoDescrição
client_idstringSeu client ID (obrigatório)
client_secretstringSua chave secreta (obrigatório)
nomestringNome do beneficiário (obrigatório)
cpfstringCPF do beneficiário — apenas dígitos (obrigatório)
valorfloatValor da transferência em reais (obrigatório)
chave_pixstringChave PIX do destinatário (obrigatório)
descricaostringDescrição da transferência (opcional)
urlnotystringURL de webhook (opcional)

Resposta de Sucesso

200 OK
{
  "statusCode": 200,
  "message": "Payment processed successfully",
  "transactionId": "e7f8a9b3c4d5e6f7g8h9i0j1k2l3m4n5"
}
Status PENDING

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.

GET https://api.ccpaglobal.com/v2/pix/status.php
Quando usar?

Ideal para polling ou validação manual. Recomendamos intervalo de 5–10 segundos entre consultas.

Parâmetros

ParâmetroTipoDescrição
client_idstringSeu client ID (obrigatório)
client_secretstringSua chave secreta (obrigatório)
transaction_idstringID retornado ao criar QRCode ou pagamento *
reference_codestringCódigo de referência alternativo *

* Informe ao menos um dos dois.

Exemplo de Requisição

consultar_status
$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

200 OK · status 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

StatusDescrição
PENDINGAguardando confirmação
PAIDConfirmado e processado
FAILEDFalhou no processamento
CANCELLEDCancelado

Consultar Saldo

Retorna o saldo disponível e bloqueado da sua conta em tempo real.

GET https://api.ccpaglobal.com/v2/account/balance.php

Parâmetros

ParâmetroTipoObrigatórioDescrição
client_idstringSimID do cliente
client_secretstringSimChave secreta do cliente

Exemplo

balance_request
$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

200 OK
{
  "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.

Importante

Seu endpoint deve retornar HTTP 200 para confirmar o recebimento. Qualquer outro código faz a API reenviar a notificação.

Payload

application/json
{
  "transactionType": "RECEIVEPIX",
  "transactionId": "a502e53d7e7d7c8afd0fmenrr80g57h0",
  "amount": 299.90,
  "status": "PAID",
  "document": "98765432100",
  "nome": "Ellen Ripley"
}

Processamento

webhook_handler
<?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

application/json
{
  "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

statusIdDescrição
1Transferência concluída
2Transferência em processamento
3Transferência falhou

Assinatura de Webhook HMAC-SHA256

Valide a autenticidade de cada webhook usando assinatura criptográfica.

Recurso opcional

Se não ativado no painel, os webhooks chegam sem o header de assinatura — nenhuma integração existente é afetada.

Como Funciona

  1. Acesse ccpaglobal.com/keysAtivar Assinatura de Webhook
  2. Confirme com seu PIN e copie o webhook_secret — exibido uma única vez
  3. Todo webhook passará a incluir o header:
Header enviado pela CC PAG Global
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.

validar_webhook_hmac
<?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);
Atenção

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çãoHeader presente?Ação recomendada
HMAC ativadoSimValidar assinatura antes de processar
HMAC não configuradoNãoProcessar normalmente (comportamento legado)