QI FATURA

带 PIX 分期付款的卡片体验

API 开发中

该 API 仍处于最终开发阶段，因此本手册可能会有所更改。

注意！

QI Tech 的 webhook 不应进行严格映射。我们的 API 返回的 webhook payload 中可能会包含额外字段。

Webhook 重发

您可以按照文档中的详细说明查询并重发 webhook：Webhook 重发。

1. 创建数字钱包

要能够在账单中添加条目（以 CCB 为基础的 PIX 入账），首先需要为每个客户创建一个数字钱包。

Request

ENDPOINT

/card_invoice/wallet

MÉTODO

POST

Request Body

{
    "owner": {
        "person_type": "natural",
        "name": "\<NOME TITULAR DA CARTEIRA\>",
        "document_number": "\<CPF TITULAR DA CARTEIRA\>",
        "address": {
            "street": "\<RUA TITULAR DA CARTEIRA\>",
            "state": "\<ESTADO TITULAR DA CARTEIRA\>",
            "city": "\<CIDADE TITULAR DA CARTEIRA\>",
            "neighborhood": "\<BAIRRO TITULAR DA CARTEIRA\>",
            "number": "\<No. TITULAR DA CARTEIRA\>",
            "postal_code": "\<CEP TITULAR DA CARTEIRA\>",
            "complement": "\<COMPLEMENTO TITULAR DA CARTEIRA\>"
        },
        "phone": {
            "number": "\<CELULAR TITULAR DA CARTEIRA\>",
            "area_code": "\<DDD TITULAR DA CARTEIRA\>",
            "country_code": "55",
            },
        "email": "\<EMAIL TITULAR DA CARTEIRA\>",
        "document_identification_number":"\<NÚMERO DO DOCUMENTO DE IDENTIFICAÇÃO DO TITULAR DA CARTEIRA\>",
        "document_identification":"\<CHAVE DO DOCUMENTO DE IDENTICAÇÃO DO TITULAR\>",
        "document_identification_back":"\<CHAVE DO VERSO DO DOCUMENTO DE IDENTICAÇÃO DO TITULAR\>",
        "selfie":"\<CHAVE DA SELFIE DO TITULAR\>",
        "document_identification_type": "\<TIPO DO DOCUMENTO DE IDENTIFICAÇÃO DO TITULAR\>"

    },
    "invoice_configuration":{
        "closing_day": "\<DATA DE FECHAMENTO DA FATURA\>", 
        "due_day": "\<DATA DE VENCIMENTO DA FATURA\>", 
        "grace_months": "\<DIFERENÇA, EM MESES, ENTRE closing_day e due_day\>", 
        "issuing_and_due_day_difference": "\<DIAS ANTES DO VENCIMENTO QUE A FATURA DEVE SER EMITIDA\>", 
        "invoice_payment_type": "bankslip", 
        "delay_fine_percentage": "\<CONFIGURAÇÃO DE ATRASO - VALOR DA MORA\>", 
        "delay_monthly_interest_rate": "\<CONFIGURAÇÃO DE ATRASO -VALOR DOS JUROS POR DIA\>"
    },
    "invoice_authorization": {
        "signature": {
            "signer": {
                "name": "\<NOME ASSINANTE\>",
                "email": "\<EMAIL ASSINANTE\>",
                "phone": {
                    "number": "\<CELULAR ASSINANTE\>",
                    "area_code": "\<DDD ASSINANTE\>",
                    "country_code": "55",
                },
                "document_number": "CPF ASSINANTE"
                },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "\<DATA E HORA DA ASSINATURA\>",
                "ip_address": "\<IP DO ASSINANTE\>",
                "fingerprint": {},
                "third_party_additional_data": {},
                "session_id": "\<ID DA SESSÃO DO ASSINANTE\>"
                },
            "signed_object": {
                "document_key": "\<CHAVE DO DOCUMENTO NA QI\>"
                }
            }
        },
    "limit": "\<VALOR DO LIMITE DA WALLET\>",
    "default_monthly_interest_rate": "\<TAXA DE JUROS MENSAL, DEFAULT DA CARTEIRA, CONSIDERADA PARA CADA ENTRADA (PIX)\>"
  }

Request body 详情

Wallet payload

字段	类型	描述	字符数
`owner`	object	钱包所有者对象	owner 对象
`invoice_configuration`	object	每个钱包的账单配置对象	invoicer_configuration 对象
`invoice_authorization`	object	授权对象	invoice_authorization 对象
`limit`	number	钱包限额
`default_monthly_interest_rate`	number	钱包的默认月利率。

owner 对象

字段	类型	描述	字符数
`person_type`	string	标识发送的对象是自然人还是法人。
`name`	string	PJ 业务时为公司名，PF 业务时为个人姓名。	100
`document_number`	string	个人 CPF（仅数字），限11个字符。
`address`	string	客户地址。	address 对象
`phone`	string	电话数据对象	phone 对象
`email`	string	客户邮箱。

address 对象

字段	描述	示例	最大字符数
`street`	string	地址街道	100
`state`	string	地址州（两个大写字母）	2
`city`	string	地址城市	100
`neighborhood`	string	地址街区	100
`number`	string	街道门牌号	10
`postal_code`	string	地址 CEP（http://www.buscacep.correios.com.br/sistemas/buscacep/）（仅数字）	8
`complement`	string	地址补充（自由文本）	100

phone 对象

