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 — uma Charge de 1 parcela substitui o conceito anterior de "pagamento avulso".

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 — a conta receptora é resolvida 1:1 a partir do 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 Account ativa para o emissor (tenant ou customer-issuer, conforme o caso).

Create Charge

Create a new charge with installments

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

Issuer customer UUID — set for CUSTOMER-issued charges; omit for TENANT-issued charges

subtotalCents
required
string

Charge subtotal in cents (must be > 0)

installments
required
integer <int32>

Number of installments (>= 1)

paymentMethod
required
string
Enum: "PIX" "BOLETO"

Payment method

dueDate
required
string

First installment due date (YYYY-MM-DD)

externalId
required
string

Client's charge identifier

object

PIX payment configuration (required when payment_method is PIX)

object

Boleto payment configuration (required when payment_method is BOLETO)

payerCustomerId
string

Payer customer UUID — set for CUSTOMER payers

object

Inline payer details — set for ANONYMOUS payers (CUSTOMER -> ANONYMOUS only)

Responses

Request samples

Content type
application/json
{
  • "issuerCustomerId": "550e8400-e29b-41d4-a716-446655440000",
  • "subtotalCents": 50000,
  • "installments": 1,
  • "paymentMethod": "PIX",
  • "dueDate": "2026-03-01",
  • "externalId": "ORD-12345",
  • "pixConfig": {
    },
  • "boletoConfig": {
    },
  • "payerCustomerId": "660e8400-e29b-41d4-a716-446655440001",
  • "anonymousPayer": {
    }
}

Response samples

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

Get Charge Details

Get charge details with installments

Authorizations:
Vitorio API Key
path Parameters
chargeId
required
string

Charge ID (UUID format)

Responses

Response samples

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

Cancel Charge

Cancel a charge and all its pending installments

Authorizations:
Vitorio API Key
path Parameters
chargeId
required
string

Charge ID (UUID format)

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 física (PF) ou 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 (Order).
  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 e endereço são obrigatórios caso voce pretenda abrir uma conta para o cliente.

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
{
  • "name": "John Doe",
  • "taxId": "12345678901",
  • "externalId": "CUST-001",
  • "phone": "+5511999999999",
  • "address": {
    }
}

Response samples

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

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
{
  • "name": "John Doe Updated",
  • "externalId": "string",
  • "phone": "string",
  • "address": {
    }
}

Response samples

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

Payment

Payment provides payment-related operations.

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"
}