Criação de Carteira (Wallet)

A criação de carteira (wallet) permite registrar uma nova carteira de crédito para uma pessoa física ou jurídica.

O que é uma Wallet

A wallet representa a fatura de um cliente e funciona como um centralizador para gerenciar múltiplos meios de pagamento atrelados. É importante entender que:

• Uma wallet = fatura: Cada carteira corresponde à fatura de um cliente específico (identificado por CPF/CNPJ)
• Múltiplos meios de pagamento: A mesma wallet pode ter diferentes instrumentos de pagamento (cartões, PIX, etc.)
• Instrumentos separados: Após criar a wallet, será necessário criar separadamente os instrumentos de pagamento (cartões de crédito, limites, etc.)
• Gestão centralizada: A wallet centraliza todas as operações e configurações relacionadas àquele cliente

Request

ENDPOINT

/wallet

MÉTODO

POST

Request Body

{
  "owner": {
    "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
    "person_type": "natural",
    "name": "João Silva",
    "document_number": "12345678901",
    "birthdate": "1990-01-01",
    "email": "joao.silva@email.com",
    "phone": {
      "number": "99999999",
      "area_code": "11",
      "country_code": "55"
    },
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "neighborhood": "Centro",
      "postal_code": "01234567",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Apto 1"
    }
  },
  "invoice_configuration": {
    "closing_date_configuration": {
      "type": "fixed",
      "fixed_day": 15
    },
    "due_date_configuration": {
      "type": "fixed",
      "fixed_day": 20,
      "offset_months": 0
    },
    "invoice_payment_type": "bank_slip",
    "embedded_monthly_interest_percentage": 2.0,
    "interest_base": "calendar_days",
    "monthly_interest_percentage": 2.0,
    "fine_percentage": 2.0
  },
  "limits": {
    "postpaid_credit_limit": 5000.00
  }
}

Request Body Params

Campo	Tipo	Descrição	Caracteres
request_control_key	uuidv4	Chave única de identificação da request utilizada pelo cliente.	36
owner	object	Dados do proprietário da carteira (pessoa física ou jurídica)	Objeto owner
person_key	string	Chave única de identificação da pessoa no formato UUID v4	36
invoice_configuration *	object	Configuração de fechamento e vencimento de faturas	Objeto invoice_configuration
limits *	object	Limites de crédito da carteira	Objeto limits

Campos Condicionais

• owner: Obrigatório quando não for enviado person_key
• person_key: Obrigatório quando não for enviado owner
• Os campos são mutuamente exclusivos

Objeto owner

Pessoa Física (person_type: "natural")

Campo	Tipo	Descrição	Caracteres
person_type *	string	Tipo da pessoa (deve ser "natural")	-
name *	string	Nome completo da pessoa	100
document_number *	string	CPF da pessoa (apenas números)	11
birthdate *	string	Data de nascimento (formato YYYY-MM-DD)	10
email *	string	E-mail de contato	254
phone *	object	Telefone de contato	Objeto phone
address *	object	Endereço completo	Objeto address

Pessoa Jurídica (person_type: "legal")

Campo	Tipo	Descrição	Caracteres
person_type *	string	Tipo da pessoa (deve ser "legal")	-
name *	string	Razão social da empresa	100
trading_name *	string	Nome fantasia da empresa	100
document_number *	string	CNPJ da empresa (apenas números)	14
foundation_date *	string	Data de fundação (formato YYYY-MM-DD)	10
email *	string	E-mail de contato	254
phone *	object	Telefone de contato	Objeto phone
address *	object	Endereço completo	Objeto address
legal_representatives *	array	Lista de representantes legais (pessoas físicas)	-

Objeto phone

Campo	Tipo	Descrição	Caracteres
country_code *	string	Código do país (DDI)	2-3
area_code *	string	Código de área (DDD)	2
number *	string	Número do telefone	8-9

Objeto address