字段	描述	示例	最大字符数
`country_code`	string	电话国际区号（https://ddi.guiamais.com.br/）	3
`area_code`	string	电话区号（https://ddd.guiamais.com.br/）	2
`number`	string	电话号码（仅数字）	10

invoice_configuration 对象

字段	描述	示例
`closing_day`	number	账单结账日（账单条目登记的截止日期）。
`due_day`	number	账单到期日。选项：1、5、10
`grace_months`	number	结账日与到期日之间的月数差。
`delay_fine_percentage`	number	账单逾期付款时的滞纳金金额。
`delay_monthly_interest_rate`	number	账单逾期付款时每月利息金额。
`issuing_and_due_day_difference`	number	账单发行日与到期日之间的天数，用于计算账单发行日期。
`invoice_payment_type`	string	账单付款方式。选项：'bankslip'

账单配置

在账单配置（invoice_configuration）中，固定数据如"delay_fine_percentage"、"grace_months"、"delay_monthly_interest_rate"、"invoice_payment_type"、"issuing_and_due_day_difference"可以直接在 API 合作伙伴初始设置中配置，从而简化钱包创建的 payload。在 API 合作伙伴初始设置中配置的信息将对所有客户固定适用。

警告

账单到期日"invoice_configuration.due_day"与结账日"invoice_configuration.closing_day"之间的天数必须大于等于8天且小于等于10天。

Response

ENDPOINT

/card_invoice/wallet

MÉTODO

POST

HTTP STATUS

201

Response Body

{
    "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
    "status": "active"
}

Response body 详情

字段	类型	描述	字符数
`wallet_key`	string	钱包唯一标识符（uuid）
`status`	string	钱包状态

1.1. 查询现有钱包：

QUERY PARAMETERS

枚举值	描述
owner_document_number	钱包持有人的 CPF
page	查询页码
page_size	查询请求的每页条数

Request

ENDPOINT

/card_invoice/wallets

MÉTODO

GET

Response

ENDPOINT

/card_invoice/wallets

MÉTODO

GET

HTTP STATUS

200

Response Body

{
    "page": 1,
    "last_page": true,
    "data": [
        {
            "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
            "owner": {
                "person_type": "natural",
                "name": "Nome Sobrenome",
                "document_number": "12345678911",
                "address": {
                    "street": "RUA DEZENOVE",
                    "state": "SP",
                    "city": "JARDINÓPOLIS",
                    "neighborhood": "JARDINS DO IMPÉRIO",
                    "number": "19",
                    "postal_code": "13348719",
                    "complement": ""
                },
                "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        },
                "email": "teste@teste.com.br"
            },
            "collaterals": [],
            "cards": [
                {"card_key":"067cba94-4d57-4a75-9766-7e5b95c87367"}
            ],
            "invoice_authorization": {
                "signature": {
                    "signer": {
                        "name": "Nome Sobrenome",
                        "document_number": "12345678911",
                        "email": "teste@teste.com.br",
                        "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        }
                    },
                    "authentication_type": "opt_in",
                    "authenticity": {
                        "timestamp": "2022-11-18T11:17:46",
                        "ip_address": "104.101.21.0",
                        "fingerprint": {
                            "browser": "Mozila"
                        },
                        "third_party_additional_data": {},
                        "session_id": "8df91773-c537-4662-b08b-025f03bf79dc"
                    },
                    "signed_object": {
                        "document_key": "27A0BA3D-A89D-4218-AB06-BC39B94CE23C"
                    }
                }
            },
            "interest_base": "calendar_days_365",
            "default_monthly_interest_rate": 0.035,
            "invoice_configuration": {
                "due_day": 10,
                "closing_day": 1,
                "grace_months": 1,
                "invoice_payment_type": "bankslip",
                "delay_fine_percentage": 0,
                "delay_monthly_interest_rate": 0,
                "issuing_and_due_day_difference": 9
            },
            "status": "active",
            "limit": 800,
            "current_limit": 800
}
    ]
}

1.2. 查询特定钱包：

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]

MÉTODO

GET

Response

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]

MÉTODO

GET

HTTP STATUS

200

Response Body

        {
            "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
            "owner": {
                "person_type": "natural",
                "name": "Nome Sobrenome",
                "document_number": "12345678911",
                "address": {
                    "street": "RUA DEZENOVE",
                    "state": "SP",
                    "city": "JARDINÓPOLIS",
                    "neighborhood": "JARDINS DO IMPÉRIO",
                    "number": "19",
                    "postal_code": "13348719",
                    "complement": ""
                },
                "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        },
                "email": "teste@teste.com.br"
            },
            "collaterals": [],
            "cards": [
                {"card_key":"067cba94-4d57-4a75-9766-7e5b95c87367"}
            ],
            "invoice_authorization": {
                "signature": {
                    "signer": {
                        "name": "Nome Sobrenome",
                        "document_number": "12345678911",
                        "email": "teste@teste.com.br",
                        "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        }
                    },
                    "authentication_type": "opt_in",
                    "authenticity": {
                        "timestamp": "2022-11-18T11:17:46",
                        "ip_address": "104.101.21.0",
                        "fingerprint": {
                            "browser": "Mozila"
                        },
                        "third_party_additional_data": {},
                        "session_id": "8df91773-c537-4662-b08b-025f03bf79dc"
                    },
                    "signed_object": {
                        "document_key": "27A0BA3D-A89D-4218-AB06-BC39B94CE23C"
                    }
                }
            },
            "interest_base": "calendar_days_365",
            "default_monthly_interest_rate": 0.035,
            "invoice_configuration": {
                "due_day": 10,
                "closing_day": 1,
                "grace_months": 1,
                "invoice_payment_type": "bankslip",
                "delay_fine_percentage": 0,
                "delay_monthly_interest_rate": 0,
                "issuing_and_due_day_difference": 9
            },
            "status": "active",
            "limit": 800,
            "current_limit": 800
}

