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

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

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

Criação de Instrumento de Pagamento

Request​

Path Parameters​

Request Body Params​

Objeto owner​

Pessoa Física (person_type: "natural")​

Pessoa Jurídica (person_type: "legal")​

Objeto phone​

Objeto address​

Enumeradores state​

Enumeradores payment_instrument_type​

Objeto postpaid_card_data​

Enumeradores card_type​

Objeto delivery_address​

Response​

Sucesso - Instrumento Criado​

Response Body Params​

Error Response​