API docs by Redocly

Vitorio Payments API (0.0.1)

Download OpenAPI specification:

Public API for Vitorio payments.

Account

Uma Account representa uma conta de pagamento vinculada a um cliente. Antes de criar uma conta, o cliente ja deve estar cadastrado (veja Customer).

Fluxo de abertura

POST /v1/customers          POST /v1/accounts
     |                           |
     v                           v
 Customer criado  --------> Conta criada (PENDING)
                                 |
                        GET /v1/accounts/{id}
                          (poll status)
                                 |
                                 v
                          Conta ACTIVE
  1. Crie o cliente via POST /v1/customers (se ainda não existir).
  2. Crie a conta via POST /v1/accounts informando o customer_id.
  3. A conta inicia com status PENDING enquanto o onboarding e processado.
  4. Consulte GET /v1/accounts/{id} ate o status mudar para ACTIVE.

Ciclo de vida da conta

PENDING ---> ACTIVE <---> INACTIVE ---> CLOSED
Transicao Endpoint
ACTIVE -> INACTIVE POST /v1/accounts/{id}/deactivate
INACTIVE -> ACTIVE POST /v1/accounts/{id}/reactivate
INACTIVE -> CLOSED POST /v1/accounts/{id}/close

Proximo passo: Com a conta ativa, crie cobranças seguindo o fluxo de Payment.

Get Account Details

Recupera os detalhes da conta do cliente especificado, incluindo saldo

Authorizations:
Vitorio API Key
query Parameters
customerId
string

ID do cliente (opcional) — quando informado, recupera os detalhes da conta deste cliente

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "ACTIVE",
  • "bankLegalName": "Celcoin Instituição de Pagamento S.A.",
  • "bankCode": "509",
  • "accountNumber": "12345678",
  • "branch": "0001",
  • "balance": {
    },
  • "createdAt": "2025-01-15T14:30:00Z",
  • "updatedAt": "2025-01-16T10:00:00Z",
  • "pixKeys": [
    ]
}

Create Account

Cria uma conta bancária para o cliente especificado

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

CNPJ da empresa (14 dígitos)

phoneNumber
required
string

Número de telefone de contato da empresa

businessEmail
required
string

E-mail de contato da empresa

businessName
required
string

Razão social

tradingName
required
string

Nome fantasia

companyType
required
string
Enum: "PJ" "MEI" "ME"

Tipo de pessoa jurídica

customerId
string

UUID do cliente. Quando informado, cria uma conta bancária para este cliente. Omita para criar a conta do próprio tenant (somente API key vitorio ou JWT).

required
Array of objects (account.v1.Owner)

Proprietários/sócios da empresa

required
object

Endereço da empresa

Responses

Request samples

Content type
application/json
{
  • "cnpj": "12345678000190",
  • "phoneNumber": "+5511999999999",
  • "businessEmail": "contato@empresa.com.br",
  • "businessName": "Empresa Exemplo Ltda",
  • "tradingName": "Empresa Exemplo",
  • "companyType": "PJ",
  • "customerId": "550e8400-e29b-41d4-a716-446655440000",
  • "owners": [
    ],
  • "businessAddress": {
    }
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "INITIATED"
}

Get Onboarding Status

Recupera o status atual de onboarding da conta do cliente especificado

Authorizations:
Vitorio API Key
query Parameters
customerId
string

ID do cliente (opcional) — quando informado, recupera o status de onboarding da conta deste cliente

Responses

Response samples

Content type
application/json
{
  • "status": "INITIATED",
  • "externalOnboardingId": "prop-123456",
  • "createdAt": "2025-01-15T14:30:00Z",
  • "updatedAt": "2025-01-16T10:00:00Z",
  • "documents": [],
  • "rejectedReason": {
    }
}

Close Account

Fecha permanentemente a conta bancária do cliente especificado

Authorizations:
Vitorio API Key
path Parameters
accountId
required
string