1.3. 修改钱包限额：

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]

MÉTODO

PATCH

Request Body

{
    "limit": 123
}

Response

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]

MÉTODO

PATCH

HTTP STATUS

200

Response Body

        {
            "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
            "owner": {
                "person_type": "natural",
                "name": "Nome Sobrenome",
                "document_number": "12345678911",
                "address": {
                    "street": "RUA DEZENOVE",
                    "state": "SP",
                    "city": "JARDINÓPOLIS",
                    "neighborhood": "JARDINS DO IMPÉRIO",
                    "number": "19",
                    "postal_code": "13348719",
                    "complement": ""
                },
                "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        },
                "email": "teste@teste.com.br"
            },
            "collaterals": [],
            "invoice_authorization": {
                "signature": {
                    "signer": {
                        "name": "Nome Sobrenome",
                        "document_number": "12345678911",
                        "email": "teste@teste.com.br",
                        "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        }
                    },
                    "authentication_type": "opt_in",
                    "authenticity": {
                        "timestamp": "2022-11-18T11:17:46",
                        "ip_address": "104.101.21.0",
                        "fingerprint": {
                            "browser": "Mozila"
                        },
                        "third_party_additional_data": {},
                        "session_id": "8df91773-c537-4662-b08b-025f03bf79dc"
                    },
                    "signed_object": {
                        "document_key": "27A0BA3D-A89D-4218-AB06-BC39B94CE23C"
                    }
                }
            },
            "interest_base": "calendar_days_365",
            "default_monthly_interest_rate": 0.035,
            "invoice_configuration": {
                "due_day": 10,
                "closing_day": 1,
                "grace_months": 1,
                "invoice_payment_type": "bankslip",
                "delay_fine_percentage": 0,
                "delay_monthly_interest_rate": 0,
                "issuing_and_due_day_difference": 9
            },
            "status": "active",
            "limit": 123,
            "current_limit": 1000
}

2. 向现有数字钱包添加卡片：

为客户创建数字钱包后，需要创建一张与该钱包关联的卡片。

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card

MÉTODO

POST

Request Body

{
    "settlement_method": "credit_operation"
}

Request body 详情

Card payload

字段	类型	描述	字符数
`settlement_method`	string	担保类型，即交易将如何进行担保。选项："credit_operation"

Response

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card

MÉTODO

POST

HTTP STATUS

201

Response Body

{
    "card_key": "dabd10b6-80a8-4c9c-8a8e-e25a56668525"
}

Response body 详情

字段	类型	描述	字符数
`card_key`	string	卡片唯一标识符（uuid）

3. 模拟操作：

模拟交易（PIX）。

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/simulation

MÉTODO

POST

Request Body

{
  "amount": 200,
  "number_of_installments": 4,
  "monthly_interest_rate": 0.035
}

注意

无需填写"monthly_interest_rate"字段，未填写时，交易将采用钱包的默认利率。

Response

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/simulation

MÉTODO

POST

HTTP STATUS

201

Response Body

{
    "amount": 200,
    "final_amount": 221.16,
    "number_of_installments": 4,
    "monthly_interest_rate": 0.035,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "items": [
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 1,
            "invoice": {
                "due_date": "2023-09-10"
            }
        },
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 2,
            "invoice": {
                "due_date": "2023-10-10"
            }
        },
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 3,
            "invoice": {
                "due_date": "2023-11-10"
            }
        },
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 4,
            "invoice": {
                "due_date": "2023-12-10"
            }
        }
    ]
}

4. 在卡片中添加交易：

添加交易（PIX）。此步骤将生成 CCB，验证是否有足够的可用额度来执行交易。交易清算以同步方式处理。

Request

注意

无需填写"monthly_interest_rate"字段，未填写时，交易将采用钱包的默认利率。

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry

MÉTODO

POST

Request Body

{
  "disbursement": {
    "method": "pix",
    "data": {
      "pix_key": "\<CHAVE PIX\>",
      "end_to_end_id": "\<CHAVE END TO END DO PIX\>"
    }
  },
  "description": "Compra Padaria do João",
  "amount": 200,
  "request_control_key": "275619e6-23d1-485e-81ca-5552aa235761",
  "number_of_installments": 4,
  "monthly_interest_rate": 0.027,
  "authorization": {
    "document_number": "01975273702",
    "signature": {
      "signed_object": {
        "document_key": "6254c56e-c980-4b38-ad99-ac5ec7535d68"
      },
      "authenticity": {
        "ip_address": "192.168.0.0",
        "third_party_additional_data": {
          "hash": "23A2581A8D524035FEB2950D28727CF5 | 192.168.0.0 | 23/02/2023 17:38:45"
        },
        "timestamp": "2023-02-23T17:38:45.610458300"
      },
      "authentication_type": "opt_in",
      "signer": {
        "document_number": "01975273702",
        "phone": {
          "number": "986243444",
          "country_code": "55",
          "area_code": "21"
        },
        "name": "Master Tester",
        "email": "mail@mail.com"
      }
    }
  }
}

