API de Cobranças Pix e Boleto - Documentação

GET /account

Consultar sua conta

Retorna se sua conta já está pronta pra emitir cobrança, e as taxas combinadas por método de pagamento.

curl -X GET https://jovpay.com/api/v1/account \
  -H "Authorization: Bearer SEU_TOKEN"

$response = Http::withToken('SEU_TOKEN')
    ->get('https://jovpay.com/api/v1/account');

const res = await fetch("https://jovpay.com/api/v1/account", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  }
});

import requests

response = requests.get(
    "https://jovpay.com/api/v1/account",
    headers={"Authorization": "Bearer SEU_TOKEN"}
)

Testar agora

Respostas

200 OK

{
    "company_name": "Minha Empresa LTDA",
    "account_status": "approved",
    "account_active": true,
    "fees": {
        "pix": {
            "percent": 0.99,
            "fixed": 0
        },
        "bank_slip": {
            "percent": 0,
            "fixed": 3.49
        },
        "credit_card": {
            "percent": 3.49,
            "fixed": 0.39
        }
    }
}

401 Token inválido

{
    "message": "Token de autenticação inválido ou ausente."
}

GET /customers

Listar clientes

Lista os clientes cadastrados, paginado.

Query params

page integer Página - padrão 1

curl -X GET https://jovpay.com/api/v1/customers \
  -H "Authorization: Bearer SEU_TOKEN"

$response = Http::withToken('SEU_TOKEN')
    ->get('https://jovpay.com/api/v1/customers');

const res = await fetch("https://jovpay.com/api/v1/customers", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  }
});

import requests

response = requests.get(
    "https://jovpay.com/api/v1/customers",
    headers={"Authorization": "Bearer SEU_TOKEN"}
)

Testar agora

Respostas

200 OK

{
    "data": [
        {
            "id": 42,
            "name": "Maria Silva",
            "document": "12345678900",
            "email": "maria@exemplo.com"
        }
    ],
    "meta": {
        "current_page": 1,
        "total": 1
    }
}

GET /customers/search

Buscar cliente por documento

Busca um cliente específico pelo CPF/CNPJ.

Query params

document string obrigatório CPF ou CNPJ, só números

curl -X GET https://jovpay.com/api/v1/customers/search \
  -H "Authorization: Bearer SEU_TOKEN"

$response = Http::withToken('SEU_TOKEN')
    ->get('https://jovpay.com/api/v1/customers/search');

const res = await fetch("https://jovpay.com/api/v1/customers/search", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  }
});

import requests

response = requests.get(
    "https://jovpay.com/api/v1/customers/search",
    headers={"Authorization": "Bearer SEU_TOKEN"}
)

Testar agora

Respostas

200 OK

{
    "id": 42,
    "name": "Maria Silva",
    "document": "12345678900"
}

404 Não encontrado

{
    "message": "Cliente não encontrado."
}

POST /customers

Criar cliente

Cadastra um novo cliente na sua conta.

Body params

name string obrigatório Nome completo ou razão social

document string obrigatório CPF ou CNPJ, só números

email string E-mail do cliente

phone string Telefone com DDD

street string Rua

number string Número

neighborhood string Bairro

city string Cidade

state string UF

zip string CEP

curl -X POST https://jovpay.com/api/v1/customers \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "document": "12345678900",
    "email": "maria@exemplo.com",
    "phone": "83999998888",
    "street": "Rua Central",
    "number": "100",
    "neighborhood": "Centro",
    "city": "João Pessoa",
    "state": "PB",
    "zip": "58000000"
}'

$response = Http::withToken('SEU_TOKEN')
    ->post('https://jovpay.com/api/v1/customers', array (
  'name' => 'Maria Silva',
  'document' => '12345678900',
  'email' => 'maria@exemplo.com',
  'phone' => '83999998888',
  'street' => 'Rua Central',
  'number' => '100',
  'neighborhood' => 'Centro',
  'city' => 'João Pessoa',
  'state' => 'PB',
  'zip' => '58000000',
));

