API v2

Documentação da API CertoPay

Integre pagamentos via PIX, Boleto e Cartão de Crédito na sua aplicação. Uma API REST simples, com autenticação por chave, webhooks e split de pagamentos.

Base URLhttps://v2.certopaybrasil.com/api

Primeiros passos

O fluxo de uma cobrança na CertoPay é sempre o mesmo, independentemente do método de pagamento. Estes são os quatro passos que sua integração precisa cobrir:

1Criar Customer
Cadastre o comprador com nome, e-mail e documento.
POST /api/customers
2Criar Order
Vincule o cliente a um valor a ser cobrado (em reais).
POST /api/orders
3Processar Pagamento
Chame o gateway com o orderId e o método (PIX, BOLETO ou CARD).
POST /api/payment-gateway/process
4Receber Webhook
Confirme o pagamento quando o evento transaction.paid chegar no seu endpoint.
POST https://seusite.com/webhooks/certopay

Ambiente de testes

Use uma X-Api-Key com prefixo sk_test_ para simular cobranças sem movimentar dinheiro. Para produção, use sk_live_.

1. Autenticação

A CertoPay suporta dois métodos de autenticação. Para integração server-to-server, recomendamos API Key.

1.1 API Key (recomendado)

Inclua o header em todas as requisições:

http

X-Api-Key: sk_live_sua_chave_aqui

Obter sua API Key (via painel Seller ou via API com JWT):

GET/api/api-keys/me

http

GET /api/api-keys/me
X-Api-Key: sk_live_sua_chave_aqui

Resposta:

json

{
  "id": "uuid",
  "label": "Chave principal",
  "keyPrefix": "sk_live_a1b2c3d4...",
  "maskedKey": "sk_live_a1b2c3d4...••••••••••",
  "active": true,
  "rateLimit": 100,
  "lastUsedAt": "2026-06-26T10:00:00Z",
  "createdAt": "2026-06-01T10:00:00Z"
}

Atenção

O valor completo da chave só é exibido no momento da criação. Salve-o imediatamente. Nunca exponha a chave no frontend ou em repositórios públicos.

Revogar e gerar nova chave:

POST/api/api-keys/me/regenerate

http

POST /api/api-keys/me/regenerate
X-Api-Key: sk_live_sua_chave_aqui

1.2 JWT (alternativa)

POST/api/auth/login

http

POST /api/auth/login
Content-Type: application/json

{
  "email": "seu@email.com",
  "password": "sua_senha"
}

Resposta:

json

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Use o token nas requisições:

http

Authorization: Bearer {accessToken}

Nota

Todas as rotas da API, incluindo Estabelecimentos (seção 9) e Split de Pagamentos (seção 10), aceitam tanto X-Api-Key quanto Bearer JWT — use o que for mais conveniente pra sua integração.

2. Clientes (Customers)

Antes de processar um pagamento, o comprador precisa estar cadastrado como Customer.

Criar cliente

POST/api/customers

http

POST /api/customers
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "name": "João da Silva",
  "email": "joao@email.com",
  "document": "12345678900",
  "phone": "(11) 99999-9999",
  "companyId": "uuid-do-estabelecimento"
}

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do cliente
`email`	string	Sim	E-mail do cliente
`document`	string	Sim	CPF/CNPJ, só números
`phone`	string	Não	Telefone
`companyId`	string	Sim	ID do Estabelecimento ao qual este cliente pertence — necessário para o split funcionar corretamente, é o mesmo `id` retornado na criação do Estabelecimento.

Listar clientes

GET/api/customers

http

GET /api/customers
X-Api-Key: sk_live_sua_chave_aqui

Buscar cliente por ID

GET/api/customers/{id}

http

GET /api/customers/{id}
X-Api-Key: sk_live_sua_chave_aqui

Atualizar cliente

PATCH/api/customers/{id}

http

PATCH /api/customers/{id}
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "phone": "(11) 88888-8888"
}

Remover cliente

DELETE/api/customers/{id}

http

DELETE /api/customers/{id}
X-Api-Key: sk_live_sua_chave_aqui

3. Pedidos (Orders)

O pedido vincula um cliente a um valor e gera o registro que será cobrado.

Criar pedido

POST/api/orders

http

POST /api/orders
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "customerId": "uuid-do-customer",
  "amount": 297.00,
  "productName": "Nome do produto vendido",
  "productSku": "SKU-INTERNO-123"
}

Campo	Tipo	Obrigatório	Descrição
`customerId`	string	Sim	ID do cliente criado em /api/customers
`amount`	number	Sim	Valor em reais (ex: `297.00` = R$297,00), mínimo `0.01`
`productName`	string	Recomendado	Nome do produto vendido. Usado para localizar ou criar automaticamente o produto correspondente na CertoPay, para que a venda apareça corretamente no Ranking de Vendas e relatórios.
`productSku`	string	Não	SKU do produto no seu sistema. Se enviado, tem prioridade sobre productName para localizar um produto já existente.

Dica

Se nenhum dos dois campos for enviado, a venda é registrada sob um produto genérico “Venda via API” — recomendamos sempre enviar ao menos productName para melhor rastreabilidade nos relatórios e no Ranking de Vendas.

Resposta:

json