使用 PIX 密钥放款

{
    "disbursement": {
    "method": "pix",
    "data": {
      "pix_key": "\<CHAVE PIX\>",
      "end_to_end_id": "\<CHAVE END TO END DO PIX\>"
    }
  }
}

使用 PIX QR Code 放款

{
    "disbursement": {
    "method": "pix_qrcode",
    "data": {
      "qr_code_url": "\<URL DO PIX\>",
      "end_to_end_id": "\<CHAVE END TO END DO PIX QR CODE\>"
    }
  }
}

使用 PIX 手动方式放款

{
    "disbursement": {
    "method": "pix_manual",
    "data": {
        "ispb": "\<BASE DO CNPJ DO BANCO\>",
        "branch_number": "\<AGÊNCIA DA CONTA DE DESEMBOLSO\>",
        "account_number": "\<NÚMERO DA CONTA SEM O DÍGITO\>",
        "account_digit": "\<DIGITO DA CONTA DE DESEMBOLSO\>",
        "document_number": "\<CPF/ CNPJ DO TITULAR DA CONTA\>",
        "name": "\<NOME DO TITULAR DA CONTA\>"
    }
  }
}

Response

交易放款成功时：

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry

MÉTODO

POST

HTTP STATUS

201

Response Body

{
    "card_entry_key": "ad8e073a-2159-479b-b141-cd5d8ceb8567",
    "status": "active",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf"
}

注意

由于巴西央行或目标银行的不稳定性，合同交易可能会延迟，从而使其进入"pending_activation"状态，并在交易成功完成或合同取消时进行更新。因此，流程将从同步转为异步，需要等待交易成功或失败的 webhook。

4.1 查询特定交易（card entry）：

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]

MÉTODO

GET

Response

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]

MÉTODO

GET

HTTP STATUS

200

PIX 手动交易 Response

{
    "transaction_key": "75b800f3-12ba-41b3-a7d5-cbb3ae2199f2",
    "end_to_end_id": "E324025022023082120064RNfdmEDTxV", 
    "transacted_at": "2023-08-21T20:07:46",
    "amount": 2242.8,
    "number_of_installments": 2,
    "monthly_interest_rate": 0.027,
    "final_amount":2250,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "description":"Compra Padaria do João",
    "disbursement": {
        "method": "pix_manual",
        "data": {
            "ispb": 32402502,
            "branch_number": 1,
            "account_number": 15570,
            "account_digit": 1,
            "document_number": "12345678911",
            "name": "XXXXX XXXX XXXX"
        }
    },
    "card_entry_datetime": "2023-06-07T10:29:49Z",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf",
    "items": [
        {
            "item_key":"37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 1125,
            "used_limit":1121.4,
            "status":"active",
            "installment_number": 1,
            "invoice": {
                "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
                "due_date": "2023-07-10",
                "status": "opened"
                },
        },
        {
            "item_key":"60e4801f-75ce-411e-aaf0-99b951c05308",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 2,
            "status":"active",
            "invoice": {
                "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
                "due_date": "2023-08-10",
                "status": "opened"
                },
        }
	], 
    "status": "active"
}

PIX Key 交易 Response

{
    "transaction_key": "75b800f3-12ba-41b3-a7d5-cbb3ae2199f2",
    "end_to_end_id": "E324025022023082120064RNfdmEDTxV", 
    "transacted_at": "2023-08-21T20:07:46",
    "amount": 2242.8,
    "final_amount":2250,
    "number_of_installments": 2,
    "monthly_interest_rate": 0.027,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "description":"Compra Padaria do João",
    "disbursement": {
 		"data": {
 			"end_to_end_id": "E3240250220210928212926341670923",
 			"pix_key": "+5516983068432"
 		},
 		"method": "pix"
    },
    "card_entry_datetime": "2023-06-07T10:29:49Z",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf",
    "items": [
        {
            "item_key":"37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 1,
            "status":"active",
            "invoice": {
                "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
                "due_date": "2023-07-10",
                "status": "opened"
                },
        },
        {
            "item_key":"60e4801f-75ce-411e-aaf0-99b951c05308",
            "amount": 1125,
            "used_limit":1121.4,
            "status":"active",
            "installment_number": 2,
            "invoice": {
                "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
                "due_date": "2023-08-10",
                "status": "opened"
                },
        }
	], 
    "status": "active"
}

PIX QR Code 交易 Response

{
    "transaction_key": "75b800f3-12ba-41b3-a7d5-cbb3ae2199f2",
    "end_to_end_id": "E324025022023082120064RNfdmEDTxV", 
    "transacted_at": "2023-08-21T20:07:46",
    "amount": 2242.8,
    "final_amount":2250,
    "number_of_installments": 2,
    "monthly_interest_rate": 0.027,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "description":"Compra Padaria do João",
    "disbursement": {
 		"method": "pix_qrcode",
        "data": {
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/a1908d67-bcc8-40cd-a63d-6b6fb510b35c5204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63042184",
            "end_to_end_id": "E3240250220220822211350711639780"
        }
    },
    "card_entry_datetime": "2023-06-07T10:29:49Z",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf",
    "items": [
        {
            "item_key":"37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 1,
            "status":"active",
            "invoice": {
                "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
                "due_date": "2023-07-10",
                "status": "opened"
                },
        },
        {
            "item_key":"60e4801f-75ce-411e-aaf0-99b951c05308",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 2,
            "status":"active",
            "invoice": {
                "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
                "due_date": "2023-08-10",
                "status": "opened"
                },
        }
	], 
    "status": "active"
}