const res = await fetch("https://jovpay.com/api/v1/customers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"name":"Maria Silva","document":"12345678900","email":"maria@exemplo.com","phone":"83999998888","street":"Rua Central","number":"100","neighborhood":"Centro","city":"João Pessoa","state":"PB","zip":"58000000"})
});

import requests

response = requests.post(
    "https://jovpay.com/api/v1/customers",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    json={"name":"Maria Silva","document":"12345678900","email":"maria@exemplo.com","phone":"83999998888","street":"Rua Central","number":"100","neighborhood":"Centro","city":"João Pessoa","state":"PB","zip":"58000000"}
)

Testar agora

Corpo da requisição - edite os valores antes de mandar

Respostas

201 Criado

{
    "id": 42,
    "name": "Maria Silva",
    "document": "12345678900"
}

422 Dados inválidos

{
    "message": "O campo document já foi utilizado."
}

GET /customers/{id}

Ver cliente

Retorna os dados de um cliente específico.

Path params

id integer ID do cliente

curl -X GET https://jovpay.com/api/v1/customers/{id} \
  -H "Authorization: Bearer SEU_TOKEN"

$response = Http::withToken('SEU_TOKEN')
    ->get('https://jovpay.com/api/v1/customers/{id}');

const res = await fetch("https://jovpay.com/api/v1/customers/{id}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  }
});

import requests

response = requests.get(
    "https://jovpay.com/api/v1/customers/{id}",
    headers={"Authorization": "Bearer SEU_TOKEN"}
)

Testar agora

Respostas

200 OK

{
    "id": 42,
    "name": "Maria Silva"
}

404 Não encontrado

{
    "message": "Cliente não encontrado."
}

PUT /customers/{id}

Atualizar cliente

Atualiza os dados de um cliente existente.

Path params

id integer ID do cliente

Body params

name string Nome

email string E-mail

phone string Telefone

curl -X PUT https://jovpay.com/api/v1/customers/{id} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "novo-email@exemplo.com"
}'

$response = Http::withToken('SEU_TOKEN')
    ->put('https://jovpay.com/api/v1/customers/{id}', array (
  'email' => 'novo-email@exemplo.com',
));

const res = await fetch("https://jovpay.com/api/v1/customers/{id}", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"email":"novo-email@exemplo.com"})
});

import requests

response = requests.put(
    "https://jovpay.com/api/v1/customers/{id}",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    json={"email":"novo-email@exemplo.com"}
)

Testar agora

Corpo da requisição - edite os valores antes de mandar

Respostas

200 OK

{
    "id": 42,
    "name": "Maria Silva",
    "email": "novo-email@exemplo.com"
}

POST /charges

Criar cobrança

Gera uma cobrança nova - Pix, boleto, ou os dois juntos numa fatura só. Se você foi indicado por um parceiro JOV Pay, pode mandar o header opcional "parceiro_token" com o token dele.

Body params

customer_id integer obrigatório ID do cliente

amount number obrigatório Valor da cobrança

discount_amount number Desconto aplicado direto no valor

due_date string obrigatório Vencimento (AAAA-MM-DD)

description string obrigatório Descrição da cobrança

payment_methods array obrigatório "pix", "bank_slip" ou os dois

curl -X POST https://jovpay.com/api/v1/charges \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 42,
    "amount": 150,
    "discount_amount": 10,
    "due_date": "2026-07-20",
    "description": "Mensalidade",
    "payment_methods": [
        "pix",
        "bank_slip"
    ]
}'

$response = Http::withToken('SEU_TOKEN')
    ->post('https://jovpay.com/api/v1/charges', array (
  'customer_id' => 42,
  'amount' => 150.0,
  'discount_amount' => 10.0,
  'due_date' => '2026-07-20',
  'description' => 'Mensalidade',
  'payment_methods' => 
  array (
    0 => 'pix',
    1 => 'bank_slip',
  ),
));

const res = await fetch("https://jovpay.com/api/v1/charges", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"customer_id":42,"amount":150,"discount_amount":10,"due_date":"2026-07-20","description":"Mensalidade","payment_methods":["pix","bank_slip"]})
});