{
  "id": "uuid-do-pedido",
  "customerId": "uuid-do-customer",
  "amount": 297.00,
  "productName": "Nome do produto vendido",
  "productSku": "SKU-INTERNO-123",
  "status": "PENDING",
  "createdAt": "2026-06-26T10:00:00Z"
}

Nota

Guarde o id do pedido — ele é o orderId usado no processamento do pagamento.

Listar pedidos

GET/api/orders

http

GET /api/orders
X-Api-Key: sk_live_sua_chave_aqui

Buscar pedido por ID

GET/api/orders/{id}

http

GET /api/orders/{id}
X-Api-Key: sk_live_sua_chave_aqui

3.1 Rastreio de Pedidos

Assim que o produto for despachado, informe o código de rastreio para que ele apareça automaticamente no painel Seller da CertoPay.

Atualizar código de rastreio

PATCH/api/orders/{id}/tracking

http

PATCH /api/orders/{id}/tracking
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "trackingCode": "BR1234567890XX"
}

Campos do corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`trackingCode`	string	Sim	Código de rastreio da transportadora

Nota

{id} é o id do pedido retornado na criação do pedido (seção 3), não o orderNumber.

Resposta:

json

{
  "id": "uuid-do-pedido",
  "trackingCode": "BR1234567890XX",
  "trackingUpdatedAt": "2026-07-18T14:30:00Z",
  "status": "PAID",
  "createdAt": "2026-06-26T10:00:00Z"
}

Dica

Chame este endpoint assim que o rastreio for gerado na sua própria plataforma de logística — não é necessário nenhum outro passo, o valor aparece automaticamente na tela de Vendas do Seller.

Consultar pedidos pendentes de rastreio

GET/api/orders/tracking-pending

http

GET /api/orders/tracking-pending?days=15
X-Api-Key: sk_live_sua_chave_aqui

Retorna pedidos pagos há mais de N dias (padrão 15, ajustável via ?days=) que ainda não têm código de rastreio preenchido — útil para automatizar seus próprios alertas internos.

Resposta:

json

{
  "count": 3,
  "days": 15,
  "orders": [
    { "id": "uuid-do-pedido", "orderNumber": "1784387748174", "createdAt": "2026-07-01T10:00:00Z", "amount": "12.90" }
  ]
}

4. Processar Pagamento

Endpoint unificado para todos os métodos de pagamento.

POST/api/payment-gateway/process

Headers obrigatórios

Header	Obrigatório	Descrição
`X-Api-Key`	Sim	Sua API Key
`Content-Type`	Sim	`application/json`
`Idempotency-Key`	Recomendado	UUID único por tentativa de cobrança

Sempre envie um Idempotency-Key diferente a cada nova tentativa.

Recomendamos UUID v4. A chave é válida por 24h — reenviar a mesma chave retorna o resultado original sem processar novamente.

Sobre split de pagamentos

Este endpoint não recebe informações de split no corpo da requisição. Se sua conta tiver uma regra de split ativa (ver seção 10), ela é aplicada automaticamente depois que a transação é aprovada — você não precisa (e não deve) enviar nada relacionado a split aqui.

Campos comuns a todos os métodos

Campo	Tipo	Obrigatório	Descrição
`orderId`	string	Sim	ID do pedido criado em `/api/orders`
`method`	string	Sim	`PIX`, `BOLETO` ou `CARD`
`amount`	number	Sim	Valor em reais (ex: `50.00`), mínimo `0.01`
`sellerId`	string	Não	ID do Estabelecimento (Company) na CertoPay ao qual esta venda pertence. Use quando uma única API Key processa vendas de múltiplos estabelecimentos. Se omitido, o estabelecimento é resolvido normalmente pela API Key usada na chamada.
`installments`	number	Não	Número de parcelas (cartão)
`baseAmount`	number	Não	Valor da venda sem o juro de parcelamento. Envie este campo sempre que o valor em `amount` já incluir o juro calculado a partir de `GET /payment-gateway/installment-rates` (ver seção 5). Se `baseAmount` não for enviado, `amount` é tratado como o valor total da venda.
`buyerDoc`	string	Recomendado	CPF/CNPJ do comprador, somente números
`buyerBirthdate`	string	Recomendado	Data de nascimento (`YYYY-MM-DD`)
`buyerCellNumber`	string	Recomendado	Celular do comprador
`buyerAddress`	object	Recomendado	Endereço completo (ver abaixo)

Dica

Exemplo: se a tabela de juros retornar finalRatePercent de 8,35% para 3x, e o produto custa R$ 100,00, envie amount: 108.35 (valor com juro, cobrado do comprador) e baseAmount: 100.00 (preço original do produto).

Processando vendas de múltiplos estabelecimentos com uma única API Key

Se sua integração processa vendas de mais de um Estabelecimento cadastrado na CertoPay usando a mesma API Key, informe o campo sellerId no corpo da requisição com o ID do Estabelecimento correspondente àquela venda específica.

O sellerId informado é validado: ele precisa pertencer à mesma conta (tenant) da API Key usada na chamada. Se o ID não existir ou pertencer a outra conta, a requisição é rejeitada com erro 403 e a venda não é processada.

