API PayVip · v1

Cobre, divida e concilie — pelo seu sistema.

Crie clientes e cobranças (PIX, boleto e cartão), monte assinaturas, reparta cada venda entre parceiros com split automático e receba os eventos no seu endpoint.

A API usa os mesmos motores que processam os pagamentos do console PayVip. Uma regra, um lugar: o que você cria por aqui aparece no console, e o que a operação faz no console aparece aqui.

Basehttps://payvip-api.io

Por onde começar

Primeira cobrança

Do zero ao link de pagamento em quatro chamadas.

Autenticação

Como criar a chave e escolher os escopos.

Como o split funciona

O conceito que mais gera dúvida — leia antes de integrar.

Assinaturas

Cobrar todo mês sem chamar a API todo mês.

Cartões de teste

Testar cartão sem liquidar de verdade.

valide sua chave

# a credencial sai do console PayVip
# em Conectores → API PayVip

curl https://payvip-api.io/v1/ping \
  -H "Authorization: Bearer sk_live_..."

# resposta
{
  "ok": true,
  "empresa": "CLÍNICA EXEMPLO LTDA",
  "escopos": ["clientes:read", "cobrancas:write"]
}

O que dá para fazer

Nove áreas, trinta e dois endpoints. A Referência traz cada um em detalhe; aqui está o mapa.

Área	Para quê
Clientes	Cadastro de quem paga (CPF ou CNPJ)
Cobranças	Avulsa ou recorrente, PIX / boleto / cartão, com ou sem split
Assinaturas	Pausar, reativar e acompanhar recorrências
Itens de split	Catálogo de serviços com a comissão do parceiro
Parceiros	Quem recebe parte da venda
Pedidos e transações	O que foi vendido e como foi rateado
Split manual	Rateio de uma transação já capturada na maquininha
Contas a pagar	Lançar despesas no fluxo de aprovação (Flows)
Webhooks	Receber os eventos no seu endpoint

Ambiente único. A API não tem sandbox separado — toda chamada vale em produção. Para exercitar o fluxo de cartão sem liquidar de verdade, use os cartões de teste.

Comece aqui

Primeira cobrança

Quatro chamadas: valide a chave, crie o cliente, crie a cobrança, receba o evento.

1 · Valide a credencial

O /v1/ping confirma que a chave está viva e mostra quais escopos ela carrega. Se algo falhar depois, volte aqui primeiro.

2 · Crie o cliente

Cliente é quem paga. Precisa de nome e documento (CPF ou CNPJ, com ou sem máscara).

3 · Crie a cobrança

Informe valor_centavos, o metodo e o vencimento. A resposta traz a fatura com o link de pagamento e, no caso do PIX, o copia-e-cola.

Valores são sempre em centavos, inteiros. R$ 149,90 é 14990. Nunca mande decimal — 149.90 vira R$ 1,49.

4 · Receba o evento

Em vez de ficar consultando a cobrança, registre um webhook e receba cobranca.paga quando o dinheiro entrar.

Consultar em laço funciona, mas gasta seu limite de 120 requisições por minuto e ainda assim chega atrasado. O webhook chega no instante da confirmação.

curl -X POST https://payvip-api.io/v1/clientes \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Souza",
    "documento": "123.456.789-09",
    "email": "maria@exemplo.com"
  }'

curl -X POST https://payvip-api.io/v1/cobrancas \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-8812-v1" \
  -d '{
    "cliente_id": "cli_7f3a...",
    "valor_centavos": 14990,   // R$ 149,90
    "metodo": "pix_boleto",
    "vencimento": "2026-09-10",
    "descricao": "Consulta de retorno"
  }'

{
  "id": "cob_2a91...",
  "status": "aberta",
  "valor_centavos": 14990,
  "faturas": [{
    "id": "fat_55c0...",
    "vencimento": "2026-09-10",
    "link": "https://pay.payvip.app/f/55c0...",
    "pix_copia_cola": "00020126850014br.gov..."
  }],
  "rateios": []
}

O ciclo de vida de uma cobrança

Você participa das duas pontas: cria a cobrança e recebe o evento. O meio — entregar o boleto, confirmar o PIX, conciliar o extrato — é da PayVip.

Comece aqui

Autenticação

Uma chave por sistema integrado, com só os escopos que aquele sistema precisa.

Toda chamada leva a chave no header Authorization. A chave é criada no console PayVip em Conectores → API PayVip e aparece uma única vez — guarde no cofre de segredos do seu lado. Se perder, revogue e crie outra.

Escopos

O escopo define o que a chave pode fazer. Os que movem dinheiro vêm desmarcados de propósito no console — marque só se aquele sistema realmente precisa.