import requests

response = requests.post(
    "https://jovpay.com/api/v1/charges",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    json={"customer_id":42,"amount":150,"discount_amount":10,"due_date":"2026-07-20","description":"Mensalidade","payment_methods":["pix","bank_slip"]}
)

Testar agora

Corpo da requisição - edite os valores antes de mandar

Respostas

201 Criada

{
    "data": [
        {
            "id": 123,
            "payment_method": "pix",
            "pix_code": "00020126...",
            "pix_qrcode_url": "data:image/png;base64,...",
            "pix_pdf_url": "https://.../jovpay/pix/123"
        },
        {
            "id": 124,
            "payment_method": "bank_slip",
            "boleto_url": "https://.../jovpay/boletos/124",
            "boleto_pdf_url": "https://.../jovpay/boletos/124",
            "boleto_barcode": "00190.00009..."
        }
    ]
}

422 Dados inválidos

{
    "message": "O campo due_date é obrigatório."
}

GET /charges

Listar cobranças

Lista as cobranças, paginado.

Query params

page integer Página - padrão 1

curl -X GET https://jovpay.com/api/v1/charges \
  -H "Authorization: Bearer SEU_TOKEN"

$response = Http::withToken('SEU_TOKEN')
    ->get('https://jovpay.com/api/v1/charges');

const res = await fetch("https://jovpay.com/api/v1/charges", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  }
});

import requests

response = requests.get(
    "https://jovpay.com/api/v1/charges",
    headers={"Authorization": "Bearer SEU_TOKEN"}
)

Testar agora

Respostas

200 OK

{
    "data": [
        {
            "id": 123,
            "amount": 150,
            "status": "pending"
        }
    ],
    "meta": {
        "current_page": 1
    }
}

GET /charges/search

Buscar cobranças

Busca cobranças pelo documento ou telefone do cliente.

Query params

document string CPF/CNPJ do cliente

phone string Telefone do cliente

curl -X GET https://jovpay.com/api/v1/charges/search \
  -H "Authorization: Bearer SEU_TOKEN"

$response = Http::withToken('SEU_TOKEN')
    ->get('https://jovpay.com/api/v1/charges/search');

const res = await fetch("https://jovpay.com/api/v1/charges/search", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  }
});

import requests

response = requests.get(
    "https://jovpay.com/api/v1/charges/search",
    headers={"Authorization": "Bearer SEU_TOKEN"}
)

Testar agora

Respostas

200 OK

{
    "data": [
        {
            "id": 123,
            "amount": 150,
            "status": "pending"
        }
    ]
}

GET /charges/{id}

Ver cobrança

Retorna os dados de uma cobrança específica.

Path params

id integer ID da cobrança

curl -X GET https://jovpay.com/api/v1/charges/{id} \
  -H "Authorization: Bearer SEU_TOKEN"

$response = Http::withToken('SEU_TOKEN')
    ->get('https://jovpay.com/api/v1/charges/{id}');

const res = await fetch("https://jovpay.com/api/v1/charges/{id}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  }
});

import requests

response = requests.get(
    "https://jovpay.com/api/v1/charges/{id}",
    headers={"Authorization": "Bearer SEU_TOKEN"}
)

Testar agora

Respostas

200 OK

{
    "id": 123,
    "amount": 150,
    "status": "pending",
    "due_date": "2026-07-20"
}

404 Não encontrada

{
    "message": "Cobrança não encontrada."
}

PUT /charges/{id}

Cancelar cobrança

Cancela essa forma de pagamento específica no gateway. Se a fatura tiver mais de um método pendente e você quiser cancelar tudo, chame esse endpoint uma vez pra cada id retornado na criação.

Path params

id integer ID da cobrança

Body params

status string obrigatório Envie "canceled"

curl -X PUT https://jovpay.com/api/v1/charges/{id} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "canceled"
}'

$response = Http::withToken('SEU_TOKEN')
    ->put('https://jovpay.com/api/v1/charges/{id}', array (
  'status' => 'canceled',
));

