Wallet Creation

Wallet creation allows you to register a new credit wallet for an individual or legal entity.

What is a Wallet

A wallet represents a client's invoice and functions as a centralizer to manage multiple attached payment methods. It's important to understand that:

• One wallet = invoice: Each wallet corresponds to a specific client's invoice (identified by CPF/CNPJ)
• Multiple payment methods: The same wallet can have different payment instruments (cards, PIX, etc.)
• Separate instruments: After creating the wallet, you'll need to separately create payment instruments (credit cards, limits, etc.)
• Centralized management: The wallet centralizes all operations and configurations related to that client

Request

ENDPOINT

/wallet

METHOD

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",
    "interest_base": "calendar_days",
    "monthly_interest_percentage": 2.0,
    "fine_percentage": 2.0
  },
  "limits": {
    "postpaid_credit_limit": 5000.00
  }
}

Request Body Params

Field	Type	Description	Characters
request_control_key	uuidv4	Unique request identification key used by the client.	36
owner	object	Wallet owner data (individual or legal entity)	owner object
person_key	string	Unique person identification key in UUID v4 format	36
invoice_configuration *	object	Invoice closing and due date configuration	invoice_configuration object
limits *	object	Wallet credit limits	limits object

Conditional Fields

• owner: Required when person_key is not sent
• person_key: Required when owner is not sent
• Fields are mutually exclusive

owner object

Individual (person_type: "natural")

Field	Type	Description	Characters
person_type *	string	Person type (must be "natural")	-
name *	string	Full name	100
document_number *	string	CPF (numbers only)	11
birthdate *	string	Date of birth (YYYY-MM-DD format)	10
email *	string	Contact email	254
phone *	object	Contact phone	phone object
address *	object	Complete address	address object

Legal Entity (person_type: "legal")

Field	Type	Description	Characters
person_type *	string	Person type (must be "legal")	-
name *	string	Company legal name	100
trading_name *	string	Company trade name	100
document_number *	string	CNPJ (numbers only)	14
foundation_date *	string	Foundation date (YYYY-MM-DD format)	10
email *	string	Contact email	254
phone *	object	Contact phone	phone object
address *	object	Complete address	address object
legal_representatives *	array	List of legal representatives (individuals)	-

phone object

Field	Type	Description	Characters
country_code *	string	Country code (international code)	2-3
area_code *	string	Area code (national code)	2
number *	string	Phone number	8-9

address object

Field	Type	Description	Characters
street *	string	Street/avenue name	500
number *	string	Address number	10
neighborhood *	string	Neighborhood	100
postal_code *	string	ZIP code (numbers only)	8
city *	string	City	100
state *	string	State (abbreviation)	state enums
complement	string	Address complement	500

state enums

Enum	Description
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	Exception

invoice_configuration object

Field	Type	Description	Characters
closing_date_configuration *	object	Invoice closing date configuration	closing_date_configuration object
due_date_configuration *	object	Invoice due date configuration	due_date_configuration object
invoice_payment_type *	string	Invoice payment type	invoice_payment_type enums
interest_base *	string	Interest calculation base	interest_base enums
monthly_interest_percentage *	float	Monthly interest percentage for late payment (0-100)	-
fine_percentage *	float	Fine percentage for late payment (0-100)	-

closing_date_configuration object

Fixed Configuration (type: "fixed")

Field	Type	Description	Characters
type *	string	Configuration type (must be "fixed")	-
fixed_day *	integer	Fixed day of month for closing (1-27)	-

Rule-based Configuration (type: "rule_based")

Field	Type	Description	Characters
type *	string	Configuration type (must be "rule_based")	-
rule *	object	Rule for date calculation	rule object (closing_date_configuration)

rule object (closing_date_configuration)

Field	Type	Description	Characters
day_of_week *	string	Day of the week	day_of_week enums
occurrence *	string	Occurrence of the day in the month	occurrence enums
fallback_strategy *	string	Strategy for non-business days	fallback_strategy enums

due_date_configuration object

Fixed Configuration (type: "fixed")

Field	Type	Description	Characters
type *	string	Configuration type (must be "fixed")	-
offset_months *	integer	Months offset from closing	-
fixed_day *	integer	Fixed day of month for due date (2-27)	-

Rule-based Configuration (type: "rule_based")

Field	Type	Description	Characters
type *	string	Configuration type (must be "rule_based")	-
offset_months *	integer	Months offset from closing	-
rule *	object	Rule for date calculation	rule object (closing_date_configuration)

rule object (due_date_configuration)

Field	Type	Description	Characters
day_of_week *	string	Day of the week	day_of_week enums
occurrence *	string	Occurrence of the day in the month	occurrence enums
fallback_strategy *	string	Strategy for non-business days	fallback_strategy enums

Date Validations

• Due date must be at least 2 days after closing date
• For rule-based configurations, there must be at least one day difference between the chosen weekdays for closing and due date (e.g., closing on Monday and due date on Wednesday of any week)

day_of_week enums

Enum	Description
monday	Monday
tuesday	Tuesday
wednesday	Wednesday
thursday	Thursday
friday	Friday
saturday	Saturday
sunday	Sunday

occurrence enums

Enum	Description
first	First occurrence
second	Second occurrence
third	Third occurrence
fourth	Fourth occurrence
last	Last occurrence

fallback_strategy enums

Enum	Description
next_business_day	Next business day
previous_business_day	Previous business day
same_day	Same day

invoice_payment_type enums

Enum	Description
bank_slip	Bank slip

interest_base enums

Enum	Description
calendar_days	Calendar days

limits object

Field	Type	Description	Characters
postpaid_credit_limit *	float	Limit for postpaid credit	-

Response

Success - Wallet Created with Pending Analysis

STATUS

202

Response Body: Wallet pending analysis

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

Information

If HTTP Status 202 is returned with the wallet_status field valued pending_analysis, the creation will be processed asynchronously. A webhook will be sent later informing whether the wallet was approved or rejected in the KYC analysis. For more details about webhooks, see the webhook documentation

Note

For cases that require KYC analysis, the owner_person_key field will be returned as null in the initial response. The wallet holder will only be created in the system at the end of the KYC process, if approved. In this case, the person key will be sent later through the approval webhook, see the webhook documentation

Success - Active Wallet Created

STATUS

201

Response Body: Active wallet

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

Response Body Params

Field	Type	Description	Characters
wallet_key *	uuidv4	Unique wallet identification key in uuid v4 format	36
owner_person_key *	string	Wallet owner identification key	36
wallet_status *	string	Wallet status	-

wallet_status enums

Enum	Description
pending_analysis	Wallet pending KYC analysis
active	Wallet active and available for use
rejected	Wallet rejected

Wallet Status

• pending_analysis: Returned when wallet is created with complete owner data. Will be submitted to KYC analysis.
• active: Returned when wallet is created with existing person key. Available for immediate use.

Error Response

STATUS

4xx

Response Body: Error

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

HTTP Code status	QI Code code	Title title	Description (eng) description	Description (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
409	CIN000099	Conflict	Request control key already exists.	Request control key já existe.