clientes:readclientes:write cobrancas:readcobrancas:write parceiros:readparceiros:write pedidos:readtransacoes:read split:readsplit:write contas_pagar:readcontas_pagar:write webhooks:write

Chamar um endpoint sem o escopo correspondente devolve 403.

Restrição por IP

Cada chave aceita uma lista de IPs autorizados. Com a lista preenchida, requisição de qualquer outra origem é recusada — mesmo com a chave correta. Recomendado para integração servidor a servidor.

Limite de uso

120 requisições por minuto por chave. Ao estourar, a API responde 429; espere a virada do minuto e repita. Se precisar de mais, fale com a gente antes de paralelizar.

Nunca coloque a chave no front-end. Ela dá acesso a dados de clientes e, conforme os escopos, movimenta dinheiro. Chamadas partem sempre do seu servidor.

toda chamada

Authorization: Bearer sk_live_SEU_TOKEN
Content-Type: application/json
Idempotency-Key: pedido-8812-v1  # em POST

{
  "erro": {
    "tipo": "forbidden",
    "mensagem": "escopo cobrancas:write ausente"
  }
}

Comece aqui

Idempotência

A rede falha. A garantia de não cobrar duas vezes é sua chave de idempotência.

Todo POST aceita o header Idempotency-Key. Se você repetir a mesma chave, a API não cria de novo: devolve a resposta original.

Isso resolve o pior caso da integração de pagamentos: você manda a cobrança, a conexão cai antes da resposta chegar, e você não sabe se criou ou não. Com a chave, é só repetir — se já existia, você recebe o mesmo resultado.

Como escolher a chave

Use algo que identifique a intenção no seu sistema, não algo aleatório. O número do pedido no seu ERP é uma boa chave. uuid() gerado na hora do envio é uma chave ruim — muda a cada retentativa e não protege nada.

Regra prática: se você reenviar a requisição, a chave precisa ser exatamente a mesma. Se for uma cobrança realmente nova, precisa ser diferente.

# 1ª tentativa — a conexão caiu,
# você não sabe se criou
curl -X POST .../v1/cobrancas \
  -H "Idempotency-Key: erp-8812" \
  -d '{...}'
curl: (52) empty reply from server

# 2ª tentativa — MESMA chave
curl -X POST .../v1/cobrancas \
  -H "Idempotency-Key: erp-8812" \
  -d '{...}'

# devolve a cobrança já criada,
# sem criar uma segunda
{ "id": "cob_2a91...", "status": "aberta" }

Comece aqui

Erros

Todo erro tem o mesmo formato e um tipo estável para você tratar em código.

Trate pelo tipo, nunca pelo texto da mensagem — a mensagem pode melhorar com o tempo, o tipo não muda.

HTTP	Tipo	O que fazer
400	invalid_request	Corrija o corpo. A mensagem diz o campo
401	unauthorized	Chave ausente, inválida ou revogada
403	forbidden	Falta o escopo, ou o IP não está autorizado
404	not_found	Recurso não existe ou é de outra empresa
409	conflict	Estado incompatível (ex.: cancelar cobrança paga)
429	rate_limited	Passou de 120/min. Espere a virada do minuto
500	internal_error	Nosso lado. Repita com a mesma Idempotency-Key

404 é proposital em recurso de outra empresa. A API não confirma nem nega a existência de dado que não é seu — responde como se não existisse.

Retentativa

Repita em 429, 500, 502, 503 e timeout, com espera crescente (1s, 2s, 4s…) e sempre a mesma Idempotency-Key. Não repita em 400, 401, 403 e 404 — repetir não muda o resultado.

{
  "erro": {
    "tipo": "invalid_request",
    "mensagem": "valor_centavos deve ser inteiro",
    "detalhe": "recebido: 149.90"
  }
}

Fluxos

Como o split funciona

Split é repartir uma venda entre a empresa e seus parceiros. Existem dois caminhos, e escolher o errado é o engano mais comum.

O vocabulário

Três entidades, e vale fixá-las antes de escrever código:

Entidade	O que é
Parceiro	Quem recebe parte da venda — o profissional, o prestador, a franquia
Item de split	Um serviço do seu catálogo com preço e a comissão percentual do parceiro
Rateio	A perna concreta: quanto vai para quem, naquela venda

A pergunta que decide o caminho é uma só: você sabe o rateio antes de receber o dinheiro?

Caminho 1 — split na cobrança

Você já sabe o rateio antes de cobrar. Monte o catálogo de itens de split e passe itens ao criar a cobrança. O rateio é calculado a partir do catálogo e executado sozinho quando o pagamento entra — você não chama mais nada.