const res = await fetch("https://jovpay.com/api/v1/charges/{id}", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"status":"canceled"})
});

import requests

response = requests.put(
    "https://jovpay.com/api/v1/charges/{id}",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    json={"status":"canceled"}
)

Testar agora

Corpo da requisição - edite os valores antes de mandar

Respostas

200 OK

{
    "id": 123,
    "status": "canceled"
}

PUT /charges/{id}

Mudar vencimento

Altera a data de vencimento de uma cobrança pendente.

Path params

id integer ID da cobrança

Body params

due_date string obrigatório Nova data (AAAA-MM-DD)

curl -X PUT https://jovpay.com/api/v1/charges/{id} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "due_date": "2026-08-01"
}'

$response = Http::withToken('SEU_TOKEN')
    ->put('https://jovpay.com/api/v1/charges/{id}', array (
  'due_date' => '2026-08-01',
));

const res = await fetch("https://jovpay.com/api/v1/charges/{id}", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"due_date":"2026-08-01"})
});

import requests

response = requests.put(
    "https://jovpay.com/api/v1/charges/{id}",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    json={"due_date":"2026-08-01"}
)

Testar agora

Corpo da requisição - edite os valores antes de mandar

Respostas

200 OK

{
    "id": 123,
    "due_date": "2026-08-01"
}

POST /installment-plans

Criar carnê

Cria o carnê, sem gerar nenhuma parcela ainda (esse é o padrão - auto_generate=false). Depois, crie cada parcela na hora que quiser com o endpoint abaixo. Se preferir que a gente gere tudo sozinho em segundo plano, manda auto_generate=true.

Body params

customer_id integer obrigatório ID do cliente

description string obrigatório Descrição do carnê

total_amount number obrigatório Valor total, dividido entre as parcelas

discount_amount number Desconto por pontualidade (R$), aplicado em cada parcela se pago até o vencimento dela

installments_count integer obrigatório Quantidade de parcelas (2 a 60)

first_due_date string obrigatório Vencimento da 1ª parcela (AAAA-MM-DD) - as demais vencem um mês depois, sempre

payment_methods array obrigatório "pix", "bank_slip", "credit_card" ou combinação - vale pra todas as parcelas

charge_interest boolean Cobrar multa/juros por atraso

interest_percent number Juros ao mês (%)

late_payment_fine_percent number Multa por atraso (%)

auto_generate boolean false (padrão) cria só o carnê, sem nenhuma parcela - você cria uma por uma. true gera tudo sozinho em segundo plano

curl -X POST https://jovpay.com/api/v1/installment-plans \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 42,
    "description": "Instalação + mensalidades",
    "total_amount": 1200,
    "installments_count": 6,
    "first_due_date": "2026-08-10",
    "payment_methods": [
        "pix",
        "bank_slip"
    ],
    "charge_interest": true,
    "interest_percent": 1,
    "late_payment_fine_percent": 2
}'

$response = Http::withToken('SEU_TOKEN')
    ->post('https://jovpay.com/api/v1/installment-plans', array (
  'customer_id' => 42,
  'description' => 'Instalação + mensalidades',
  'total_amount' => 1200.0,
  'installments_count' => 6,
  'first_due_date' => '2026-08-10',
  'payment_methods' => 
  array (
    0 => 'pix',
    1 => 'bank_slip',
  ),
  'charge_interest' => true,
  'interest_percent' => 1.0,
  'late_payment_fine_percent' => 2.0,
));

const res = await fetch("https://jovpay.com/api/v1/installment-plans", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"customer_id":42,"description":"Instalação + mensalidades","total_amount":1200,"installments_count":6,"first_due_date":"2026-08-10","payment_methods":["pix","bank_slip"],"charge_interest":true,"interest_percent":1,"late_payment_fine_percent":2})
});

import requests