Se o campo sellerId não for enviado, o Estabelecimento continua sendo resolvido normalmente a partir da API Key usada — nenhuma mudança de comportamento para integrações existentes.

Exemplo de requisição:

json

{
  "orderId": "ord_123456",
  "method": "PIX",
  "amount": 50.00,
  "sellerId": "clx1a2b3c4d5e6f7g8h9"
}

Exemplo de erro (sellerId inválido ou de outra conta):

json

{
  "statusCode": 403,
  "message": "O sellerId informado não pertence à sua conta ou não existe."
}

Atenção

Para cartão de crédito, buyerDoc, buyerBirthdate, buyerCellNumber e buyerAddress são efetivamente obrigatórios: o adquirente exige um comprador válido cadastrado para aprovar a cobrança. Enviar a transação sem esses dados tende a ser recusada.

Objeto `buyerAddress`

json

{
  "postal_code": "01310930",
  "street": "Avenida Paulista",
  "number": "100",
  "complement": "Apto 42",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP"
}

Campo	Tipo	Obrigatório	Descrição
`postal_code`	string	Sim	CEP
`street`	string	Sim	Logradouro
`number`	string	Sim	Número
`complement`	string	Não	Complemento
`neighborhood`	string	Sim	Bairro
`city`	string	Sim	Cidade
`state`	string	Sim	UF, 2 letras

4.1 PIX

POST/api/payment-gateway/process

http

POST /api/payment-gateway/process
X-Api-Key: sk_live_sua_chave_aqui
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001
Content-Type: application/json

{
  "orderId": "uuid-do-pedido",
  "method": "PIX",
  "amount": 297.00,
  "buyerDoc": "12345678900",
  "buyerCellNumber": "(11) 99999-9999",
  "buyerAddress": {
    "postal_code": "01310930",
    "street": "Avenida Paulista",
    "number": "100",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  }
}

Resposta:

json

{
  "transactionId": "uuid-da-transacao",
  "status": "PENDING",
  "method": "PIX",
  "amount": 297.00,
  "pix": {
    "emv": "00020126580014br.gov.bcb.pix...",
    "qrCodeUrl": "https://...",
    "expiresAt": "2026-06-26T11:00:00Z"
  }
}

Exiba o emv (copia e cola) ou o QR Code para o comprador. A confirmação chega via webhook quando o PIX é liquidado.

5. Tabela de Juros por Parcela

Ao vender no cartão de crédito parcelado, cada parcela tem um percentual de juro embutido — o valor da parcela sobe conforme o número de parcelas escolhido. A CertoPay expõe uma tabela oficial (1x a 12x) para que o checkout do parceiro exiba, para o comprador, o valor exato de cada parcela antes de fechar a compra.

Importante — consulte antes de exibir o preço parcelado.

Se sua integração oferece parcelamento ao cliente final, consulte este endpoint ANTES de mostrar a tela de escolha de parcelas, e calcule o valor de cada parcela aplicando o finalRatePercent correspondente sobre o valor total da compra. Isso garante que o valor exibido ao comprador seja exatamente o valor que será processado em /payment-gateway/process.

Consultar tabela de juros

GET/api/payment-gateway/installment-rates

http

GET /api/payment-gateway/installment-rates
X-Api-Key: sk_live_sua_chave_aqui

Resposta:

json

{
  "rates": [
    { "installments": 1, "baseMdrPercent": 0, "marginPercent": 0, "finalRatePercent": 0 },
    { "installments": 2, "baseMdrPercent": 5.55, "marginPercent": 2.00, "finalRatePercent": 7.55 },
    { "installments": 3, "baseMdrPercent": 6.35, "marginPercent": 2.00, "finalRatePercent": 8.35 },
    { "installments": 4, "baseMdrPercent": 7.17, "marginPercent": 2.00, "finalRatePercent": 9.17 },
    { "installments": 5, "baseMdrPercent": 7.99, "marginPercent": 2.00, "finalRatePercent": 9.99 },
    { "installments": 6, "baseMdrPercent": 8.82, "marginPercent": 2.00, "finalRatePercent": 10.82 },
    { "installments": 7, "baseMdrPercent": 9.98, "marginPercent": 2.00, "finalRatePercent": 11.98 },
    { "installments": 8, "baseMdrPercent": 10.83, "marginPercent": 2.00, "finalRatePercent": 12.83 },
    { "installments": 9, "baseMdrPercent": 11.69, "marginPercent": 2.00, "finalRatePercent": 13.69 },
    { "installments": 10, "baseMdrPercent": 12.55, "marginPercent": 2.00, "finalRatePercent": 14.55 },
    { "installments": 11, "baseMdrPercent": 13.43, "marginPercent": 2.00, "finalRatePercent": 15.43 },
    { "installments": 12, "baseMdrPercent": 14.31, "marginPercent": 2.00, "finalRatePercent": 15.31 }
  ]
}

Compra à vista (1x) nunca tem acréscimo de juro — o campo finalRatePercent para installments: 1 é sempre 0.

Campos da resposta

Campo	Tipo	Obrigatório	Descrição
`installments`	number	Sim	Número de parcelas
`baseMdrPercent`	number	Sim	Taxa de referência (custo real do adquirente)
`marginPercent`	number	Sim	Margem da CertoPay somada sobre a base
`finalRatePercent`	number	Sim	Percentual final de juro a aplicar sobre o valor da compra nesta parcela

