API v1 Gateway de Pagamentos
Base URL: api.certopaybrasil.com
CERTOPAY. FEITO PRO SEU NEGÓCIO DIGITAL

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.

Cartão, PIX e boleto Métodos de pagamento para e-commerce, SaaS e operações digitais.
Checkout próprio Use API, link de pagamento ou página dedicada com identidade da marca.
Webhook em tempo real Receba atualizações de transação, estorno, MED, chargeback e saque.

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.

REST + JSON

Base URL

Use o domínio abaixo como referência para chamadas em produção.

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
Observação: ajuste os domínios de API caso sua infraestrutura use outro host, por exemplo 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.

api_token

Query parameter

Exemplo
GET /public/v1/balance?api_token=YOUR_API_TOKEN

Header opcional

Bearer token
Authorization: Bearer YOUR_API_TOKEN

Headers requeridos

Envie os headers abaixo para garantir que a API interprete corretamente sua requisição.

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

Transaction.status
paid

Pagamento aprovado e processado.

processing

Transação em processamento.

pending

Aguardando confirmação do pagamento.

antifraud

Em análise antifraude, normalmente em cartão.

med_received

Documentos recebidos para análise MED, normalmente em PIX.

med_analysis

Em análise manual de MED, normalmente em PIX.

refused

Pagamento recusado pela adquirente, banco ou regra de risco.

failed

Falha no processamento da transação.

med_reproved

Reprovado na análise MED.

cancelled

Transação cancelada antes da confirmação.

refunded

Pagamento estornado total ou parcialmente.

chargeback

Contestação confirmada, normalmente em cartão.

pre_chargeback

Pré-contestação recebida, normalmente em cartão.

Transações

Crie cobranças, consulte transações existentes e solicite estornos.

Pagamentos
Criar pagamento com cartão
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"
      }
    ]
  }'
Fetch API
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);
Laravel HTTP Client
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
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.
Resposta 201
{
  "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
cURL
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
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.

Instantâneo
POST
/public/v1/transactions Criar cobrança PIX
method: pix
Payload
{
  "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 como pending.

Saldo

Consulte o saldo disponível, saldo futuro, reserva e valores em processamento.

Balance
GET
/public/v1/balance Consultar saldo da conta
Conta
Resposta 200
{
  "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.

Relatórios
GET
/public/v1/financials Listar movimentações financeiras
Conciliação
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
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.

Risk
GET
/public/v1/antifraud/{transaction_hash} Consultar análise antifraude
Cartão
Resposta 200
{
  "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.

Split
POST
/public/v1/subaccounts Criar subconta
KYC
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.
Payload
{
  "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

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

Eventos disponíveis

  • transaction.created
  • transaction.paid
  • transaction.refused
  • transaction.refunded
  • transaction.chargeback
  • pix.med_received
  • withdraw.paid
Exemplo de payload
{
  "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"
    }
  }
}
Segurança recomendada: valide assinatura do webhook usando um segredo compartilhado, registre logs de entrega e responda HTTP 2xx apenas após processar ou enfileirar o evento.

Erros

Os erros seguem uma estrutura simples para facilitar tratamento no front-end, back-end e integrações.

HTTP status
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.
Resposta de erro
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "amount": [
      "O valor deve ser maior que zero."
    ],
    "customer.email": [
      "Informe um e-mail válido."
    ]
  }
}
Copiado!