ID da conta (UUID)

Request Body schema: application/json
required
reason
required
string

Motivo do encerramento da conta

Responses

Request samples

Content type
application/json
{
  • "reason": "Business dissolved"
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "CLOSED"
}

Deactivate Account

Desativa temporariamente a conta bancária do cliente especificado

Authorizations:
Vitorio API Key
path Parameters
accountId
required
string

ID da conta (UUID)

Request Body schema: application/json
required
reason
required
string

Motivo da desativação da conta

Responses

Request samples

Content type
application/json
{
  • "reason": "Suspicious activity detected"
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "INACTIVE"
}

Reactivate Account

Reativa uma conta bancária previamente desativada

Authorizations:
Vitorio API Key
path Parameters
accountId
required
string

ID da conta (UUID)

Request Body schema: application/json
required
reason
required
string

Motivo da reativação da conta

Responses

Request samples

Content type
application/json
{
  • "reason": "Investigation cleared"
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "ACTIVE"
}

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 para criar contas (Account) e cobranças (Payment).
  3. Para atualizar dados cadastrais, use PATCH /v1/customers/{id}.

Próximo passo: Com o cliente cadastrado, abra uma conta seguindo o fluxo de Account.

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

A API suporta dois metodos de pagamento: PIX e Boleto. Cada cobrança é criada via POST /v1/payments com o campo method definindo o tipo.

Fluxo geral

POST /v1/payments  -->  Payment criado (PENDING)
                             |
                    Pagador efetua pagamento
                             |
                             v
                     Payment COMPLETED

Opções de pagador (payer)

Opção Descrição
customer_id Seu cliente já cadastrado na plataforma
payer (inline) Cliente do seu cliente - dados do pagador informados sem cadastro prévio

Opções de recebedor (receiver)

Opção Descricao
Padrão Valor creditado na sua conta Vitório
account_id Valor creditado na conta Vitório do seu cliente

Pre-requisitos: Customer cadastrado (se usar customer_id) e Account ativa (se especificar account_id).

Create Payment

Cria uma cobrança individual (boleto ou PIX)

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

Valor do pagamento em centavos. Deve ser > 0 para PIX e > 500 (R$ 5,00) para boleto.

paymentMethod
required
string
Enum: "PIX" "BOLETO"

Método de pagamento

dueDate
required
string

Data de vencimento do pagamento (AAAA-MM-DD)

externalId
required
string

Chave de idempotência fornecida pelo cliente (alfanumérico, hífens, underscores; máx. 255 caracteres)

receiverAccountId
required
string

UUID da conta que recebe o pagamento. Use sua conta para receber pagamentos diretamente, ou a conta de um cliente para que ele receba.

payerCustomerId
string

UUID de cliente existente como pagador

object

Informações do pagador anônimo (nome + documento)

object

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

object

Configuração de pagamento por boleto (quando payment_method é BOLETO)

Responses

Request samples

Content type
application/json
{
  • "amountCents": 10000,
  • "paymentMethod": "PIX",
  • "dueDate": "2026-04-01",
  • "externalId": "PAY-001",
  • "receiverAccountId": "550e8400-e29b-41d4-a716-446655440000",
  • "payerCustomerId": "660e8400-e29b-41d4-a716-446655440001",
  • "anonymousPayer": {
    },
  • "pixConfig": {
    },
  • "boletoConfig": {
    }
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "PENDING",
  • "paymentMethod": "PIX",
  • "amountCents": 10000,
  • "dueDate": "2026-04-01",
  • "pixQrCode": "string",
  • "pixLocationUrl": "string",
  • "boletoBarcode": "string",
  • "boletoBankLine": "string"
}

Cancel Payment

Cancela uma cobrança pendente

Authorizations:
Vitorio API Key
path Parameters
paymentId
required
string

ID do pagamento (UUID)

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "CANCELLED"
}

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