Como calcular o valor de cada parcela

Exemplo: compra de R$ 100,00 em 3x.

Consulte a tabela e localize installments: 3 → finalRatePercent: 8.35.
Valor total com juro = 100 * (1 + 8.35 / 100) = R$ 108,35.
Valor de cada parcela = 108,35 / 3 = R$ 36,12.
Envie amount: 108.35 e installments: 3 no POST /payment-gateway/process.

Dica

Esta tabela é a mesma para todos os Estabelecimentos e pode ser atualizada periodicamente pela CertoPay. Não faça cache por mais de algumas horas — consulte novamente a cada nova sessão de checkout.

Nota

Parcelas acima de 12x não são suportadas — a CertoPay processa cobranças com cartão de 1x a 12x apenas.

7. Consultar Transações

Listar todas as transações

GET/api/transactions

http

GET /api/transactions
X-Api-Key: sk_live_sua_chave_aqui

Buscar transação por ID

GET/api/transactions/{transactionId}

http

GET /api/transactions/{transactionId}
X-Api-Key: sk_live_sua_chave_aqui

Resposta:

json

{
  "id": "uuid-da-transacao",
  "orderId": "uuid-do-pedido",
  "method": "PIX",
  "amount": 297.00,
  "status": "PAID",
  "createdAt": "2026-06-26T10:00:00Z",
  "updatedAt": "2026-06-26T10:05:00Z"
}

Listar eventos de uma transação

GET/api/transaction-events/transaction/{transactionId}

http

GET /api/transaction-events/transaction/{transactionId}
X-Api-Key: sk_live_sua_chave_aqui

8. Reembolso

Reembolso total

POST/api/payment-gateway/refund

http

POST /api/payment-gateway/refund
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "transactionId": "uuid-da-transacao",
  "reason": "Solicitação do cliente"
}

Reembolso parcial

POST/api/payment-gateway/refund

http

POST /api/payment-gateway/refund
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "transactionId": "uuid-da-transacao",
  "amount": 100.00,
  "reason": "Desconto aplicado retroativamente"
}

9. Estabelecimentos

Um Estabelecimento é uma subconta dentro da sua conta CertoPay, usada para dividir automaticamente o valor das vendas via Split de Pagamento (ver seção seguinte). Não confundir com Customer (seção 2) — Customer é o comprador final que paga uma cobrança; Estabelecimento é quem RECEBE parte do dinheiro.

⚠️Importante — leia antes de integrar

O cadastro de um Estabelecimento é feito em 4 chamadas (empresa, endereço, sócio administrador, conta bancária) e pode ser completado em etapas — não precisa mandar tudo de uma vez.

A aprovação junto ao adquirente é AUTOMÁTICA e ASSÍNCRONA: assim que os 4 blocos estiverem completos, o sistema submete sozinho, sem nenhuma chamada extra. Isso pode levar minutos. Consulte o status pelo campo payoutAccount.status no GET.

Esses endpoints aceitam autenticação via X-Api-Key OU JWT (Authorization: Bearer {jwt_token}) — o mesmo padrão usado no resto da API.

Criar Estabelecimento

POST/api/companies

http

POST /api/companies
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "legalName": "Loja Exemplo LTDA",
  "tradeName": "Loja Exemplo",
  "document": "12345678000199",
  "email": "contato@lojaexemplo.com",
  "phone": "11999999999",
  "website": "https://lojaexemplo.com.br",
  "cnaeCode": "6201-5/01",
  "legalNatureCode": "206-2",
  "companyType": "LTDA",
  "foundationDate": "2018-03-10",
  "annualRevenue": 250000.00
}

Campos do corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`legalName`	string	Sim	Razão social
`document`	string	Sim	CNPJ (só números)
`tradeName`	string	Não	Nome fantasia
`email`	string	Não*	E-mail de contato
`phone`	string	Não*	Telefone
`website`	string	Não	Site
`cnaeCode`	string	Não*	Código CNAE da atividade
`legalNatureCode`	string	Não*	Código de natureza jurídica
`companyType`	string	Não*	Um de: `MEI`, `ME`, `EPP`, `LTDA`, `EIRELI`, `SA`, `ASSOCIACOES_ENTIDADES`, `DEMAIS_PORTES`
`foundationDate`	string	Não*	Data de fundação (YYYY-MM-DD)
`annualRevenue`	number	Não	Faturamento anual

*Campos marcados com asterisco não são obrigatórios na criação, mas são exigidos (junto com endereço, sócio e conta bancária) para o Estabelecimento ser aprovado e poder receber split de verdade.

Resposta: objeto Company criado, incluindo id — use nas próximas 3 chamadas.

Guarde este id — ele é o identificador permanente deste Estabelecimento na CertoPay. Use-o em todas as chamadas seguintes (endereço, sócio, conta bancária) e, futuramente, para incluir este Estabelecimento numa regra de Split (estabelecimentoCompanyId, ver seção Split de Pagamentos). Este mesmo id também fica visível no painel Seller, na tela "Estabelecimentos" → clique em "Ver" em qualquer Estabelecimento → aparece em destaque no topo do modal, com botão de copiar.

