CertoPay Brasil - API de Pagamentos
Integre pagamentos com cartão de crédito, PIX, boleto, checkout, saldo, relatórios financeiros, subcontas, webhooks e recursos antifraude em uma única documentação técnica.
Visão geral
A API da CertoPay Brasil permite criar cobranças, consultar transações, acompanhar saldos, emitir relatórios financeiros e automatizar eventos por webhook.
Base URL
Use o domínio abaixo como referência para chamadas em produção.
https://api.certopaybrasil.com
Formato
Todas as respostas seguem o padrão JSON. Para requisições de criação, envie o corpo em JSON.
- Encoding: UTF-8
- Timezone recomendado: America/Sao_Paulo
- Valores monetários em centavos
Ambientes
Separe tokens de produção e testes para evitar cobranças reais durante homologação.
- Sandbox:
https://sandbox-api.certopaybrasil.com - Produção:
https://api.certopaybrasil.com
api.cloud.certopaybrasil.com ou outro subdomínio interno.
Autenticação
Todas as requisições devem enviar o token da conta. Por compatibilidade com integrações simples, o token pode ser enviado como query parameter api_token.
Query parameter
GET /public/v1/balance?api_token=YOUR_API_TOKEN
Header opcional
Authorization: Bearer YOUR_API_TOKEN
Headers requeridos
Envie os headers abaixo para garantir que a API interprete corretamente sua requisição.
| Header | Obrigatório | Quando usar |
|---|---|---|
Accept: application/json |
Sim | Em todas as requisições. |
Content-Type: application/json |
Sim | Em requisições POST, PUT e PATCH. |
Idempotency-Key: UUID |
Recomendado | Para evitar cobrança duplicada em reenvios de transação. |
Status de pagamento
Lista dos principais status que uma transação pode assumir durante o processamento.
Pagamento aprovado e processado.
Transação em processamento.
Aguardando confirmação do pagamento.
Em análise antifraude, normalmente em cartão.
Documentos recebidos para análise MED, normalmente em PIX.
Em análise manual de MED, normalmente em PIX.
Pagamento recusado pela adquirente, banco ou regra de risco.
Falha no processamento da transação.
Reprovado na análise MED.
Transação cancelada antes da confirmação.
Pagamento estornado total ou parcialmente.
Contestação confirmada, normalmente em cartão.
Pré-contestação recebida, normalmente em cartão.
Transações
Crie cobranças, consulte transações existentes e solicite estornos.
curl -X POST "https://api.certopaybrasil.com/public/v1/transactions?api_token=YOUR_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 63f2a42a-0fc3-4bc1-bad5-80db9105a88a" \
-d '{
"method": "credit_card",
"amount": 10990,
"installments": 1,
"comment": "Pedido #1001",
"expires_at": "2026-05-20T23:59:59-03:00",
"customer": {
"name": "Maria Oliveira",
"email": "maria@example.com",
"phone": "88999990000",
"document": "12345678909",
"ip": "177.10.10.10"
},
"products": [
{
"name": "Produto exemplo",
"quantity": 1,
"unit_price": 10990,
"sku": "SKU-001",
"link": "https://certopaybrasil.com/produto-exemplo"
}
]
}'
const response = await fetch(
"https://api.certopaybrasil.com/public/v1/transactions?api_token=YOUR_API_TOKEN",
{
method: "POST",
headers: {
"Accept": "application/json",
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID()
},
body: JSON.stringify({
method: "pix",
amount: 10990,
comment: "Pedido #1001",
customer: {
name: "Maria Oliveira",
email: "maria@example.com",
phone: "88999990000",
document: "12345678909",
ip: "177.10.10.10"
},
products: [
{
name: "Produto exemplo",
quantity: 1,
unit_price: 10990,
sku: "SKU-001"
}
]
})
}
);
const data = await response.json();
console.log(data);
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
$response = Http::acceptJson()
->withHeaders([
'Content-Type' => 'application/json',
'Idempotency-Key' => (string) Str::uuid(),
])
->post('https://api.certopaybrasil.com/public/v1/transactions', [
'api_token' => env('CERTOPAY_API_TOKEN'),
'method' => 'pix',
'amount' => 10990,
'comment' => 'Pedido #1001',
'customer' => [
'name' => 'Maria Oliveira',
'email' => 'maria@example.com',
'phone' => '88999990000',
'document' => '12345678909',
'ip' => request()->ip(),
],
'products' => [
[
'name' => 'Produto exemplo',
'quantity' => 1,
'unit_price' => 10990,
'sku' => 'SKU-001',
],
],
]);
$data = $response->json();
POST
/public/v1/transactions
Criar uma nova transação
Cobrança
/public/v1/transactions
Criar uma nova transação
| Campo | Tipo | Descrição |
|---|---|---|
method |
string | credit_card, pix ou billet. |
amount |
integer | Valor em centavos. Exemplo: R$ 109,90 = 10990. |
installments |
integer | Quantidade de parcelas, quando cartão. |
customer |
object | Dados do comprador. |
products |
array | Lista de produtos do pedido. |
metadata |
object | Dados livres para conciliação, como order_id e origem. |
{
"success": true,
"data": {
"hash": "tr_9dd4b64a8f",
"status": "pending",
"method": "pix",
"amount": 10990,
"checkout_url": "https://pay.certopaybrasil.com/checkout/tr_9dd4b64a8f",
"pix": {
"qr_code": "000201010212...",
"qr_code_url": "https://pay.certopaybrasil.com/qrcode/tr_9dd4b64a8f"
},
"created_at": "2026-05-20T14:20:00-03:00"
}
}
GET
/public/v1/transactions/{hash}
Consultar uma transação pelo hash
Consulta
/public/v1/transactions/{hash}
Consultar uma transação pelo hash
curl -X GET "https://api.certopaybrasil.com/public/v1/transactions/tr_9dd4b64a8f?api_token=YOUR_API_TOKEN" \
-H "Accept: application/json"
POST
/public/v1/transactions/{hash}/refund
Solicitar estorno total ou parcial
Estorno
/public/v1/transactions/{hash}/refund
Solicitar estorno total ou parcial
| Campo | Tipo | Descrição |
|---|---|---|
amount |
integer | Opcional. Valor em centavos para estorno parcial. Se omitido, estorno total. |
reason |
string | Motivo interno do estorno. |
PIX
Crie cobranças PIX, obtenha QR Code e acompanhe confirmação por consulta ou webhook.
POST
/public/v1/transactions
Criar cobrança PIX
method: pix
/public/v1/transactions
Criar cobrança PIX
{
"method": "pix",
"amount": 5990,
"comment": "Pedido PIX #1002",
"expires_at": "2026-05-20T23:59:59-03:00",
"customer": {
"name": "João Santos",
"email": "joao@example.com",
"phone": "88988887777",
"document": "12345678909"
},
"metadata": {
"order_id": "1002",
"source": "shopify"
}
}
Campos PIX retornados
pix.qr_code: código copia e cola.pix.qr_code_url: imagem/URL do QR Code.expires_at: data limite de pagamento.status: normalmente inicia comopending.
Saldo
Consulte o saldo disponível, saldo futuro, reserva e valores em processamento.
GET
/public/v1/balance
Consultar saldo da conta
Conta
/public/v1/balance
Consultar saldo da conta
{
"success": true,
"data": {
"available": 125900,
"pending": 35600,
"reserved": 10000,
"currency": "BRL",
"updated_at": "2026-05-20T15:00:00-03:00"
}
}
Financeiro
Liste movimentações financeiras por período para conciliação, repasses, taxas e reservas.
GET
/public/v1/financials
Listar movimentações financeiras
Conciliação
/public/v1/financials
Listar movimentações financeiras
| Parâmetro | Tipo | Descrição |
|---|---|---|
start_at |
date | Data inicial no formato YYYY-MM-DD. |
end_at |
date | Data final no formato YYYY-MM-DD. |
type |
string | Opcional. Ex.: sale, refund, reserve, withdraw. |
curl -X GET "https://api.certopaybrasil.com/public/v1/financials?api_token=YOUR_API_TOKEN&start_at=2026-05-01&end_at=2026-05-20" \
-H "Accept: application/json"
Antifraude
Consulte análises, envie informações complementares e acompanhe decisões de risco.
GET
/public/v1/antifraud/{transaction_hash}
Consultar análise antifraude
Cartão
/public/v1/antifraud/{transaction_hash}
Consultar análise antifraude
{
"success": true,
"data": {
"transaction_hash": "tr_9dd4b64a8f",
"status": "approved",
"score": 82,
"decision": "approve",
"reason": null
}
}
Subcontas
Crie e consulte subcontas para operações com split, whitelabel, marketplace e reservas financeiras.
POST
/public/v1/subaccounts
Criar subconta
KYC
/public/v1/subaccounts
Criar subconta
| Campo | Tipo | Descrição |
|---|---|---|
name |
string | Nome comercial da subconta. |
document |
string | CPF ou CNPJ. |
email |
string | E-mail responsável. |
bank_account |
object | Dados bancários para liquidação. |
{
"name": "Loja Exemplo LTDA",
"document": "12345678000190",
"email": "financeiro@lojaexemplo.com",
"phone": "88999990000",
"bank_account": {
"bank_code": "001",
"agency": "1234",
"agency_digit": "0",
"account": "123456",
"account_digit": "7",
"type": "checking"
}
}
GET
/public/v1/subaccounts
Listar subcontas
Listagem
/public/v1/subaccounts
Listar subcontas
Retorna subcontas vinculadas ao token autenticado, com paginação e filtros por documento, status e data.
Webhooks
Configure uma URL para receber eventos assíncronos da CertoPay Brasil.
Eventos disponíveis
transaction.createdtransaction.paidtransaction.refusedtransaction.refundedtransaction.chargebackpix.med_receivedwithdraw.paid
{
"event": "transaction.paid",
"created_at": "2026-05-20T15:25:00-03:00",
"data": {
"hash": "tr_9dd4b64a8f",
"status": "paid",
"amount": 10990,
"method": "pix",
"paid_at": "2026-05-20T15:24:58-03:00",
"metadata": {
"order_id": "1002",
"source": "shopify"
}
}
}
Erros
Os erros seguem uma estrutura simples para facilitar tratamento no front-end, back-end e integrações.
| Status | Descrição |
|---|---|
400 |
Payload inválido ou parâmetro ausente. |
401 |
Token ausente ou inválido. |
403 |
Conta sem permissão para o recurso. |
404 |
Recurso não encontrado. |
422 |
Erro de validação dos dados enviados. |
429 |
Limite de requisições excedido. |
500 |
Erro interno inesperado. |
{
"success": false,
"message": "Validation failed",
"errors": {
"amount": [
"O valor deve ser maior que zero."
],
"customer.email": [
"Informe um e-mail válido."
]
}
}