response = requests.post(
    "https://jovpay.com/api/v1/installment-plans",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    json={"customer_id":42,"description":"Instalação + mensalidades","total_amount":1200,"installments_count":6,"first_due_date":"2026-08-10","payment_methods":["pix","bank_slip"],"charge_interest":true,"interest_percent":1,"late_payment_fine_percent":2}
)

Testar agora

Corpo da requisição - edite os valores antes de mandar

Respostas

202 Aceito

{
    "message": "Carnê criado sem parcelas ainda - chame POST /installment-plans/{id}/installments uma vez pra cada parcela (1 a 6).",
    "data": {
        "id": 10,
        "status": "active",
        "generation_complete": false,
        "installments_count": 6
    }
}

422 Dados inválidos

{
    "message": "Esse cliente não tem o endereço completo cadastrado - é exigido pra emitir boleto."
}

POST /installment-plans/{id}/installments

Criar uma parcela específica

Cria e já gera no gateway UMA parcela específica do carnê (identificada pelo número) - pensado pra quem prefere montar o carnê chamando isso uma vez pra cada parcela (1, 2, 3...), no estilo de outras APIs bancárias, em vez de deixar tudo por conta da geração automática. Cada chamada é rápida, já que só processa uma parcela. Precisa que o carnê tenha sido criado com auto_generate=false.

Path params

id integer ID do carnê

Body params

installment_number integer obrigatório Número dessa parcela (1 até o total de parcelas do carnê)

amount number Valor dessa parcela - se não informar, calcula automático dividindo o total

due_date string Vencimento dessa parcela (AAAA-MM-DD) - se não informar, calcula automático a partir da 1ª parcela

curl -X POST https://jovpay.com/api/v1/installment-plans/{id}/installments \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "installment_number": 1
}'

$response = Http::withToken('SEU_TOKEN')
    ->post('https://jovpay.com/api/v1/installment-plans/{id}/installments', array (
  'installment_number' => 1,
));

const res = await fetch("https://jovpay.com/api/v1/installment-plans/{id}/installments", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"installment_number":1})
});

import requests

response = requests.post(
    "https://jovpay.com/api/v1/installment-plans/{id}/installments",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    json={"installment_number":1}
)

Testar agora

Corpo da requisição - edite os valores antes de mandar

Respostas

201 Criada

{
    "data": {
        "installment_plan_id": 10,
        "installment_number": 1,
        "charges": [
            {
                "payment_method": "pix",
                "generated": true,
                "pix_code": "00020126...",
                "pix_pdf_url": "https://.../jovpay/pix/456",
                "checkout_url": "https://.../jovpay/checkout/..."
            }
        ]
    }
}

422 Dados inválidos

{
    "message": "A parcela 1 já foi criada nesse carnê."
}

PUT /installment-plans/{id}/installments/{number}

Editar uma parcela específica

Edita valor, vencimento e/ou formas de pagamento de UMA parcela. Se ela já tinha sido gerada no gateway e algo mudou, a cobrança antiga é cancelada e uma nova é criada (o link de pagamento muda). Uma parcela já paga não pode ser editada.

Path params

id integer ID do carnê

number integer Número da parcela

Body params

amount number Novo valor dessa parcela

due_date string Novo vencimento (AAAA-MM-DD)

payment_methods array Novas formas de pagamento - substitui as atuais (desmarcar cancela, marcar nova cria)

curl -X PUT https://jovpay.com/api/v1/installment-plans/{id}/installments/{number} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150,
    "due_date": "2026-09-15"
}'

$response = Http::withToken('SEU_TOKEN')
    ->put('https://jovpay.com/api/v1/installment-plans/{id}/installments/{number}', array (
  'amount' => 150.0,
  'due_date' => '2026-09-15',
));

const res = await fetch("https://jovpay.com/api/v1/installment-plans/{id}/installments/{number}", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"amount":150,"due_date":"2026-09-15"})
});

import requests

response = requests.put(
    "https://jovpay.com/api/v1/installment-plans/{id}/installments/{number}",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    json={"amount":150,"due_date":"2026-09-15"}
)

Testar agora

Corpo da requisição - edite os valores antes de mandar