É o caminho da clínica que agenda a consulta sabendo qual profissional atende. Prefira este sempre que for possível: menos chamadas, menos estado para você guardar e nenhuma janela em que o dinheiro está parado esperando alguém decidir.

Caminho 2 — split manual

A venda já foi capturada — na maquininha, por exemplo — e só depois alguém decide o rateio. Crie um rascunho de split sobre a transação, ajuste à vontade e confirme.

É o caminho do salão que passa o cartão e depois divide entre os profissionais que atenderam. O rascunho existe justamente para essa conversa acontecer sem risco: enquanto não confirmar, nada saiu do lugar.

Confirmar é irreversível. O rascunho pode ser editado e excluído; depois do /confirmar o rateio entra na fila e vai para a adquirente. Não existe "desconfirmar".

A confirmação é assíncrona

POST /v1/splits/{id}/confirmar responde 202, não 200. Isso quer dizer "aceitei e coloquei na fila", não "já está feito na adquirente". Acompanhe pelo GET /v1/splits/{id}, que reflete o estado real da execução.

Quem trata 202 como conclusão acaba mostrando ao usuário um split que ainda pode falhar. Espere o estado final.

Comissão é sempre percentual

No catálogo de itens, a comissão é percentual do valor do item — nunca valor fixo. Comissão zero é legítima: significa que aquele item não reparte (o dono fica com tudo).

# o rateio sai do catálogo de itens
curl -X POST .../v1/cobrancas \
  -H "Idempotency-Key: erp-8812" \
  -d '{
    "cliente_id": "cli_7f3a...",
    "metodo": "pix",
    "vencimento": "2026-09-10",
    "itens": [
      { "item_split_id": "itm_9c2...",
        "quantity": 1 }
    ]
  }'

# valor e rateio vêm do item;
# a perna do parceiro executa
# sozinha quando o PIX entrar

# 1) rascunho sobre transação capturada
curl -X POST .../v1/splits \
  -d '{
    "transacao_id": "trx_31bd...",
    "rateios": [
      { "parceiro_id": "prc_04a...",
        "valor_centavos": 6000 }
    ]
  }'

# 2) confirma → 202 Accepted
curl -X POST .../v1/splits/spl_88.../confirmar

# 3) acompanhe o estado REAL
curl .../v1/splits/spl_88...

Caminho 1 — o rateio já vai junto da cobrança

O catálogo carrega o preço e a comissão. Você referencia o item, e o rateio acontece sozinho no momento em que o pagamento entra — sem nenhuma chamada sua depois.

Caminho 2 — rascunho, e só depois confirma

Tudo à esquerda da linha laranja é reversível: edite e exclua à vontade. Passou do /confirmar, o rateio entrou na fila e vai para a adquirente — não existe "desconfirmar".

O 202 é a parte que mais engana. Ele significa "aceitei e enfileirei", não "está feito na adquirente". Quem trata 202 como conclusão mostra ao usuário um split que ainda pode falhar — sempre confirme pelo GET.

Fluxos

Assinaturas e recorrência

Você cria uma vez. A PayVip gera a cobrança de cada ciclo, no vencimento, sem você chamar nada.

Assinatura não é cobrança

Vale separar bem, porque é a confusão mais comum:

Conceito	O que é
Assinatura	A regra: quem paga, quanto, com que frequência. Existe uma só, e dura
Cobrança	A ocorrência de um ciclo. Nasce uma a cada período
Fatura	O documento pagável daquela cobrança — link, boleto, PIX

Cancelar uma cobrança não encerra a assinatura: no ciclo seguinte nasce outra. Para parar de verdade, pause a assinatura.

Como criar

Não existe endpoint POST /v1/assinaturas. A assinatura nasce quando você cria uma cobrança com o campo recorrente — informando a frequência e o intervalo. A partir daí ela é sua âncora: liste por GET /v1/assinaturas, pause e reative pelo id.

Por que assim? Porque a primeira cobrança e a regra de repetição nascem do mesmo ato de vontade. Separar em duas chamadas criaria uma janela onde existe assinatura sem cobrança — e alguém acabaria pagando duas vezes o primeiro mês.

Pausar e reativar

POST /v1/assinaturas/{id}/pausar interrompe a geração dos próximos ciclos. O que já foi gerado continua valendo: fatura em aberto segue pagável e ainda vence. Pausar não é estornar.

/reativar volta a gerar a partir do próximo vencimento. A API não emite retroativamente os ciclos do período pausado — se você precisa cobrar o intervalo, crie uma cobrança avulsa.

Com split

Assinatura aceita itens igual à cobrança avulsa. O rateio é recalculado e executado a cada ciclo, com a comissão vigente no catálogo naquele momento — não com a do dia em que você assinou. Mudou a comissão do item, o ciclo seguinte já sai diferente.

