Payment Instrument Creation

Payment instrument creation allows registering a new payment method (such as a postpaid card) for an existing wallet.

Request

ENDPOINT

/wallet/WALLET_KEY/payment_instrument

METHOD

POST

Path Parameters

Field	Type	Description	Characters
`wallet_key`	uuidv4	Unique wallet key in UUID v4 format	36

Request Body

{
  "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
  "owner": {
    "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"
    }
  },
  "payment_instrument_type": "postpaid_card",
  "limit_amount": 2000.00,
  "postpaid_card_data": {
    "card_type": "physical",
    "card_name": "Cartão Principal",
    "printed_name": "JOAO SILVA",
    "cvv_rotation_interval_hours": 24,
    "contactless_enabled": true,
    "delivery_address": {
      "street": "Rua das Flores",
      "number": "123",
      "neighborhood": "Centro",
      "postal_code": "01234567",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Apto 1"
    }
  }
}

Request Body Params

Field	Type	Description	Characters
`request_control_key`	uuidv4	Unique request identification key used by the client.	36
`owner`	object	Payment instrument owner data (natural or legal person)	owner object
`person_key`	string	Unique person identification key in UUID v4 format	36
`payment_instrument_type` *	string	Payment instrument type	payment_instrument_type enumerators
`limit_amount`	float	Instrument credit limit (must be less than or equal to wallet limit)	-
`postpaid_card_data`	object	Postpaid card specific data	postpaid_card_data object

Conditional Fields

owner: Required when person_key is not provided
person_key: Required when owner is not provided
postpaid_card_data: Required when payment_instrument_type is "postpaid_card"
The fields owner and person_key are mutually exclusive

Limit Validations

The limit_amount is not required
When provided, cannot be greater than the wallet's postpaid credit limit
If not provided, the instrument will use the wallet's total limit

owner object

Natural Person (`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	Birth date (YYYY-MM-DD format)	10
`email` *	string	Contact email	254
`phone` *	object	Contact phone	phone object
`address` *	object	Complete address	address object

Legal Person (`person_type: "legal"`)

Field	Type	Description	Characters
`person_type` *	string	Person type (must be "legal")	-
`name` *	string	Company name	100
`trading_name` *	string	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 (natural persons)	-

phone object

Field	Type	Description	Characters
`country_code` *	string	Country code	2-3
`area_code` *	string	Area 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	Postal code (numbers only)	8
`city` *	string	City	100
`state` *	string	State	state enumerators
`complement`	string	Address complement	500

state enumerators

Enumerator	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

payment_instrument_type enumerators

Enumerator	Description
postpaid_card	Postpaid card

postpaid_card_data object

Field	Type	Description	Characters
`card_type` *	string	Card type	card_type enumerators
`card_name` *	string	Card name	1-50
`printed_name` *	string	Name printed on card	2-26
`cvv_rotation_interval_hours`	int	CVV rotation interval in hours	-
`contactless_enabled`	boolean	Enable contactless payment	-
`delivery_address`	object	Card delivery address	delivery_address object

card_type enumerators

Enumerator	Description
virtual	Virtual card
plastic	Plastic card

Conditional Fields

cvv_rotation_interval_hours: Required for card_type: "virtual". Not allowed for card_type: "plastic".
delivery_address: Not allowed for card_type: "virtual". Optional for card_type: "plastic", if not provided will use the owner address or the previously registered address for the provided person_key
contactless_enabled: Not allowed for card_type: "virtual", required for card_type: "plastic"

delivery_address object

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

Response

Success - Instrument Created

STATUS

201

Response Body: Instrument created

{
  "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
  "payment_instrument_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "postpaid_card_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
  "owner_person_key": "f2cad6b4-2a68-9572-99a7-2849c8d6ecf8"
}

Response Body Params

Field	Type	Description	Characters
`request_control_key`	uuidv4	Unique request identification key used by the client.	36
`payment_instrument_key` *	uuidv4	Unique instrument identification key in uuid v4 format	36
`postpaid_card_key` *	uuidv4	Unique postpaid card identification key in uuid v4 format	36
`owner_person_key` *	uuidv4	Unique owner identification key in uuid v4 format	36

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	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
404	CIN000007	Wallet not Found	Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found	Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado
400	CIN000073	Bad Request	Limit amount is greater than postpaid credit limit of the wallet	Limite é maior que o limite de crédito pós-pago da carteira
400	CIN000074	Bad Request	Limit amount is greater than ccb limit of the wallet	Limite é maior que o limite de ccb da carteira
400	CIN000072	Bad Request	Error while creating postpaid card in card service, try again in a few minutes	Erro ao criar postpaid card no serviço de cartão, tente novamente em alguns minutos
400	CIN000067	Bad Request	Error while creating owner of the wallet. Try again in a few minutes	Erro ao criar owner da carteira. Tente novamente em alguns minutos
409	CIN000099	Conflict	Request control key already exists.	Request control key já existe.

Request​

Path Parameters​

Request Body Params​

owner object​

Natural Person (person_type: "natural")​

Legal Person (person_type: "legal")​

phone object​

address object​

state enumerators​

payment_instrument_type enumerators​

postpaid_card_data object​

card_type enumerators​

delivery_address object​

Response​

Success - Instrument Created​

Response Body Params​

Error Response​