Respostas

200 OK

{
    "data": {
        "installment_plan_id": 10,
        "installment_number": 1,
        "charges": [
            {
                "payment_method": "pix",
                "amount": 150,
                "due_date": "2026-09-15",
                "generated": true,
                "pix_code": "00020126..."
            }
        ]
    }
}

422 Dados inválidos

{
    "message": "Essa parcela já foi paga - não dá pra editar."
}

GET /installment-plans

Listar carnês

Lista os carnês, paginado.

Query params

page integer Página - padrão 1

curl -X GET https://jovpay.com/api/v1/installment-plans \
  -H "Authorization: Bearer SEU_TOKEN"

$response = Http::withToken('SEU_TOKEN')
    ->get('https://jovpay.com/api/v1/installment-plans');

const res = await fetch("https://jovpay.com/api/v1/installment-plans", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  }
});

import requests

response = requests.get(
    "https://jovpay.com/api/v1/installment-plans",
    headers={"Authorization": "Bearer SEU_TOKEN"}
)

Testar agora

Respostas

200 OK

{
    "data": [
        {
            "id": 10,
            "description": "Instalação + mensalidades",
            "installments_count": 6,
            "status": "active"
        }
    ]
}

GET /installment-plans/{id}

Ver carnê

Retorna o carnê com todas as parcelas, cada uma com o Pix/boleto já gerado.

Path params

id integer ID do carnê

curl -X GET https://jovpay.com/api/v1/installment-plans/{id} \
  -H "Authorization: Bearer SEU_TOKEN"

$response = Http::withToken('SEU_TOKEN')
    ->get('https://jovpay.com/api/v1/installment-plans/{id}');

const res = await fetch("https://jovpay.com/api/v1/installment-plans/{id}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  }
});

import requests

response = requests.get(
    "https://jovpay.com/api/v1/installment-plans/{id}",
    headers={"Authorization": "Bearer SEU_TOKEN"}
)

Testar agora

Respostas

200 OK

{
    "data": {
        "id": 10,
        "installments": [
            {
                "installment_number": 1,
                "due_date": "2026-08-10",
                "amount": 200,
                "status": "pending",
                "charges": [
                    {
                        "payment_method": "pix",
                        "pix_code": "00020126...",
                        "pix_pdf_url": "https://.../jovpay/pix/456"
                    },
                    {
                        "payment_method": "bank_slip",
                        "boleto_url": "https://.../jovpay/boletos/457",
                        "boleto_pdf_url": "https://.../jovpay/boletos/457"
                    }
                ]
            }
        ]
    }
}

PUT /installment-plans/{id}

Editar descrição do carnê

Só a descrição pode ser editada - valor, parcelas e vencimentos já viraram cobranças reais no gateway. Pra mudar isso, cancele e crie um carnê novo.

Path params

id integer ID do carnê

Body params

description string Nova descrição

curl -X PUT https://jovpay.com/api/v1/installment-plans/{id} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Novo texto"
}'

$response = Http::withToken('SEU_TOKEN')
    ->put('https://jovpay.com/api/v1/installment-plans/{id}', array (
  'description' => 'Novo texto',
));

const res = await fetch("https://jovpay.com/api/v1/installment-plans/{id}", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"description":"Novo texto"})
});

import requests

response = requests.put(
    "https://jovpay.com/api/v1/installment-plans/{id}",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    json={"description":"Novo texto"}
)

Testar agora

Corpo da requisição - edite os valores antes de mandar

Respostas

200 OK

{
    "data": {
        "id": 10,
        "description": "Novo texto"
    }
}

POST /installment-plans/{id}/cancel-remaining

Cancelar parcelas pendentes

Cancela no gateway e marca como canceladas todas as parcelas ainda pendentes - as já pagas continuam intactas.

Path params

id integer ID do carnê

curl -X POST https://jovpay.com/api/v1/installment-plans/{id}/cancel-remaining \
  -H "Authorization: Bearer SEU_TOKEN"