Card Entry 状态枚举值

枚举值	描述
active	合同激活并已放款
pending_activation	合同等待放款
canceled	合同已取消
paid	合同已清算

4.2 生成交易凭证：

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/receipt

MÉTODO

GET

Response

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/receipt

MÉTODO

GET

HTTP STATUS

200

Response Body

    {
        "base64_receipt": ""
    }

5. 列出数字钱包的账单：

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoices

MÉTODO

GET

PARAMETERS

page, page_size

Response

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoices

MÉTODO

GET

HTTP STATUS

200

每页返回最多100条条目

Response Body

{
    "wallet_key": "9798d733-7f68-4929-8877-a00bfda9735e",
    "invoice_closing_day": 2,
    "invoice_due_day": 10,
    "page": "1",
	"last_page": "False",
    "invoices": [
        {
            "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
            "due_date": "2023-04-10",
            "closing_date": "2023-04-02",
            "status": "opened",
            "number_of_items": 2
        },
        {
            "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
            "due_date": "2023-05-10",
            "closing_date": "2023-05-02",
            "status": "opened",
            "number_of_items": 12
        },
        {
            "invoice_key": "26e18c39-8f67-4399-9a42-8d18bc175da2",
            "due_date": "2023-04-10",
            "closing_date": "2023-04-02",
            "status": "opened",
            "number_of_items": 1
        },
        {
            "invoice_key": "6991f8e6-7b1d-4496-a08f-8a9eef263f07",
            "due_date": "2023-06-10",
            "closing_date": "2023-06-02",
            "status": "opened",
            "number_of_items": 12
        }
    ]
    
}

6. 列出账单交易：

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]

MÉTODO

GET

Response

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]

MÉTODO

GET

HTTP STATUS

200

Response Body

{
    "due_date": "2023-06-10",
    "closing_date": "2023-06-02",
    "status": "closed",
    "amount": 12345.67,
    "paid_amount": 0,
    "delay_interest_total_amount": 0,
    "delay_fine_total_amount": 0,
    "number_of_items": 1,
    "invoice_payments": [
        {
            "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
            "invoice_payment_type": "bankslip",
            "charge_type": "ordinary",
            "data": {
                "digitable_line": "32990001039000000000104620768103992260000004183",
                "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8"
            },
            "expiration": "2023-07-10",
            "status": "opened",
            "total_amount": 0,
            "paid_amount": 0,
            "chargeback_amount": 50
        }
    ],
    "items": [
        {
            "item_key": "37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 12345.67,
            "used_limit": 12300,
            "status": "active",
            "card_entry": {
                "card_entry_key": "ad8e073a-2159-479b-b141-cd5d8ceb8567",
                "card_entry_datetime": "2022-11-13T10:29:49",
                "description": "Compra Padaria do João",
                "final_amount": 12345.67,
                "number_of_installments": 2,
                "card": {
                    "card_key": "d41bd53e-eedc-4d62-97dd-26bbaefadb20"
                }
            },
            "installment_number": 1
        }
    ]
}

条目状态枚举值

枚举值	描述
pending_activation	条目等待激活，条目金额计入账单金额
active	条目激活，条目金额计入账单金额
canceled	条目已取消，条目金额从账单金额中移除
paid	条目已在当月账单中付款，条目金额计入账单金额
paid_early	条目已提前付款，条目金额不再计入账单金额
reversed	条目在账单结账后取消，条目金额将产生退款

7. 生成 boleto：

普通 boleto 将在账单结账日自动生成，可通过账单付款的 GET 接口获取。查询参数"shorten_url"是请求缩短 boleto URL 的标志。

注意

boleto 可以在账单到期后30天内支付。

注意

URL 缩短限制为每分钟60次请求。

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]

MÉTODO

GET

PARAMETER

shorten_url

Response

参数 shorten_url=False

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]?shorten_url=False

MÉTODO

GET

HTTP STATUS

200

Response Body

    {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "ordinary",
        "data": {
            "bank_slip_key": "dc4a27db-2fe1-474d-aa02-88d6fffb8d0d",
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
            "bank_slip_url": "\<URL BOLETO EM PDF\>"
        },
        "expiration": "2023-07-10",
        "status": "issued",
        "total_amount": 0,
        "paid_amount": 0,
        "chargeback_amount": 50,
    }

参数 shorten_url=True

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]?shorten_url=True

MÉTODO

GET

HTTP STATUS

200

Response Body

    {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "ordinary",
        "data": {
            "bank_slip_key": "dc4a27db-2fe1-474d-aa02-88d6fffb8d0d",
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
            "bank_slip_url": "\<URL BOLETO EM PDF\>",
            "short_bank_slip_url": "\<URL BOLETO EM PDF ENCURTADA\>"
        },
        "expiration": "2023-07-10",
        "status": "issued",
        "total_amount": 0,
        "paid_amount": 0
    }

7.1 生成提前还款特别 boleto：

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment

MÉTODO

POST

Request Body

{
    "invoice_payment_type": "bankslip",
    "charge_type": "early",
    "expiration": "2023-08-15",
    "invoice_items": [
	    "key_1",
	    "key_2"
    ]
}