Campo	Tipo	Descrição	Caracteres
street *	string	Nome da rua/avenida	500
number *	string	Número do endereço	10
neighborhood *	string	Bairro	100
postal_code *	string	CEP (apenas números)	8
city *	string	Cidade	100
state *	string	Estado (UF)	Enumeradores state
complement	string	Complemento do endereço	500

Enumeradores state

Enumerador	Descrição
AC	Acre
AL	Alagoas
AM	Amazonas
AP	Amapá
BA	Bahia
CE	Ceará
DF	Distrito Federal
ES	Espírito Santo
GO	Goiás
MA	Maranhão
MG	Minas Gerais
MS	Mato Grosso do Sul
MT	Mato Grosso
PA	Pará
PB	Paraíba
PE	Pernambuco
PI	Piauí
PR	Paraná
RJ	Rio de Janeiro
RN	Rio Grande do Norte
RO	Rondônia
RR	Roraima
RS	Rio Grande do Sul
SC	Santa Catarina
SE	Sergipe
SP	São Paulo
TO	Tocantins
EX	Exceção

Objeto invoice_configuration

Campo	Tipo	Descrição	Caracteres
closing_date_configuration *	object	Configuração da data de fechamento da fatura	Objeto closing_date_configuration
due_date_configuration *	object	Configuração da data de vencimento da fatura	Objeto due_date_configuration
invoice_payment_type *	string	Tipo de pagamento da fatura	Enumeradores invoice_payment_type
interest_base *	string	Base de cálculo dos juros	Enumeradores interest_base
monthly_interest_percentage *	float	Percentual de juros mensais por atraso (0-100)	-
fine_percentage *	float	Percentual de multa por atraso (0-100)	-

Objeto closing_date_configuration

Configuração Fixa (type: "fixed")

Campo	Tipo	Descrição	Caracteres
type *	string	Tipo de configuração (deve ser "fixed")	-
fixed_day *	integer	Dia fixo do mês para fechamento (1-27)	-

Configuração Baseada em Regras (type: "rule_based")

Campo	Tipo	Descrição	Caracteres
type *	string	Tipo de configuração (deve ser "rule_based")	-
rule *	object	Regra para cálculo da data	Objeto rule (closing_date_configuration)

Objeto rule (closing_date_configuration)

Campo	Tipo	Descrição	Caracteres
day_of_week *	string	Dia da semana	Enumeradores day_of_week
occurrence *	string	Ocorrência do dia no mês	Enumeradores occurrence
fallback_strategy *	string	Estratégia para dias não úteis	Enumeradores fallback_strategy

Objeto due_date_configuration

Configuração Fixa (type: "fixed")

Campo	Tipo	Descrição	Caracteres
type *	string	Tipo de configuração (deve ser "fixed")	-
offset_months *	integer	Meses de offset a partir do fechamento	-
fixed_day *	integer	Dia fixo do mês para vencimento (2-27)	-

Configuração Baseada em Regras (type: "rule_based")

Campo	Tipo	Descrição	Caracteres
type *	string	Tipo de configuração (deve ser "rule_based")	-
offset_months *	integer	Meses de offset a partir do fechamento	-
rule *	object	Regra para cálculo da data	Objeto rule (closing_date_configuration)

Objeto rule (due_date_configuration)

Campo	Tipo	Descrição	Caracteres
day_of_week *	string	Dia da semana	Enumeradores day_of_week
occurrence *	string	Ocorrência do dia no mês	Enumeradores occurrence
fallback_strategy *	string	Estratégia para dias não úteis	Enumeradores fallback_strategy

Validações de Data

• A data de vencimento deve ser pelo menos 2 dia após a data de fechamento
• Para configurações baseadas em regras, deve existir ao menos um dia de diferença entre os dias da semana escolhidos para fechamento e vencimento (ex: fechamento na segunda-feira e vencimento na quarta-feira de qualquer semana)

Enumeradores day_of_week