Endereço do Estabelecimento

PATCH/api/companies/{id}/address

http

PATCH /api/companies/{id}/address
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "zipCode": "01310100",
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Sala 200",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR"
}

Idempotente — pode chamar quantas vezes precisar, sempre atualiza o mesmo registro.

Sócio Administrador

PATCH/api/companies/{id}/managing-partner

http

PATCH /api/companies/{id}/managing-partner
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "name": "João da Silva",
  "document": "12345678900",
  "birthdate": "1985-06-15",
  "email": "joao@lojaexemplo.com",
  "motherName": "Maria da Silva",
  "phoneCountryCode": "+55",
  "phoneAreaCode": "11",
  "phoneNumber": "988887777",
  "zipcode": "01310100",
  "state": "SP",
  "city": "São Paulo",
  "neighborhood": "Bela Vista",
  "street": "Av. Paulista",
  "number": "1000",
  "complement": null
}

Todos os campos são obrigatórios pra aprovação, exceto email e complement.

Conta Bancária

PATCH/api/companies/{id}/bank-account

http

PATCH /api/companies/{id}/bank-account
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "bankCode": "260",
  "bankName": "Nubank",
  "agency": "0001",
  "agencyDigit": null,
  "account": "12345678",
  "accountDigit": "9",
  "accountType": "corrente",
  "pixKeyType": "cnpj",
  "pixKey": "12345678000199"
}

accountType: corrente ou poupanca. pixKeyType: cnpj, email, phone ou random.

Consultar status de aprovação

GET/api/companies/{id}

O campo payoutAccount.status no retorno indica o status:

Status	Significado
`NOT_CREATED`	Cadastro incompleto — falta algum dado
`PENDING`	Dados completos, aguardando aprovação
`ACTIVE`	Aprovado — já pode receber split de verdade
`REFUSED`	Recusado
`BLOCKED` / `INACTIVE`	Bloqueado / inativo

9.1 Documentos do Estabelecimento (KYC)

Antes de um Estabelecimento ser aprovado para receber split de verdade, é necessário enviar os documentos de identidade do responsável (RG ou CNH, mais uma selfie segurando o documento). O envio pode ser feito via API, sem precisar acessar o painel Seller.

Importante

Os documentos ficam com status PENDING até serem revisados manualmente pela equipe CertoPay no Manager. Isso pode levar algum tempo — não é instantâneo. Consulte o status pelo endpoint de listagem antes de considerar o Estabelecimento totalmente aprovado.

Enviar documento

POST/api/kyc/upload

Requisição em multipart/form-data (não application/json, diferente da maioria dos outros endpoints desta API).

bash

curl -X POST https://v2.certopaybrasil.com/api/kyc/upload \
  -H "X-Api-Key: sk_live_sua_chave" \
  -F "file=@/caminho/rg-frente.jpg" \
  -F "documentType=RG_FRENTE" \
  -F "companyId=uuid-do-estabelecimento"

Campos do formulário

Campo	Tipo	Obrigatório	Descrição
`file`	arquivo	Sim	Imagem (JPG/PNG) ou PDF do documento
`documentType`	string	Sim	Um dos valores listados na tabela abaixo
`companyId`	string	Sim	`id` do Estabelecimento dono do documento (ver seção 9)

Valores aceitos para documentType

Valor	Descrição
`RG_FRENTE`	RG, frente
`RG_VERSO`	RG, verso
`CNH_FRENTE`	CNH, frente
`CNH_VERSO`	CNH, verso
`SELFIE_RG`	Selfie do responsável segurando o documento
`COMPROVANTE_ENDERECO`	Comprovante de endereço
`COMPROVANTE_FATURAMENTO`	Comprovante de faturamento
`CNPJ`	Cartão CNPJ
`CONTRATO_SOCIAL`	Contrato social

Dica

Envie no mínimo RG (frente e verso) OU CNH (frente e verso), mais a selfie — é o mínimo exigido para análise.

Resposta:

json

{
  "id": "uuid-do-documento",
  "companyId": "uuid-do-estabelecimento",
  "documentType": "RG_FRENTE",
  "fileUrl": "https://...",
  "fileName": "rg-frente.jpg",
  "status": "PENDING",
  "createdAt": "2026-07-07T10:00:00Z"
}

Consultar documentos enviados

GET/api/kyc/my?companyId={id}

Retorna a lista de todos os documentos já enviados para aquele Estabelecimento, com o status atual de cada um.

bash

curl https://v2.certopaybrasil.com/api/kyc/my?companyId=uuid-do-estabelecimento \
  -H "X-Api-Key: sk_live_sua_chave"

Resposta:

json

[
  {
    "id": "uuid-do-documento",
    "documentType": "RG_FRENTE",
    "fileUrl": "https://...",
    "status": "APPROVED",
    "rejectedReason": null,
    "createdAt": "2026-07-07T10:00:00Z",
    "reviewedAt": "2026-07-07T14:30:00Z"
  }
]

Valores possíveis de status

Status	Significado
`PENDING`	Aguardando revisão
`APPROVED`	Aprovado
`REJECTED`	Reprovado — ver rejectedReason

Nota

