Criação de Instrumento de Pagamento

A criação de instrumento de pagamento permite registrar um novo meio de pagamento (como cartão pós-pago) para uma carteira existente.

Request

ENDPOINT

/wallet/WALLET_KEY/payment_instrument

MÉTODO

POST

Path Parameters

Campo	Tipo	Descrição	Caracteres
wallet_key	uuidv4	Chave única da carteira no formato UUID v4	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

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 do instrumento (pessoa física ou jurídica)	Objeto owner
person_key	string	Chave única de identificação da pessoa no formato UUID v4	36
payment_instrument_type *	string	Tipo do instrumento de pagamento	Enumeradores payment_instrument_type
limit_amount	float	Limite de crédito do instrumento (deve ser menor ou igual ao limite da carteira)	-
postpaid_card_data	object	Dados específicos do cartão pós-pago	Objeto postpaid_card_data

Campos Condicionais

• owner: Obrigatório quando não for enviado person_key
• person_key: Obrigatório quando não for enviado owner
• postpaid_card_data: Obrigatório quando payment_instrument_type for "postpaid_card"
• Os campos owner e person_key são mutuamente exclusivos

Validações de Limite

• O limit_amount não é obrigatório
• Quando informado, não pode ser maior que o limite de crédito pós-pago da carteira
• Se não informado, o instrumento utilizará o limite total da carteira

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

Enumeradores payment_instrument_type

Enumerador	Descrição
postpaid_card	Cartão pós-pago

Objeto postpaid_card_data

Campo	Tipo	Descrição	Caracteres
card_type *	string	Tipo do cartão	Enumeradores card_type
card_name *	string	Nome do cartão	1-50
printed_name *	string	Nome impresso no cartão	2-26
cvv_rotation_interval_hours	int	Intervalo de rotação do CVV em horas	-
contactless_enabled	boolean	Habilita pagamento por aproximação	-
delivery_address	object	Endereço de entrega do cartão	Objeto delivery_address

Enumeradores card_type

Enumerador	Descrição
virtual	Cartão virtual
plastic	Cartão plástico

Campos Condicionais

• cvv_rotation_interval_hours: Obrigatório para card_type: "virtual". Não permitido para card_type: "plastic".
• delivery_address: Não permitido para card_type: "virtual". Opcional para card_type: "plastic", se não informado será usado o endereço do owner ou o previamente cadastrado para a person_key informada
• contactless_enabled: Não permitido para card_type: "virtual", obrigatório para card_type: "plastic"

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

Response

Sucesso - Instrumento Criado

STATUS

201

Response Body: Instrumento criado

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

Campo	Tipo	Descrição	Caracteres
request_control_key	uuidv4	Chave única de identificação da request utilizada pelo cliente.	36
payment_instrument_key *	uuidv4	Chave única de identificação do instrumento no formato uuid v4	36
postpaid_card_key *	uuidv4	Chave única de identificação do cartão pós-pago no formato uuid v4	36
owner_person_key *	uuidv4	Chave única de identificação do proprietário no formato uuid v4	36

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