O campo tem_split na listagem diz quais assinaturas repartem.

curl -X POST .../v1/cobrancas \
  -H "Idempotency-Key: assin-4471" \
  -d '{
    "cliente_id": "cli_7f3a...",
    "valor_centavos": 9900,
    "metodo": "boleto",
    "vencimento": "2026-09-10",
    "recorrente": {
      "frequencia": "monthly",
      "intervalo": 1
    }
  }'

# a 1ª cobrança nasce agora;
# as próximas, a cada mês

# para de gerar os próximos ciclos
curl -X POST \
  .../v1/assinaturas/asn_31c.../pausar

# faturas JÁ geradas continuam
# pagáveis e ainda vencem

# volta a gerar do próximo
# vencimento em diante
curl -X POST \
  .../v1/assinaturas/asn_31c.../reativar

O ciclo de uma assinatura

A assinatura é a regra que fica girando. Cada volta produz uma cobrança independente, com sua própria fatura e seu próprio evento.

Fluxos

Cartões de teste

Exercite o fluxo de cartão de ponta a ponta sem que a transação seja liquidada.

Os cartões abaixo são reconhecidos pela adquirente e não liquidam: percorrem autorização, resposta e webhook como uma venda real, mas nenhum dinheiro se move.

Você continua em produção. A cobrança, o cliente e o pedido criados no teste são registros reais e aparecem no console. Use dados de teste no cadastro e cancele depois o que não for válido.

Aprovam

Número	Bandeira
4539 0033 7072 5497	Visa (digitada)
4761 3400 0000 0035	Visa (chip & PIN)
4716 5888 3636 2104	Visa (crédito)
4532 6501 0413 7832	Visa Electron (crédito)
5356 0663 2027 1893	MasterCard (digitada)
5201 5610 5002 4014	MasterCard (chip & PIN)
5577 2700 0428 6630	MasterCard (crédito)
5138 6920 3612 5449	MasterCard (crédito)

Recusam — teste o caminho triste

Integração boa é a que trata a recusa bem. Use estes para conferir a mensagem que o seu sistema mostra ao cliente.

Número	Resposta esperada
6011 4578 1994 0087	`card_declined`
4929 7104 2663 7678	`card_declined`
4710 4267 4321 6178	`service_request_timeout`

Validade e CVV: use qualquer data futura e qualquer CVV de 3 dígitos. O que determina o resultado é o número do cartão.

Lista mantida pela adquirente (Zoop). Em caso de divergência, a documentação dela prevalece.

o que seu código recebe

{
  "erro": {
    "tipo": "card_declined",
    "mensagem": "cartão recusado pelo emissor"
  }
}

# trate pelo tipo e mostre algo
# acionável para o cliente —
# "tente outro cartão", não
# "erro 402 na transação"

Eventos

Webhooks

Em vez de perguntar "já pagou?", seja avisado quando pagar.

Registre uma URL e escolha os eventos. A cada acontecimento a PayVip envia um POST com o corpo do evento.

Eventos disponíveis

Evento	Quando dispara
cobranca.criada	Cobrança criada com sucesso
cobranca.paga	Pagamento confirmado — o dinheiro entrou
cobranca.vencida	Passou do vencimento sem pagamento
cobranca.cancelada	Cobrança cancelada
assinatura.criada	Nova recorrência ativa
nfse.emitida	Nota fiscal de serviço emitida

Segredo de assinatura

Ao registrar, você recebe um segredo whsec_… — mostrado uma única vez. Use-o para conferir que o POST veio mesmo da PayVip antes de processar.

Endpoint de webhook é público. Sem validar a assinatura, qualquer um que descubra sua URL pode forjar um "cobranca.paga" e liberar serviço não pago.

Boas práticas

Responda 200 rápido e processe depois. Trabalho pesado dentro do handler causa timeout e retentativa.
Espere receber o mesmo evento mais de uma vez. Guarde o id do evento já processado e ignore repetição.
Não confie na ordem. cobranca.paga pode chegar antes de cobranca.criada.

curl -X POST .../v1/webhooks \
  -d '{
    "url": "https://seu-erp.com/payvip",
    "eventos": ["cobranca.paga",
                 "cobranca.vencida"]
  }'

{
  "id": "whk_1f88...",
  "segredo": "whsec_a91c..."  // só agora
}

POST /payvip  (no SEU servidor)

{
  "evento": "cobranca.paga",
  "id": "evt_66d2...",
  "criado_em": "2026-09-10T14:22:07Z",
  "dados": {
    "cobranca_id": "cob_2a91...",
    "valor_centavos": 14990,
    "pago_em": "2026-09-10T14:22:05Z"
  }
}

Carregando a referência…