Se um documento for reprovado (REJECTED), reenvie um novo arquivo com o mesmo documentType — não é possível editar o documento existente, apenas enviar um novo, que passa a ser o mais recente daquele tipo.

10. Split de Pagamentos

O Split permite dividir automaticamente o valor de cada venda entre múltiplos recebedores (por exemplo, entre diferentes estabelecimentos/contas cadastrados na sua conta CertoPay).

⚠️Importante — leia antes de integrar

O split não é enviado na hora da cobrança. Ele é configurado previamente, uma única vez (ou sempre que a regra precisar mudar), através dos endpoints abaixo. A partir do momento em que uma regra é marcada como ativa, ela passa a valer automaticamente para todas as transações aprovadas da conta — nenhum campo adicional é necessário nas chamadas de /payment-gateway/process.

Esses endpoints aceitam autenticação via X-Api-Key OU JWT (Authorization: Bearer {accessToken}) — o mesmo padrão usado no resto da API.

Essa é a mesma funcionalidade disponível na tela "Split de Pagamentos" do painel Seller — configurar via API tem exatamente o mesmo efeito que configurar por lá.

Regras gerais

Apenas uma regra pode estar ativa por vez por conta (companyId). Ao criar uma nova regra, qualquer regra ativa anterior é automaticamente desativada.
Uma regra tem um ou mais destinatários (recipients). Cada destinatário é vinculado a EXATAMENTE UM entre: receiverGatewayConfigId (um recebedor cadastrado pela CertoPay) OU estabelecimentoCompanyId (o id de um Estabelecimento — ver seção anterior). Enviar os dois juntos, ou nenhum dos dois, retorna erro 400.
Cada destinatário recebe uma fatia definida por type (PERCENTAGE ou FIXED) e value.
A soma dos percentuais (type: "PERCENTAGE") entre todos os destinatários não pode ultrapassar 100%.
O split é aplicado depois que a transação é aprovada, gerando um registro por destinatário com o valor calculado.

Criar regra de split

POST/api/split-config

http

POST /api/split-config
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "name": "Split padrão - Loja + Fornecedor",
  "description": "80% para a loja principal, 20% para o fornecedor parceiro",
  "feeResponsibility": "MAIN_RECEIVER",
  "recipients": [
    {
      "receiverGatewayConfigId": "uuid-do-recebedor-1",
      "type": "PERCENTAGE",
      "value": 80,
      "chargebackLiable": true,
      "processingFeeResponsible": true
    },
    {
      "estabelecimentoCompanyId": "uuid-do-estabelecimento-1",
      "type": "PERCENTAGE",
      "value": 20,
      "chargebackLiable": false,
      "processingFeeResponsible": false
    }
  ]
}

Campos do corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome identificador da regra
`description`	string	Não	Descrição livre
`feeResponsibility`	string	Não	`MAIN_RECEIVER` (padrão), `PROPORTIONAL` ou `RECIPIENT` — ver nota abaixo
`recipients`	array	Sim	Lista de destinatários (mínimo 1)

Campos de cada item em `recipients`

Campo	Tipo	Obrigatório	Descrição
`receiverGatewayConfigId`	string	Sim*	ID de um recebedor cadastrado pela CertoPay (deve pertencer à mesma `company`). *Envie ISSO OU `estabelecimentoCompanyId`, nunca os dois.
`estabelecimentoCompanyId`	string	Sim*	`id` de um Estabelecimento cadastrado (ver seção Estabelecimentos). *Envie ISSO OU `receiverGatewayConfigId`, nunca os dois.
`type`	string	Sim	`PERCENTAGE` ou `FIXED`
`value`	number	Sim	Se `PERCENTAGE`: valor de 0 a 100. Se `FIXED`: valor em reais
`chargebackLiable`	boolean	Não (padrão false)	Se este destinatário é responsável em caso de chargeback
`processingFeeResponsible`	boolean	Não (padrão false)	Se este destinatário arca com a taxa de processamento

feeResponsibility — campo ainda sem efeito funcional

O valor é aceito e armazenado normalmente, mas atualmente não é utilizado em nenhum cálculo de taxa ou repasse durante o processamento do split. O rateio efetivo entre os destinatários é determinado apenas por type e value de cada item em recipients. Envie MAIN_RECEIVER (valor padrão) ou omita o campo — qualquer um dos três valores aceitos tem, hoje, o mesmo comportamento na prática. Este comportamento pode mudar em uma atualização futura da API; consulte o suporte CertoPay caso sua integração dependa de repasse de taxa por destinatário.

Resposta:

json

{
  "id": "uuid-da-regra",
  "tenant_id": "uuid-tenant",
  "company_id": "uuid-company",
  "name": "Split padrão - Loja + Fornecedor",
  "description": "80% para a loja principal, 20% para o fornecedor parceiro",
  "fee_responsibility": "MAIN_RECEIVER",
  "status": "ACTIVE",
  "split_config_recipients": [
    {
      "receiver_gateway_config_id": "uuid-do-recebedor-1",
      "type": "PERCENTAGE",
      "value": 80,
      "chargeback_liable": true,
      "processing_fee_responsible": true
    },
    {
      "estabelecimento_company_id": "uuid-do-estabelecimento-1",
      "type": "PERCENTAGE",
      "value": 20,
      "chargeback_liable": false,
      "processing_fee_responsible": false
    }
  ]
}

