Documentação da API

A API do CorePag é REST, fala JSON e trabalha sempre com valores em centavos. Com ela você gera cobranças PIX, consulta o status e movimenta saldo (saques e transferências).

Comece em 3 passos: 1) pegue sua chave de API no painel · 2) gere uma cobrança PIX · 3) receba a confirmação por webhook ou consulta.

O formato de resposta espelha o padrão de mercado: um envelope { status, message, data }. Datas em ISO-8601 (UTC), identificadores como strings.

Autenticação

Toda chamada à API do lojista é autenticada por chave de API no header x-api-key. O header User-Agent é obrigatório (identifique sua integração).

Headers

x-api-key: cpag_live_sua_chave_aqui
User-Agent: MinhaLoja/1.0
Content-Type: application/json

Situação da conta	Pode gerar cobrança?	Pode sacar?
`PENDING` (em análise)	Sim	Não
`APPROVED`	Sim	Sim
`BLOCKED` / `REJECTED`	Não (401)	Não

Segurança: a chave só aparece uma vez, na criação/regeneração. Guarde-a em ambiente seguro (nunca no front-end). Você pode restringir a chave por lista de IPs no painel. Se vazar, regenere — a antiga é revogada na hora.

Ambiente & URL base

BASEhttps://api.corepag.com.br/api

Todos os caminhos desta página são relativos a essa base. Ex.: POST /transactions → https://api.corepag.com.br/api/transactions.

Valores & idempotência

Valores em centavos

Todo valor monetário é um inteiro em centavos. R$ 129,90 = 12990. Nunca envie casa decimal.

Idempotência

Para evitar cobranças duplicadas em caso de retry de rede, envie um externalRef único (ou o header Idempotency-Key). Se a mesma referência chegar de novo, a cobrança original é retornada — não é criada outra.

Header opcional

Idempotency-Key: 3f8a1c22-9b0e-4e7a-9a1e-2b0c9d1e4f55

Criar cobrança PIX

POST/transactions

Cria uma cobrança PIX e devolve o copia-e-cola (payload EMV) para o pagador. A cobrança nasce em WAITING_PAYMENT.

Corpo da requisição

Campo	Tipo		Descrição
`amount`	integer	obrig.	Valor total em centavos (> 0).
`paymentMethod`	string	obrig.	Sempre `"PIX"`.
`customer.name`	string	obrig.	Nome do pagador.
`customer.email`	string	obrig.	E-mail do pagador.
`customer.phone`	string	opcional	Telefone.
`customer.document.type`	string	obrig.	`"CPF"` ou `"CNPJ"`.
`customer.document.number`	string	obrig.	Documento do pagador.
`items[]`	array	opcional	Itens do pedido: `title`, `unitPrice` (centavos), `quantity`, `tangible?`, `externalRef?`.
`pix.expiresInDays`	integer	opcional	Validade da cobrança em dias.
`postbackUrl`	string	opcional	URL que recebe o webhook desta cobrança.
`externalRef`	string	opcional	Sua referência (chave de idempotência).
`metadata`	object	opcional	Objeto livre devolvido de volta pra você.

cURL

curl -X POST https://api.corepag.com.br/api/transactions \
  -H "x-api-key: cpag_live_sua_chave" \
  -H "User-Agent: MinhaLoja/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12990,
    "paymentMethod": "PIX",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@email.com",
      "phone": "(11) 98888-7777",
      "document": { "type": "CPF", "number": "390.533.447-05" }
    },
    "items": [{ "title": "Plano Pro", "unitPrice": 12990, "quantity": 1 }],
    "externalRef": "pedido-1042"
  }'

Resposta 200

JSON

{
  "status": 200,
  "message": "Transação criada",
  "data": {
    "id": "9b1e...c4",
    "amount": 12990,
    "paymentMethod": "PIX",
    "status": "WAITING_PAYMENT",
    "qrCode": "00020126850014br.gov.bcb.pix...6304ABCD",
    "pix": {
      "qrcode": "00020126850014br.gov.bcb.pix...6304ABCD",
      "expirationDate": "2026-07-14T13:00:00.000Z",
      "qrCodeImageUrl": null
    },
    "fee": {
      "spreadPercentage": 6.99,
      "fixedAmount": 199,
      "estimatedFee": 1106,
      "netAmount": 11884
    },
    "providerTxId": "DQwLAd52jlRW",
    "createdAt": "2026-07-13T13:00:00.000Z"
  }
}

Use data.pix.qrcode (ou data.qrCode) como o copia-e-cola exibido ao cliente. O campo fee mostra a taxa estimada e o líquido que cai pra você.

Consultar transação

GET/transactions/:id

GET/transactions/:id/summary

Enquanto o webhook não chega (ou como reconciliação), consulte o status. O /summary devolve o essencial.

cURL

curl https://api.corepag.com.br/api/transactions/9b1e...c4/summary \
  -H "x-api-key: cpag_live_sua_chave" \
  -H "User-Agent: MinhaLoja/1.0"

JSON

{
  "id": "9b1e...c4",
  "amount": 12990,
  "status": "PAID",
  "paymentMethod": "PIX",
  "paidAt": "2026-07-13T13:04:22.000Z",
  "createdAt": "2026-07-13T13:00:00.000Z"
}