$response = Http::withToken('SEU_TOKEN')
    ->post('https://jovpay.com/api/v1/installment-plans/{id}/cancel-remaining');

const res = await fetch("https://jovpay.com/api/v1/installment-plans/{id}/cancel-remaining", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  }
});

import requests

response = requests.post(
    "https://jovpay.com/api/v1/installment-plans/{id}/cancel-remaining",
    headers={"Authorization": "Bearer SEU_TOKEN"}
)

Testar agora

Respostas

200 OK

{
    "message": "4 parcela(s) pendente(s) cancelada(s)."
}

DELETE /installment-plans/{id}

Apagar carnê

Cancela no gateway as parcelas pendentes e apaga o carnê e as cobranças dele. Não tem como desfazer.

Path params

id integer ID do carnê

curl -X DELETE https://jovpay.com/api/v1/installment-plans/{id} \
  -H "Authorization: Bearer SEU_TOKEN"

$response = Http::withToken('SEU_TOKEN')
    ->delete('https://jovpay.com/api/v1/installment-plans/{id}');

const res = await fetch("https://jovpay.com/api/v1/installment-plans/{id}", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
  }
});

import requests

response = requests.delete(
    "https://jovpay.com/api/v1/installment-plans/{id}",
    headers={"Authorization": "Bearer SEU_TOKEN"}
)

Testar agora

Respostas

200 OK

{
    "message": "Carnê apagado - parcelas pendentes foram canceladas no gateway."
}

WEBHOOK charge.status_changed

Status da cobrança mudou

Enviado pro seu endpoint configurado sempre que uma cobrança muda de status (ex: foi paga).

Exemplo de payload enviado pra sua URL de webhook

{
    "event": "charge.status_changed",
    "created_at": "2026-07-11T12:00:00-03:00",
    "data": {
        "charge_id": 123,
        "public_token": "...",
        "status": "paid"
    }
}

WEBHOOK charge.invoice_atualized

Dados de pagamento atualizados

Enviado quando o Pix/boleto de uma fatura é atualizado (o link de pagamento continua o mesmo).

Exemplo de payload enviado pra sua URL de webhook

{
    "event": "charge.invoice_atualized",
    "created_at": "2026-07-11T12:00:00-03:00",
    "data": {
        "charge_id": 123,
        "public_token": "...",
        "payment_method": "pix",
        "pix_code": "00020126..."
    }
}

WEBHOOK installment_plan.completed

Carnê terminou de ser gerado

Enviado quando todas as parcelas de um carnê terminaram de ser processadas no gateway (com sucesso ou erro) - assim você não precisa ficar consultando GET /installment-plans/{id} repetidamente.

Exemplo de payload enviado pra sua URL de webhook

{
    "event": "installment_plan.completed",
    "created_at": "2026-07-11T12:00:00-03:00",
    "data": {
        "installment_plan_id": 10,
        "description": "Instalação + mensalidades",
        "installments_count": 6,
        "installments": [
            {
                "installment_number": 1,
                "due_date": "2026-08-10",
                "amount": 200,
                "charges": [
                    {
                        "payment_method": "pix",
                        "generated": true,
                        "pix_code": "00020126...",
                        "pix_pdf_url": "https://.../jovpay/pix/456",
                        "checkout_url": "https://.../jovpay/checkout/..."
                    }
                ]
            }
        ]
    }
}

Conta

Clientes

Cobranças

Carnê

Webhooks

API JovPay

Autenticação

Token de parceiro (opcional)

Conta

Consultar sua conta

Clientes

Listar clientes

Buscar cliente por documento

Criar cliente

Ver cliente

Atualizar cliente

Cobranças

Criar cobrança

Listar cobranças

Buscar cobranças

Ver cobrança

Cancelar cobrança

Mudar vencimento

Carnê

Criar carnê

Criar uma parcela específica

Editar uma parcela específica

Listar carnês

Ver carnê

Editar descrição do carnê

Cancelar parcelas pendentes

Apagar carnê

Webhooks

Status da cobrança mudou

Dados de pagamento atualizados

Carnê terminou de ser gerado