注意

条件："expiration"必须早于账单结账日至少两个工作日，以确保付款不会影响该例行程序。

Response

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment

MÉTODO

POST

HTTP STATUS

200

Response Body

     {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "early",
        "data": {
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
        },
        "expiration": "2023-08-15",
        "status": "issued",
        "total_amount": 200,
        "paid_amount": 0
 }

7.2 逾期特别 boleto 模拟：

注意

模拟只能在普通 boleto 的付款期限结束后才能申请。

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/simulation

MÉTODO

POST

Request Body

    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15"
    }

含折扣的请求

Request Body

    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15",
        "discount_amount": 50
    }

Response

Response Body

    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "total_amount": 150,
        "discount_amount": 50
    }

7.3 生成逾期特别 boleto：

注意

逾期 boleto 只能在普通 boleto 的付款期限结束后才能生成。

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment

MÉTODO

POST

Request Body

    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15"
    }

含折扣的请求

Request Body

    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15",
        "discount_amount": 50
    }

Response

Response Body

    {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "data": {
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
        },
        "expiration": "2023-07-10",
        "status": "issued",
        "total_amount": 0,
        "paid_amount": 0,
        "discount_amount": 50
    }

7.4 取消账单付款 boleto

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]

MÉTODO

DELETE

Response

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]

MÉTODO

DELETE

HTTP STATUS

204

Response Body

{}

8. 退款：

8.1. 查询退款：

Request

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/chargebacks

MÉTODO

GET

PATH PARAMETERS

枚举值	描述
status	退款状态（'active'/'used'/'pending_payment'）

Response

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/chargebacks

MÉTODO

GET

HTTP STATUS

200

Response Body

    {
        "page": 1,
        "last_page": true,
        "data": [
            {
                "charge_back_key": "key",
                "amount": 100,
                "used_amount": 0,
                "status": "active",
                "reference_card_entry_key": "key",
                "reference_item_key": "key"
            }
        ]
    }

9. Webhooks：

9.1. 账单状态变更：

Webhook

WEBHOOK_TYPE

card_invoice.invoice.status_change

STATUS

opened

Webhook Body

{
	"webhook_type": "card_invoice.invoice.status_change",
	"key": "\<INVOICE-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "opened",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "due_date": "2023-07-10",
        "closing_date": "2023-07-02"
    }
}

注意

"data"字段的内容对所有状态保持相同格式。

账单状态枚举值

枚举值	描述
opened	账单已开启
closed	账单已关闭
paid	账单在到期日内已付款
paid_overdue	账单逾期后已付款

9.2. 交易状态变更：

Webhook

WEBHOOK_TYPE

card_invoice.card_entry.status_change

STATUS

active

Webhook Body

{
	"webhook_type": "card_invoice.card_entry.status_change",
	"key": "\<CARD-ENTRY-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "active",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>"
    }
}

Card Entry 状态枚举值

枚举值	描述
active	合同激活并已放款
canceled	合同已取消

注意

此 webhook 仅在交易处于"pending_activation"状态时才会发送。

9.3. 账单结账后生成 boleto：

Webhook

WEBHOOK_TYPE

card_invoice.invoice_payment.status_change

STATUS

issued

Webhook Body

{
	"webhook_type": "card_invoice.invoice_payment.status_change",
	"key": "\<INVOICE-PAYMENT-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "issued",
    "data": {
        "charge_type": "ordinary",
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "invoice_key":"\<CHAVE DA FATURA\>",
        "digitable_line":"\<LINHA DIGITAVEL DO BOLETO\>",
        "qr_code_url":"\<URL DO QR CODE DO BOLETO\>"
    }
}

付款类型枚举值

枚举值	描述
ordinary	普通付款
early	提前还款特别付款
delay	逾期特别付款

9.4. 账单付款状态变更：

Webhook

WEBHOOK_TYPE

card_invoice.invoice_payment.status_change

STATUS

paid

Webhook Body

{
	"webhook_type": "card_invoice.invoice_payment.status_change",
	"key": "\<INVOICE-PAYMENT-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "paid",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "charge_type": "ordinary",
        "invoice_key":"\<CHAVE DA FATURA\>",
        "paid_amount": 150.0
    }
}

账单付款状态枚举值

枚举值	描述
issued	已发行账单付款 boleto
paid	boleto 已付款
canceled	boleto 付款已取消

9.5. 退款状态变更：

Webhook

WEBHOOK_TYPE

card_invoice.chargeback.status_change

STATUS

active

Webhook Body

{
	"webhook_type": "card_invoice.chargeback.status_change",
	"key": "\<CHARGEBACK-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "active",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "chargeback_amount":150.00,
        "reference_card_entry_key":"\<CHAVE DA TRANSAÇÃO DE REFERÊNCIA DO ESTORNO\>",
        "reference_item_key" :"\<CHAVE DO ITEM DE REFERÊNCIA DO ESTORNO\>"
    }
}

退款状态枚举值

枚举值	描述
active	退款已激活，可用于账单付款
used	退款已用于账单付款
pending_payment	退款等待付款以激活

'pending_payment' 状态

pending_payment 状态表示属于已关闭但尚未付款的账单的条目退款，退款金额只能在账单付款后才能使用。

9.6.1 交易重新协商拒绝：

Webhook

WEBHOOK_TYPE

card_invoice.renegotiation.status_change

STATUS

rejected

Webhook Body