Boa prática: não fique consultando em loop apertado. Prefira o webhook e use a consulta como fallback (ex.: a cada 30s até expirar).

Ciclo de vida da transação

Status	Significado
`WAITING_PAYMENT`	Cobrança criada, aguardando o pagamento.
`PAID`	Pagamento confirmado. O valor entra no seu saldo pending e é liberado em D+X.
`REFUSED`	Recusada / expirada / cancelada.
`REFUNDED`	Estornada.
`CHARGEBACK`	Contestada (MED).

O saldo tem três baldes: available (disponível pra saque), pending (pago, aguardando liberação D+X) e reserved (reserva de risco).

Webhooks

Ao mudar o status de uma cobrança, o CorePag faz um POST na sua postbackUrl (ou nos webhooks cadastrados no painel) com o corpo JSON do evento e uma assinatura no header.

POSTsua-url-de-postback

Assinatura

Cada entrega vem com o header X-CorePag-Signature no formato t=<unix>,v1=<hmac>. O v1 é um HMAC-SHA256, com o seu segredo de webhook, sobre a string <t>.<corpo-cru>.

Header

X-CorePag-Signature: t=1783960000,v1=7b2d...e9f1

Node.js — verificação

import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const t = Number(parts.t);
  // anti-replay: rejeite entregas com mais de 5 min
  if (!Number.isFinite(t) || Math.abs(Date.now()/1000 - t) > 300) return false;
  const expected = crypto.createHmac('sha256', secret)
    .update(`${t}.${rawBody}`).digest();
  const got = Buffer.from(parts.v1, 'hex');
  return got.length === expected.length &&
    crypto.timingSafeEqual(got, expected);
}

Verifique sobre o corpo CRU (os bytes exatos recebidos), antes de qualquer JSON.parse — reserializar muda a assinatura. Responda 2xx pra confirmar; em erro, reenviamos com backoff (1min, 5min, 30min, 2h — até 5 tentativas).

Saque PIX (cashout)

POST/cashout

Envia um PIX do seu saldo disponível para uma chave. Requer conta APPROVED. O débito é feito antes de chamar o PSP e estornado automaticamente se falhar.

Campo	Tipo		Descrição
`amount`	integer	obrig.	Centavos (> 0).
`pixKey`	string	obrig.	Chave PIX de destino.
`pixType`	string	obrig.	`CPF`, `CNPJ`, `EMAIL`, `PHONE` ou `RANDOM`.
`beneficiaryName`	string	obrig.	Nome do recebedor.
`beneficiaryDocument`	string	obrig.	CPF/CNPJ do recebedor.
`description`	string	obrig.	Descrição do saque.
`postbackUrl`	string	opcional	URL de notificação.
`externalRef`	string	opcional	Sua referência.

cURL

curl -X POST https://api.corepag.com.br/api/cashout \
  -H "x-api-key: cpag_live_sua_chave" \
  -H "User-Agent: MinhaLoja/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "pixKey": "maria@email.com",
    "pixType": "EMAIL",
    "beneficiaryName": "Maria Souza",
    "beneficiaryDocument": "390.533.447-05",
    "description": "Repasse pedido 1042"
  }'

Status do saque: PENDING (em processamento) · PAID · FAILED (estornado ao seu saldo). Consulte com GET /cashout/:id e liste com GET /cashout.

Transferências

POST/transfers/fee— cotar taxa

POST/transfers— executar

Movimentação de saldo. Cote a taxa antes com /transfers/fee (não debita nada) e execute com /transfers.

POST /transfers/fee — resposta

{
  "status": 200,
  "message": "OK",
  "data": { "amount": 5000, "fee": 199, "fixedCents": 199, "spreadPct": 0, "total": 5199 }
}

Também disponíveis: GET /transfers, /transfers/:id e /transfers/summary.

Erros

Erros usam códigos HTTP padrão e trazem message no corpo.

HTTP	Quando
`400`	Corpo inválido (validação) ou saldo insuficiente no saque.
`401`	`x-api-key` ausente/inválida, `User-Agent` ausente, IP não autorizado ou conta bloqueada.
`404`	Transação/saque não encontrado (ou não é da sua conta).
`429`	Rate limit em rotas protegidas (a criação de cobrança não tem rate-limit).

Exemplo 401

{ "statusCode": 401, "message": "chave inválida" }

Todos os endpoints

Método	Rota	Descrição
POST	`/transactions`	Criar cobrança PIX
GET	`/transactions/:id`	Detalhe da transação
GET	`/transactions/:id/summary`	Resumo (status)
POST	`/cashout`	Saque PIX
GET	`/cashout`	Listar saques
GET	`/cashout/:id`	Detalhe do saque
POST	`/transfers/fee`	Cotar taxa de transferência
POST	`/transfers`	Criar transferência
GET	`/transfers`	Listar transferências
GET	`/transfers/:id`	Detalhe da transferência
GET	`/transfers/summary`	Resumo de transferências

Precisa de ajuda com a integração? Fale com o suporte do CorePag. Base da API: https://api.corepag.com.br/api.