Listar todas as regras de split

GET/api/split-config

http

GET /api/split-config
X-Api-Key: sk_live_sua_chave_aqui

Retorna todas as regras (ativas e inativas) da conta autenticada, ordenadas da mais recente para a mais antiga.

Consultar a regra ativa

GET/api/split-config/active

http

GET /api/split-config/active
X-Api-Key: sk_live_sua_chave_aqui

Retorna a única regra atualmente com status: "ACTIVE" (ou null/vazio se nenhuma regra estiver ativa). Este é o endpoint recomendado para verificar qual configuração está valendo neste momento.

Editar uma regra existente

PATCH/api/split-config/{id}

http

PATCH /api/split-config/{id}
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "name": "Split atualizado",
  "recipients": [
    {
      "receiverGatewayConfigId": "uuid-do-recebedor-1",
      "type": "PERCENTAGE",
      "value": 70
    },
    {
      "receiverGatewayConfigId": "uuid-do-recebedor-2",
      "type": "PERCENTAGE",
      "value": 30
    }
  ]
}

Todos os campos são opcionais — envie apenas os que deseja alterar. Atenção: se recipients for enviado, a lista de destinatários anterior é substituída por completo pela nova lista (não é possível editar um destinatário individualmente).

Ativar / desativar uma regra

PATCH/api/split-config/{id}/toggle

http

PATCH /api/split-config/{id}/toggle
X-Api-Key: sk_live_sua_chave_aqui

Alterna o status da regra entre ACTIVE e INACTIVE. Se o resultado for ACTIVE, qualquer outra regra ativa da conta é automaticamente desativada (mantendo a regra "apenas uma ativa por vez").

Remover uma regra

DELETE/api/split-config/{id}

http

DELETE /api/split-config/{id}
X-Api-Key: sk_live_sua_chave_aqui

Erros comuns ao configurar split

Situação	Retorno
`recipients` vazio ou ausente	`400` — `"Adicione pelo menos um destinatário"`
Soma dos percentuais acima de 100%	`400` — `"Percentuais somam X% — máximo é 100%"`
`receiverGatewayConfigId` que não pertence à conta	`400` — `"Um ou mais recebedores não pertencem a esta conta"`
`recipient` com os dois campos preenchidos, ou nenhum	`400` — `"Cada destinatário deve ter EXATAMENTE um entre receiverGatewayConfigId ou estabelecimentoCompanyId"`
`estabelecimentoCompanyId` que não existe ou não pertence à conta	`400` — `"Um ou mais Estabelecimentos não foram encontrados nesta conta"`
Regra não encontrada (ID inválido ou de outra conta)	`404` — `"Configuração de split não encontrada"`

11. Webhooks

Configure um endpoint no seu servidor para receber notificações automáticas de eventos de pagamento.

Registrar ou atualizar webhook

POST/api/webhooks/upsert

http

POST /api/webhooks/upsert
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "url": "https://seusite.com/webhooks/certopay"
}

Consultar webhook cadastrado

GET/api/webhooks

http

GET /api/webhooks
X-Api-Key: sk_live_sua_chave_aqui

Desativar webhook

DELETE/api/webhooks

http

DELETE /api/webhooks
X-Api-Key: sk_live_sua_chave_aqui

Histórico de entregas

GET/api/webhooks/deliveries

http

GET /api/webhooks/deliveries
X-Api-Key: sk_live_sua_chave_aqui

Filtros disponíveis via query string:

?status=SUCCESS
?status=FAILED
?status=PENDING
?event=transaction.paid

Reenviar entrega manualmente

POST/api/webhooks/deliveries/{deliveryId}/retry

http

POST /api/webhooks/deliveries/{deliveryId}/retry
X-Api-Key: sk_live_sua_chave_aqui

Formato do payload recebido no seu endpoint

json

{
  "event": "transaction.paid",
  "created_at": "2026-06-26T10:05:00Z",
  "data": {
    "transactionId": "uuid-da-transacao",
    "orderId": "uuid-do-pedido",
    "amount": 297.00,
    "method": "PIX",
    "status": "PAID",
    "paidAt": "2026-06-26T10:05:00Z"
  }
}

Eventos disponíveis

Evento	Descrição
`transaction.created`	Transação criada
`transaction.paid`	Pagamento confirmado
`transaction.refused`	Pagamento recusado
`transaction.refunded`	Reembolso processado
`transaction.chargeback`	Chargeback recebido
`transaction.expired`	PIX ou boleto expirado
`transaction.cancelled`	Transação cancelada

Dica

Seu endpoint deve responder HTTP 200 em até 5 segundos. Caso contrário, a CertoPay tentará o reenvio automaticamente.

12. Status das Transações

Status	Descrição
`CREATED`	Transação criada, aguardando processamento
`PENDING`	Aguardando pagamento (PIX/boleto gerados)
`AUTHORIZED`	Cartão autorizado, aguardando captura
`CAPTURED`	Cartão capturado com sucesso
`PAID`	Pagamento confirmado (PIX/boleto)
`REFUSED`	Recusado
`EXPIRED`	Prazo de pagamento expirado
`FAILED`	Erro no processamento
`REFUNDED`	Reembolso total realizado
`PARTIAL_REFUND`	Reembolso parcial realizado
`CHARGEBACK`	Contestação aberta pelo comprador
`CANCELLED`	Transação cancelada