{
    "webhook_type": "card_invoice.renegotiation.status_change",
    "key": "\\<RENEGOTIATION-KEY\\>",
    "event_datetime": "\\<DATA E HORA DO ENVIO DO WEBHOOK\\>",
    "status": "rejected",
    "data": {
        "wallet_key": "\\<CHAVE DA CARTEIRA\\>"
    }
}

9.6.2 交易重新协商付款：

Webhook

WEBHOOK_TYPE

card_invoice.renegotiation.status_change

STATUS

paid

Webhook Body

{
    "webhook_type": "card_invoice.renegotiation.status_change",
    "key": "\\<RENEGOTIATION-KEY\\>",
    "event_datetime": "\\<DATA E HORA DO ENVIO DO WEBHOOK\\>",
    "status": "paid",
    "data": {
        "wallet_key": "\\<CHAVE DA CARTEIRA\\>",
        "paid_method_type": "<METODO DE PAGAMENTO>",
        "paid_in": {
            "code_number": "<CODIGO DO BANCO LIQUIDANTE>", 
            "ispb": "<ISPB DO BANCO LIQUIDANTE>", 
            "name": "<NOME DO BANCO LIQUIDANTE>"
        }
    }
}

重新协商状态枚举值

枚举值	描述
pending_payment	提前还款重新协商等待付款
paid	提前还款重新协商已付款
canceled	提前还款重新协商已取消
rejected	由于在重新协商外分期付款或超过期限，提前还款重新协商被拒绝

10. 7天内取消购买：

10.1. 申请取消购买：

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/reversal

MÉTODO

POST

Request

Request Body

{}

Response

Response Body

    {
      "amount": "2026.93",
      "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.dev.qitech.app/bacen/cobv/dece8d3e-32ce-439e-8204000053039865802BR5925Joao61080150400062070503***63046ECD",
      "expiration_date": "2022-09-28"
    }

10.2. 查询有效的取消购买：

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/reversal

MÉTODO

GET

Response

Response Body

    {
      "amount": "2026.93",
      "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.dev.qitech.app/bacen/cobv/dece8d3e-32ce-439e-8204000053039865802BR5925Joao61080150400062070503***63046ECD",
      "expiration_date": "2022-09-28"
    }

11. 购买重新协商：

11.1. 模拟购买重新协商：

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/renegotiation/simulation

MÉTODO

POST

Request

Request Body

{
    "reference_date": "2024-07-20",
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e"
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea"
        }
    ]
}

Request body 详情

字段	类型	描述	字符数
`reference_date`	string	重新协商的参考日期。

Response

Response Body

    {
    "renegotiation_payment_amount": 350,
    "reference_date": "2022-07-20",
    "discount_percentage": 0,
    "discount_amount": 0,
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "payment_amount": 125,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea",
            "payment_amount": 225,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "1249249c-95b5-45aa-81f1-967abf5e6eef",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                },
                {
                    "item_key": "c66dad81-ecb4-4afa-8713-a85ee8e721ec",
                    "due_date": "2022-08-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 100,
                    "present_amount": 120
                }
            ]
        }
    ]
}

11.2. 创建购买重新协商：

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/renegotiation

MÉTODO

POST

'items' 对象

当未提供"items"对象时，将视为交易中所有可用条目都包含在重新协商中，即状态非"active"的条目将被忽略。

此外，如果钱包已有等待付款的重新协商，必须先取消才能生成新的重新协商。

Request

Request Body

{
    "reference_date": "2024-07-20",
    "proposal_due_date": "2024-07-27",
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e"
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea"
        }
    ]
}

折扣字段

在请求中添加以下任一字段可以在创建或模拟重新协商方案时设置百分比或绝对折扣金额。

百分比折扣

{
  "discount_percentage": 0.5
}

绝对折扣

{
  "discount_amount": 200
}

Request body 详情

字段	类型	描述	字符数
`reference_date`	string	重新协商的参考日期。
`proposal_due_date`	string	重新协商方案的到期日。

Response

Response Body

{
    "renegotiation_key": "2af29916-582b-4ce7-8440-352a0d9543f7",
    "renegotiation_payment_amount": 350,
    "reference_date": "2022-07-20",
    "renegotiation_status": "pending_payment",
    "proposal_due_date": "2022-07-27",
    "discount_percentage": 0,
    "discount_amount": 0,
    "payment": {
        "digitable_line": "",
        "qr_code_url": "",
        "qr_code_key": "",
        "bank_slip_key": "",
        "paid_method_type": null
    },
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "payment_amount": 125,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea",
            "payment_amount": 225,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "1249249c-95b5-45aa-81f1-967abf5e6eef",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                },
                {
                    "item_key": "c66dad81-ecb4-4afa-8713-a85ee8e721ec",
                    "due_date": "2022-08-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 100,
                    "present_amount": 120
                }
            ]
        }
    ]
}

Response body 详情

字段	类型	描述
`reference_date`	string	重新协商的参考日期。
`proposal_due_date`	string	重新协商方案的到期日。
`renegotiation_key`	string	重新协商的唯一标识符（uuid）。
`renegotiation_payment_amount`	number	重新协商的总金额。
`discount_percentage`	number	重新协商中要应用的百分比折扣值。
`discount_amount`	number	重新协商中要应用的绝对折扣值。
`payment`	object	包含重新协商付款信息的对象。
`card_entries`	list	要重新协商的交易及其各自分期的列表。

