API docs by Redocly

Vitorio Payments API (0.0.1)

Download OpenAPI specification:

Public API for Vitorio payments.

Charge

Uma Charge representa uma cobrança (de 1 a N parcelas) emitida pela sua empresa ou por um dos seus clientes. Toda cobrança via API começa por aqui.

Fluxo geral

POST /v1/charges    -->  Charge criada (status: PENDING)
                              |
                       Registro junto ao BaaS
                              |
                              v
                          Charge ACTIVE  +  N Payments PENDING
                              |
                     Pagador efetua os pagamentos
                              |
                              v
                       Todos os Payments COMPLETED
                              |
                              v
                          Charge COMPLETED

Quem emite (issuer) × quem paga (payer)

Issuer Payer Quando usar
TENANT CUSTOMER Sua empresa cobra um cliente cadastrado (payer_customer_id).
CUSTOMER ANONYMOUS Seu cliente cobra um pagador externo, informado inline (anonymous_payer).

Para emissão pelo TENANT, omita o bloco issuer_customer_id. Para emissão por um CUSTOMER, informe issuer_customer_id com o UUID do cliente emissor.

Métodos de pagamento

A API suporta PIX e BOLETO. Configure via pix_config ou boleto_config (mutuamente exclusivos), conforme o payment_method informado.

Operações disponíveis

Operação Endpoint
Criar uma Charge com N parcelas POST /v1/charges
Listar Charges do tenant (paginado) GET /v1/charges
Detalhar uma Charge com suas parcelas GET /v1/charges/{charge_id}
Cancelar uma Charge e todas as parcelas pendentes DELETE /v1/charges/{charge_id}

Para cancelar uma única parcela sem afetar as demais, use DELETE /v1/payments/{payment_id} (veja Payment).

Pre-requisitos: Customer cadastrado e conta ativa para o emissor (tenant ou customer-issuer, conforme o caso).

List Charges

Lista as cobranças do tenant autenticado

Authorizations:
Vitorio API Key
query Parameters
page
integer <int32>

Número da página (padrão: 1)

pageSize
integer <int32>

Tamanho da página (padrão: 10, máx: 50)

status
string

Filtra por status da cobrança

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create Charge

Cria uma nova cobrança com parcelas

Authorizations:
Vitorio API Key
Request Body schema: application/json
required
issuerCustomerId
string

UUID do cliente emissor — definido para cobranças emitidas pelo CUSTOMER; omita para cobranças emitidas pelo TENANT

subtotalCents
required
string

Subtotal da cobrança em centavos (deve ser > 0)

installments
required
integer <int32>

Número de parcelas (>= 1)

paymentMethod
required
string
Enum: "PIX" "BOLETO"

Método de pagamento

dueDate
required
string

Data de vencimento da primeira parcela (YYYY-MM-DD)

externalId
required
string

Identificador da cobrança do cliente

object

Configuração de pagamento PIX (obrigatória quando payment_method é PIX)

object

Configuração de pagamento do boleto (obrigatória quando payment_method é BOLETO)

payerCustomerId
string

UUID do cliente pagador — definido para pagadores CUSTOMER

object

Detalhes do pagador inline — definido para pagadores ANONYMOUS (apenas CUSTOMER -> ANONYMOUS)

Responses

Request samples

Content type
application/json
Example

Seu cliente cobra um pagador externo via boleto. Informe issuerCustomerId e os dados do pagador em anonymousPayer (nome, CPF e endereço completos). Cobrança parcelada em 3x.

{
  • "issuerCustomerId": "550e8400-e29b-41d4-a716-446655440000",
  • "subtotalCents": 180000,
  • "installments": 3,
  • "paymentMethod": "BOLETO",
  • "dueDate": "2026-06-15",
  • "externalId": "ORD-BOLETO-3X-001",
  • "anonymousPayer": {
    },
  • "boletoConfig": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Charge Details

Obtém os detalhes da cobrança com as parcelas

Authorizations:
Vitorio API Key
path Parameters
chargeId
required
string

ID da cobrança (formato UUID)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Cancel Charge

Cancela uma cobrança e todas as suas parcelas pendentes

Authorizations:
Vitorio API Key
path Parameters
chargeId
required
string

ID da cobrança (formato UUID)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Customer

O cadastro de clientes é o primeiro passo para utilizar a API da Vitorio. Um Customer representa uma pessoa jurídica (PJ) que será associada a contas e cobranças.

Fluxo

POST /v1/customers  -->  Customer criado (status: ACTIVE)

Orientações

  1. Envie os dados cadastrais via POST /v1/customers.
  2. O customer_id retornado será usado na criação de cobranças (Charge).
  3. Para atualizar dados cadastrais, use PATCH /v1/customers/{id}.

Próximo passo: Com o cliente cadastrado, crie uma cobrança seguindo o fluxo de Charge.

Create Customer

Cria um novo cliente. Este endpoint deve ser utilizado apenas para cadastrar clientes diretos da sua empresa. Clientes dos seus clientes não devem ser registrados. Telefone é obrigatório caso voce pretenda abrir uma conta bancária para o cliente eventualmente.

Authorizations:
Vitorio API Key
Request Body schema: application/json
required
name
required
string
taxId
required
string

CPF (11 dígitos) ou CNPJ (14 dígitos).

externalId
string
phone
string
required
object (customers.v1.Address)

Responses

Request samples

Content type
application/json

Exemplo de criação de cliente pessoa jurídica (CNPJ) com endereço completo

{
  • "name": "Tech Solutions Ltda",
  • "taxId": "12345678000190",
  • "externalId": "CUST-PJ-001",
  • "phone": "+5511933334444",
  • "address": {
    }
}

Response samples

Content type
application/json
{ }

Delete Customer

DeleteCustomer exclui um cliente

Authorizations:
Vitorio API Key
path Parameters
customerId
required
string

Responses

Update Customer

Atualiza um cliente existente

Authorizations:
Vitorio API Key
path Parameters
customerId
required
string
Request Body schema: application/json
required
name
string
externalId
string
phone
string
object (customers.v1.Address)

Responses

Request samples

Content type
application/json

Exemplo de atualização parcial do nome e telefone de um cliente existente

{
  • "name": "Ana Paula Ferreira Santos",
  • "phone": "+5511912345678"
}

Response samples

Content type
application/json
{ }

Payment

Um Payment representa uma parcela de uma cobrança.

Download Boleto PDF

Baixa o PDF do boleto para um pagamento especificado

Authorizations:
Vitorio API Key
path Parameters
paymentId
required
string

ID do pagamento (UUID)

Responses

Response samples

Content type
application/json
{
  • "pdfContent": "string"
}