跳到主要内容

创建支付工具

创建支付工具允许为现有钱包注册新的支付方式（如后付费卡）。

Request​

ENDPOINT
/wallet/WALLET_KEY/payment_instrument
MÉTODO
POST

路径参数​

字段类型描述字符数
wallet_keyuuidv4UUID 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_control_keyuuidv4客户端使用的请求唯一识别密钥36
ownerobject工具所有人信息（个人或法人）owner 对象
person_keystringUUID v4 格式的人员唯一识别密钥36
payment_instrument_type *string支付工具类型payment_instrument_type 枚举值
limit_amountfloat工具信用额度（必须小于或等于钱包额度）-
postpaid_card_dataobject后付费卡的特定数据postpaid_card_data 对象
条件字段
  • owner：未发送 person_key 时为必填
  • person_key：未发送 owner 时为必填
  • postpaid_card_data：payment_instrument_type 为 "postpaid_card" 时为必填
  • owner 和 person_key 字段互斥
额度验证
  • limit_amount 非必填
  • 填写时不得超过钱包的后付费信用额度
  • 未填写时，工具将使用钱包的全部额度

owner 对象​

个人（person_type: "natural"）​

字段类型描述字符数
person_type *string人员类型（必须为 "natural"）-
name *string姓名全称100
document_number *stringCPF（仅数字）11
birthdate *string出生日期（YYYY-MM-DD 格式）10
email *string联系邮箱254
phone *object联系电话phone 对象
address *object完整地址address 对象
字段类型描述字符数
person_type *string人员类型（必须为 "legal"）-
name *string公司法定名称100
trading_name *string公司商号100
document_number *stringCNPJ（仅数字）14
foundation_date *string成立日期（YYYY-MM-DD 格式）10
email *string联系邮箱254
phone *object联系电话phone 对象
address *object完整地址address 对象
legal_representatives *array法定代表人列表（自然人）-

phone 对象​

字段类型描述字符数
country_code *string国家代码（DDI）2-3
area_code *string区号（DDD）2
number *string电话号码8-9

address 对象​

字段类型描述字符数
street *string街道/大道名称500
number *string门牌号10
neighborhood *string社区/街区100
postal_code *stringCEP（仅数字）8
city *string城市100
state *string州（UF）state 枚举值
complementstring地址补充说明500

state 枚举值​

枚举值描述
ACAcre
ALAlagoas
AMAmazonas
APAmapá
BABahia
CECeará
DFDistrito Federal
ESEspírito Santo
GOGoiás
MAMaranhão
MGMinas Gerais
MSMato Grosso do Sul
MTMato Grosso
PAPará
PBParaíba
PEPernambuco
PIPiauí
PRParaná
RJRio de Janeiro
RNRio Grande do Norte
RORondônia
RRRoraima
RSRio Grande do Sul
SCSanta Catarina
SESergipe
SPSão Paulo
TOTocantins
EX特殊情况

payment_instrument_type 枚举值​

枚举值描述
postpaid_card后付费卡

postpaid_card_data 对象​

字段类型描述字符数
card_type *string卡片类型card_type 枚举值
card_name *string卡片名称1-50
printed_name *string卡片印刷名称2-26
cvv_rotation_interval_hoursintCVV 轮换间隔（小时）-
contactless_enabledboolean启用非接触式支付-
delivery_addressobject卡片配送地址delivery_address 对象

card_type 枚举值​

枚举值描述
virtual虚拟卡
plastic实体卡
条件字段
  • cvv_rotation_interval_hours：card_type: "virtual" 时为必填，card_type: "plastic" 时不允许。
  • delivery_address：card_type: "virtual" 时不允许；card_type: "plastic" 时为可选，若未填写，将使用 owner 的地址或已为 person_key 注册的地址。
  • contactless_enabled：card_type: "virtual" 时不允许，card_type: "plastic" 时为必填。

delivery_address 对象​

字段类型描述字符数
street *string街道/大道名称500
number *string门牌号10
neighborhood *string社区/街区100
postal_code *stringCEP（仅数字）8
city *string城市100
state *string州（UF）state 枚举值
complementstring地址补充说明500

Response​

成功 - 工具已创建​

STATUS
201
Response Body：已创建工具
{
  "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"
}

响应体参数​

字段类型描述字符数
request_control_keyuuidv4客户端使用的请求唯一识别密钥36
payment_instrument_key *uuidv4uuid v4 格式的工具唯一识别密钥36
postpaid_card_key *uuidv4uuid v4 格式的后付费卡唯一识别密钥36
owner_person_key *uuidv4uuid v4 格式的所有人唯一识别密钥36

错误响应​

STATUS
4xx
Response Body: Error
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
HTTP 代码
status		QI 代码
code		标题
title		描述（英文）
description		描述（葡文）
translation
400QIT000001Bad RequestSchema ErrorSchema Inválido
404CIN000062Not FoundPerson not found by person key: e51070e4-7494-468d-a20e-bf14789fa8ffPessoa não encontrada para a person key: e51070e4-7494-468d-a20e-bf14789fa8ff
404CIN000007Wallet not FoundWallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not foundCarteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado
400CIN000073Bad RequestLimit amount is greater than postpaid credit limit of the walletLimite é maior que o limite de crédito pós-pago da carteira
400CIN000074Bad RequestLimit amount is greater than ccb limit of the walletLimite é maior que o limite de ccb da carteira
400CIN000072Bad RequestError while creating postpaid card in card service, try again in a few minutesErro ao criar postpaid card no serviço de cartão, tente novamente em alguns minutos
400CIN000067Bad RequestError while creating owner of the wallet. Try again in a few minutesErro ao criar owner da carteira. Tente novamente em alguns minutos
409CIN000099ConflictRequest control key already exists.Request control key já existe.