11.3. 查询现有购买重新协商：

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/renegotiation/[RENEGOTIATION-KEY]

MÉTODO

GET

QUERY PARAMETERS

枚举值	描述
shorten_url	请求缩短 boleto URL 的参数

Response

Response Body

{
    "renegotiation_key": "2af29916-582b-4ce7-8440-352a0d9543f7",
    "renegotiation_payment_amount": 350,
    "reference_date": "2022-07-20",
    "renegotiation_status": "pending_payment",
    "proposal_due_date": "2022-07-27",
    "discount_percentage": 0,
    "discount_amount": 0,
    "payment": {
        "digitable_line": "",
        "qr_code_url": "",
        "qr_code_key": "",
        "bank_slip_key": "",
        "paid_method_type": null,
        "bank_slip_url": "\<URL BOLETO EM PDF\>",
        "short_bank_slip_url": "\<URL BOLETO EM PDF ENCURTADA\>"
    },
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "payment_amount": 125,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea",
            "payment_amount": 225,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "1249249c-95b5-45aa-81f1-967abf5e6eef",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                },
                {
                    "item_key": "c66dad81-ecb4-4afa-8713-a85ee8e721ec",
                    "due_date": "2022-08-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 100,
                    "present_amount": 120
                }
            ]
        }
    ]
}

11.4. 手动取消重新协商：

ENDPOINT

/card_invoice/wallet/[WALLET-KEY]/renegotiation/[RENEGOTIATION-KEY]

MÉTODO

DELETE

Response

Response Body

{
    "renegotiation_key": "2af29916-582b-4ce7-8440-352a0d9543f7",
    "renegotiation_status": "canceled"
}

12. 场景模拟：

12.1. 账单结账：

DUE_DATE

due_date 字段为可选字段，未填写时账单保留已设定的到期日。结账日不能设置为未来日期，到期日不能早于结账日。

ENDPOINT

/mock/card_invoice/invoice/[INVOICE-KEY]/close

MÉTODO

PATCH

Request

Request Body

{
    "closing_date":"2024-10-08",
    "due_date":"2024-10-20"
}

Response

Response Body

{}

带 PIX 分期付款的卡片体验​

1. 创建数字钱包​

Request​

Request body 详情​

Wallet payload​

owner 对象​

address 对象​

phone 对象​

invoice_configuration 对象​

Response​

Response body 详情​

1.1. 查询现有钱包：​

QUERY PARAMETERS​

Request​

Response​

1.2. 查询特定钱包：​

Request​

Response​

1.3. 修改钱包限额：​

Request​

Response​

2. 向现有数字钱包添加卡片：​

Request​

Request body 详情​

Card payload​

Response​

Response body 详情​

3. 模拟操作：​

Request​

Response​

4. 在卡片中添加交易：​

Request​

Response​

4.1 查询特定交易（card entry）：​

Request​

Response​

Card Entry 状态枚举值​

4.2 生成交易凭证：​

Request​

Response​

5. 列出数字钱包的账单：​

Request​

Response​

6. 列出账单交易：​

Request​

Response​

条目状态枚举值​

7. 生成 boleto：​

Request​

Response​

参数 shorten_url=False​

参数 shorten_url=True​

7.1 生成提前还款特别 boleto：​

Request​

Response​

7.2 逾期特别 boleto 模拟：​

Request​

含折扣的请求​

Response​

7.3 生成逾期特别 boleto：​

Request​

含折扣的请求​

Response​

7.4 取消账单付款 boleto​

Request​

Response​

8. 退款：​

8.1. 查询退款：​

Request​

PATH PARAMETERS​

Response​

9. Webhooks：​

9.1. 账单状态变更：​

Webhook​

账单状态枚举值​

9.2. 交易状态变更：​

Webhook​

Card Entry 状态枚举值​

9.3. 账单结账后生成 boleto：​

Webhook​

带 PIX 分期付款的卡片体验

1. 创建数字钱包

Request

Request body 详情

Wallet payload

owner 对象

address 对象

phone 对象

invoice_configuration 对象

Response

Response body 详情

1.1. 查询现有钱包：

QUERY PARAMETERS

Request

Response

1.2. 查询特定钱包：

Request

Response

1.3. 修改钱包限额：

Request

Response

2. 向现有数字钱包添加卡片：

Request

Request body 详情

Card payload

Response

Response body 详情

3. 模拟操作：

Request

Response

4. 在卡片中添加交易：

Request

Response

4.1 查询特定交易（card entry）：

Request

Response

Card Entry 状态枚举值

4.2 生成交易凭证：

Request

Response

5. 列出数字钱包的账单：

Request

Response

6. 列出账单交易：

Request

Response

条目状态枚举值

7. 生成 boleto：

Request

Response

参数 shorten_url=False

参数 shorten_url=True

7.1 生成提前还款特别 boleto：

Request

Response

7.2 逾期特别 boleto 模拟：

Request

含折扣的请求

Response

7.3 生成逾期特别 boleto：

Request

含折扣的请求

Response

7.4 取消账单付款 boleto

Request

Response

8. 退款：

8.1. 查询退款：

Request

PATH PARAMETERS

Response

9. Webhooks：

9.1. 账单状态变更：

Webhook

账单状态枚举值

9.2. 交易状态变更：

Webhook

Card Entry 状态枚举值

9.3. 账单结账后生成 boleto：

Webhook