Pular para o conteúdo
KrokoPayDocs
Painel

Atenção: Proposta provisória de contrato

Estes endpoints ainda não estão em operação e nenhum SDK foi publicado. Os exemplos usam apenas identificadores de teste e nada é enviado a lugar nenhum.

Pagamentos

Clientes

Um cliente é a pessoa ou empresa que paga você. Vincule clientes a cobranças e assinaturas para ter o histórico de pagamentos de cada comprador.

Nesta página

Os clientes agrupam os pagamentos por comprador. Você pode criá-los pela API ou deixar o checkout fazer isso: quando um comprador paga sem customer_id, a KrokoPay procura um cliente com o mesmo e-mail ou cria um novo. Nos dois casos, todas as cobranças, reembolsos e assinaturas desse comprador ficam reunidos em um só registro no painel.

O objeto customer

Atributos

idstring
Identificador único, com o prefixo cus_.
objectstring
Sempre customer.
namestring
Nome completo ou razão social.
emailstring
Usado nos comprovantes e para reconhecer o comprador no checkout (sem diferenciar maiúsculas e minúsculas).
phonestring | null
Telefone em formato internacional.
documentstring | null
CPF ou CNPJ, sempre devolvido mascarado. Veja CPF e CNPJ.
created_atstring
Data e hora em ISO 8601.
Um clienteJSON
{  "id": "cus_8Hq2LmZr4TxN1a",  "object": "customer",  "name": "Ana Beatriz Souza",  "email": "ana.souza@example.com",  "phone": "+55 11 5555-0101",  "document": "•••.•••.•••-00",  "created_at": "2026-10-28T13:04:11.000Z"}

Criar um cliente

Endpoint: POST/v1/customers

Crie o cliente quando o comprador se cadastrar no seu produto e reutilize o id em todas as cobranças. Só name e email são obrigatórios.

Parâmetros do corpo

namestringObrigatório
Nome completo ou razão social.
emailstringObrigatório
Um e-mail válido. Nos testes, use @example.com.
phonestringOpcional
Telefone, opcional.
documentstringOpcional
CPF (11 dígitos) ou CNPJ (14 dígitos), opcional, com ou sem pontuação.
curl -X POST https://api.krokopay.app/v1/customers \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Content-Type: application/json" \  -d '{    "name": "Ana Beatriz Souza",    "email": "ana.souza@example.com"  }'
curl -X POST https://api.krokopay.app/v1/customers \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Idempotency-Key: customer_ana_souza" \  -H "Content-Type: application/json" \  -d '{    "name": "Ana Beatriz Souza",    "email": "ana.souza@example.com",    "phone": "+55 11 5555-0101",    "document": "000.000.001-00"  }'

Atenção: Evite duplicados

Procure o comprador no seu próprio banco de dados antes de criar e envie um Idempotency-Key derivado do id do seu usuário, para que uma requisição repetida não crie um segundo cliente. Veja Idempotência.

Consultar um cliente

Endpoint: GET/v1/customers/{id}
curl https://api.krokopay.app/v1/customers/cus_8Hq2LmZr4TxN1a \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"

Listar clientes

Endpoint: GET/v1/customers

Parâmetros de consulta

limitintegerOpcional
Quantos clientes devolver, do mais recente para o mais antigo. O máximo ainda será definido.
curl https://api.krokopay.app/v1/customers?limit=20 \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"
Informação: A busca por e-mail e a paginação por cursor ainda serão definidas na proposta. Guarde o id cus_… junto com o registro do seu usuário em vez de procurá-lo depois.

Atualizar um cliente

Endpoint: POST/v1/customers/{id}

Envie só os campos que quer mudar: name, email, phone ou document. Os campos omitidos mantêm o valor atual.

curl -X POST https://api.krokopay.app/v1/customers/cus_8Hq2LmZr4TxN1a \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Content-Type: application/json" \  -d '{    "phone": "+55 11 5555-0199"  }'

Vincular clientes a cobranças

Envie customer_id ao criar uma cobrança. A cobrança entra no histórico do cliente e o checkout já sabe quem está pagando.

curl -X POST https://api.krokopay.app/v1/charges \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Idempotency-Key: order_1043" \  -H "Content-Type: application/json" \  -d '{    "amount": 49700,    "currency": "BRL",    "description": "Curso Identidade Visual do Zero",    "customer_id": "cus_8Hq2LmZr4TxN1a",    "methods": [      "pix"    ]  }'
  • Com customer_id: a cobrança fica vinculada ao cliente desde o início.
  • Sem customer_id: o checkout pede nome e e-mail. No pagamento, o comprador é associado a um cliente existente pelo e-mail (sem diferenciar maiúsculas e minúsculas) ou um novo cliente é criado, e o customer_id da cobrança é preenchido.
  • Assinaturas sempre pertencem a um cliente: o customer_id é obrigatório ao criar uma assinatura.

CPF e CNPJ

O campo document guarda um documento fiscal brasileiro: CPF para pessoas físicas (11 dígitos) ou CNPJ para empresas (14 dígitos). Você pode enviar com pontuação ou só os números.

Você enviaA API devolve
000.000.001-00 (CPF)•••.•••.•••-00
00000000000100 (CNPJ)••.•••.•••/••••-00
nadanull

Atenção: Use apenas valores fictícios de teste

No ambiente de teste, nunca envie o CPF de uma pessoa real nem o CNPJ de uma empresa real. Use valores claramente fictícios, como 000.000.001-00. As respostas mantêm só os dois últimos dígitos, então não conte com a API para devolver o documento completo: se precisar dele, guarde você mesmo, seguindo as suas regras de proteção de dados.

Veja também