Enumerador	Descrição
monday	Segunda-feira
tuesday	Terça-feira
wednesday	Quarta-feira
thursday	Quinta-feira
friday	Sexta-feira
saturday	Sábado
sunday	Domingo

Enumeradores occurrence

Enumerador	Descrição
first	Primeira ocorrência
second	Segunda ocorrência
third	Terceira ocorrência
fourth	Quarta ocorrência
last	Última ocorrência

Enumeradores fallback_strategy

Enumerador	Descrição
next_business_day	Próximo dia útil
previous_business_day	Dia útil anterior
same_day	Mesmo dia

Enumeradores invoice_payment_type

Enumerador	Descrição
bank_slip	Boleto bancário

Enumeradores interest_base

Enumerador	Descrição
calendar_days	Dias corridos

Objeto limits

Campo	Tipo	Descrição	Caracteres
postpaid_credit_limit *	float	Limite para crédito pós-pago	-

Response

Sucesso - Carteira Criada com Análise Pendente

STATUS

202

Response Body: Carteira pendente de análise

{
  "wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "owner_person_key": null,
  "wallet_status": "pending_analysis"
}

Informação

Caso seja retornado HTTP Status 202 com o campo wallet_status com valor pending_analysis, a criação será processada assincronamente. Posteriormente será enviado posteriormente um webhook informando se a carteira foi aprovada ou rejeitada na análise KYC. Para mais detalhes sobre webhooks, consulte a documentação de webhooks

Observação

Para casos que requerem análise KYC, o campo owner_person_key será retornado como null na resposta inicial. A pessoa titular da carteira só será criada no sistema ao final do processo de KYC, caso seja aprovada. Neste caso, a chave da pessoa será enviada posteriormente através do webhook de aprovação, consulte a documentação de webhooks

Sucesso - Carteira Criada Ativa

STATUS

201

Response Body: Carteira ativa

{
  "wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "owner_person_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
  "wallet_status": "active"
}

Response Body Params

Campo	Tipo	Descrição	Caracteres
wallet_key *	uuidv4	Chave única de identificação da carteira no formato uuid v4	36
owner_person_key *	string	Chave de identificação do proprietário da carteira	36
wallet_status *	string	Status da carteira	-

Enumeradores wallet_status

Enumerador	Descrição
pending_analysis	Carteira pendente de análise KYC
active	Carteira ativa e disponível para uso

Status da Carteira

• pending_analysis: Retornado quando a carteira é criada com dados completos do proprietário. Será submetida a análise KYC.
• active: Retornado quando a carteira é criada com chave de pessoa existente. Disponível para uso imediato.

Error Response

STATUS

4xx

Response Body: Error

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}

Código HTTP status	Código QI code	Título title	Descrição (eng) description	Descrição (pt-br) translation
400	QIT000001	Bad Request	Schema Error	Schema Inválido
404	CIN000020	Requester not Found	No requester configuration found for requester key: 8e1e6b46-beb3-467b-965c-6c545707d467	Solicitante não encontrado para requester key: 8e1e6b46-beb3-467b-965c-6c545707d467
404	CIN000062	Not Found	Person not found by person key: e51070e4-7494-468d-a20e-bf14789fa8ff	Pessoa não encontrada para a person key: e51070e4-7494-468d-a20e-bf14789fa8ff
409	CIN000043	Conflict	Active wallet found	Carteira ativa já existe
400	CIN000063	Bad Request	Expiration date too close to closing date	Data de vencimento muito próxima da data de fechamento
400	CIN000064	Bad Request	Invalid offset months for rule-based configuration	Meses de offset inválidos para configuração baseada em regras
400	CIN000065	Bad Request	Weekdays too close for rule-based configuration	Dias da semana muito próximos para configuração baseada em regras
400	CIN000002	Bad Request	Invalid signer document number	Número do documento do signatário inválido
400	CIN000066	Bad Request	Error while creating wallet in card service	Erro ao criar carteira no serviço de cartão