13. Erros

Todos os erros seguem o formato:

json

{
  "statusCode": 400,
  "message": "Descrição do erro",
  "error": "Bad Request"
}

Status	Descrição
`400`	Payload inválido ou parâmetro ausente
`401`	Token ou API Key ausente ou inválido
`403`	Sem permissão para o recurso
`404`	Recurso não encontrado
`429`	Limite de requisições excedido
`500`	Erro interno inesperado

14. Boas Práticas

Idempotência: sempre envie um Idempotency-Key único (UUID v4) em toda chamada ao /api/payment-gateway/process. Em caso de timeout ou erro de rede, reenvie a mesma chave — a CertoPay retornará o resultado original sem cobrar novamente.

Segurança da API Key: nunca exponha sua chave no frontend, em apps mobile ou em repositórios públicos. Use variáveis de ambiente no servidor.

Segurança do JWT (rotas administrativas): o token de acesso usado para configurar Split e outras operações administrativas tem o mesmo nível de sensibilidade da API Key — nunca exponha no frontend.

Validação de webhooks: ao receber um webhook, consulte a transação via GET /api/transactions/{id} para confirmar o status antes de liberar o acesso ao produto.

Split de Pagamentos: configure a regra de split antes de começar a processar vendas que precisam da divisão — ela não é retroativa a transações já aprovadas antes da regra ser criada/ativada. Use GET /api/split-config/active para confirmar qual regra está valendo antes de reportar qualquer divergência de valores.

Rate limit: a API Key padrão suporta 100 requisições por minuto. Entre em contato caso precise de limites maiores.

Fluxo completo — exemplo em cURL

bash

# 1. Criar customer
curl -X POST https://v2.certopaybrasil.com/api/customers \
  -H "X-Api-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"name":"João Silva","email":"joao@email.com","document":"12345678900","phone":"(11) 99999-9999"}'

# 2. Criar pedido
curl -X POST https://v2.certopaybrasil.com/api/orders \
  -H "X-Api-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"uuid-customer","amount":299.00}'

# 3. (Opcional, uma única vez) Configurar split de pagamentos
curl -X POST https://v2.certopaybrasil.com/api/split-config \
  -H "X-Api-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"name":"Split padrão","recipients":[{"receiverGatewayConfigId":"uuid-recebedor-1","type":"PERCENTAGE","value":80},{"receiverGatewayConfigId":"uuid-recebedor-2","type":"PERCENTAGE","value":20}]}'

# 4. Processar pagamento PIX
curl -X POST https://v2.certopaybrasil.com/api/payment-gateway/process \
  -H "X-Api-Key: sk_live_sua_chave" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
  -H "Content-Type: application/json" \
  -d '{"orderId":"uuid-pedido","method":"PIX","amount":297.00,"buyerDoc":"12345678900"}'

# 5. Consultar status
curl https://v2.certopaybrasil.com/api/transactions/{transactionId} \
  -H "X-Api-Key: sk_live_sua_chave"

Primeiros passos

1. Autenticação

1.1 API Key (recomendado)

1.2 JWT (alternativa)

2. Clientes (Customers)

Criar cliente

Listar clientes

Buscar cliente por ID

Atualizar cliente

Remover cliente

3. Pedidos (Orders)

Criar pedido

Listar pedidos

Buscar pedido por ID

3.1 Rastreio de Pedidos

Atualizar código de rastreio

Campos do corpo da requisição

Consultar pedidos pendentes de rastreio

4. Processar Pagamento

Headers obrigatórios

Campos comuns a todos os métodos

Processando vendas de múltiplos estabelecimentos com uma única API Key

Objeto buyerAddress

4.1 PIX

5. Tabela de Juros por Parcela

Consultar tabela de juros

Campos da resposta

Como calcular o valor de cada parcela

7. Consultar Transações

Listar todas as transações

Buscar transação por ID

Listar eventos de uma transação

8. Reembolso

Reembolso total

Reembolso parcial

9. Estabelecimentos

Criar Estabelecimento

Campos do corpo da requisição

Endereço do Estabelecimento

Sócio Administrador

Conta Bancária

Consultar status de aprovação

9.1 Documentos do Estabelecimento (KYC)

Enviar documento

Campos do formulário

Valores aceitos para documentType

Consultar documentos enviados

Valores possíveis de status

10. Split de Pagamentos

Regras gerais

Criar regra de split

Campos do corpo da requisição

Campos de cada item em recipients

Listar todas as regras de split

Consultar a regra ativa

Editar uma regra existente

Ativar / desativar uma regra

Remover uma regra

Erros comuns ao configurar split

11. Webhooks

Registrar ou atualizar webhook

Consultar webhook cadastrado

Desativar webhook

Histórico de entregas

Reenviar entrega manualmente

Formato do payload recebido no seu endpoint

Eventos disponíveis

12. Status das Transações

13. Erros

14. Boas Práticas

Fluxo completo — exemplo em cURL

Objeto `buyerAddress`

Campos de cada item em `recipients`