- Pix 二维码: 客户使用银行应用程序扫描动态二维码。
- Pix 复制粘贴(Copia e Cola): 客户复制 Pix 代码并将其粘贴到他们的银行或数字钱包应用程序中以发起转账。
开始之前
请确保您已备好:- 有效的 API 凭证(访问令牌)。
步骤 1. 创建 Pix 付款
要生成用于在巴西收款的 Pix 付款,请向 创建 Payin endpoint 发送POST 请求,并附带 Pix 专用参数。
关键请求参数
该请求需要几个与二维码支付相关的关键对象:| 对象 | 描述 | 必需的 |
|---|---|---|
paymentMethod.type | 必须是 BankTransfer。 | ✅ |
paymentMethod.code | Pix 请使用 1314。 | ✅ |
sender | 发件人信息,用于合规性审查。 | ✅ |
merchant | 商家/企业详情。 | ✅ |
paymentMethod | 支付方式配置。 | ✅ |
amount | 交易金额。 | ✅ |
currency | 交易货币代码。 | ✅ |
country | 必须是 BRA。 | ✅ |
两种方法使用相同的 endpoint: 此 API 请求用于生成 Pix 二维码和 Pix 复制粘贴(Copia e Cola) 的付款信息。客户使用哪种方法取决于您如何呈现响应中返回的付款详情。
示例请求
以下是使用curl 的示例:
curl
curl --request POST \
--url https://api.stage.localpayment.com/api/payin/ \
--header 'accept: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'content-type: application/json' \
--data '
{
"paymentMethod": {
"type": "BankTransfer",
"code": "1314",
"flow": "DIRECT"
},
"currency": "USD",
"merchant": {
"type": "COMPANY",
"document": {
"type": "",
"id": ""
},
"name": "Company",
"email": ""
},
"payer": {
"type": "INDIVIDUAL",
"document": {
"id": "75.518.609/0001-56",
"type": "CNPJ"
},
"bank": {
"account": {
"type": "C"
}
},
"name": "John",
"lastname": "Doe"
},
"externalId": "3d3b3e1d-c234-4fde-8e87-cd61b7dde3cf",
"country": "BRA",
"amount": 1000,
"accountNumber": "{{accountNumber}}",
"conceptCode": "0003",
"comment": "Any relevant information related to the transaction"
}
'
步骤 2. 处理响应
成功响应
成功创建 Pix 付款会返回 Pix 代码数据和付款详情:{
"transactionType": "PayIn",
"externalId": "3d3b3e1d-c234-4fde-8e87-cd61b7dde3cf",
"internalId": "7e57a8ed-7fa4-4264-bcf3-a44d3ff2c132",
"paymentMethod": {
"type": "BankTransfer",
"code": "1314",
"flow": "DIRECT"
},
"country": "BRA",
"currency": "USD",
"amount": 1000,
"accountNumber": "{{accountNumber}}",
"confirmed": {
"currency": "USD",
"amount": 1000,
"fxQuote": 1,
"exchangeRateToken": null
},
"payment": {
"installment": null,
"currency": "BRL",
"fxQuote": 4.96637604,
"financingFee": 0,
"amount": 4966.38
},
"localTaxes": [],
"withHoldings": [],
"fees": {
"description": "Fee",
"currency": "USD",
"fxSource": 1,
"fxQuote": 1,
"amount": 11,
"account": "{{accountNumber}}"
},
"status": {
"code": "100",
"description": "INPROGRESS",
"detail": "The payin is pending the confirmation"
},
"ticket": null,
"qr": {
"image": "https://api.stage.localpayment.com/api/images/1314/00020126580014br.gov.bcb.pix013627a44d0a-0736-4bbf-a4a4-6e11063973315204000053039865406150.005802BR5911Telequiet496008Campinas62230519mpqrinter12397252666304FA23",
"code": "00020126580014br.gov.bcb.pix013627a44d0a-0736-4bbf-a4a4-6e11063973315204000053039865406150.005802BR5911Telequiet496008Campinas62230519mpqrinter12397252666304FA23",
"codeBase64": "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",
"expirationDate": "2022-08-13T12:28:09.695-04:00"
},
"beneficiary": null,
"merchant": {
"type": "COMPANY",
"name": "Company",
"document": {
"id": "",
"type": ""
},
"email": "",
"phone": {
"countryCode": "",
"areaCode": "",
"number": ""
},
"address": {
"street": "",
"number": "",
"city": "",
"state": "",
"country": "",
"zipCode": "",
"comment": "Any relevant information related to the transaction"
},
"birthdate": "",
"nationality": ""
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastname": "Doe",
"document": {
"id": "75.518.609/0001-56",
"type": "CNPJ"
},
"email": "",
"phone": {
"countryCode": "",
"areaCode": "",
"number": ""
},
"address": {
"street": "",
"number": "",
"city": "",
"state": "",
"country": "",
"zipCode": ""
},
"birthdate": "",
"nationality": ""
},
"intermediaries": null,
"wireInstructions": null,
"date": {
"creationDate": "2025-02-19T20:57:50.253+00:00",
"processedDate": "2025-02-19T20:57:50.507088",
"expirationDate": "2025-02-21T20:57:50.507088"
},
"card": null,
"errors": []
}
{
"transactionType": "PayIn",
"externalId": "18c12cfb-a4ea-c0bd-983b-51ac394a7439",
"internalId": "8d9c5ae3-929d-105b-c59d-1c59e3096688",
"paymentMethod": {
"type": "BankTransfer",
"code": "1314",
"flow": "DIRECT"
},
"country": "BRA",
"currency": "BRL",
"amount": 1000.0,
"accountNumber": "{{accountNumber}}",
"confirmed": {
"currency": "BRL",
"amount": 1000.0,
"fxQuote": 1.0
},
"payment": {
"currency": "BRL",
"fxQuote": 1.0,
"financingFee": 0.0,
"amount": 1000.0
},
"localTaxes": [
{
"code": "0028",
"percentage": 3.5,
"description": "NUEVO IOF",
"currency": "BRL",
"fxSource": 5.388318,
"fxQuote": 0.0,
"amount": 35.0,
"account": "{{accountNumber}}"
}
],
"withHoldings": [],
"fees": {
"description": "Fee",
"currency": "BRL",
"fxSource": 5.388318,
"fxQuote": 1.0,
"amount": 0.0,
"account": "{{accountNumber}}"
},
"status": {
"code": "100",
"description": "INPROGRESS",
"detail": "The payin is pending the confirmation"
},
"qr": {
"image": "https://api.stage.localpayment.com/api/images/QR/00020101021226880014br.gov.bcb.pix2566qrcode-h.fitbank.com.br%2FQR%2Fcob%2FC5F29B1D537A2040C62359BA425F7D5B09B5204000053039865802BR5912Localpayment6008CAMPINAS61081310582262070503%2A%2A%2A630475C7",
"code": "00020101021226880014br.gov.bcb.pix2566qrcode-h.fitbank.com.br/QR/cob/C5F29B1D537A2040C62359BA425F7D5B09B5204000053039865802BR5912Localpayment6008CAMPINAS61081310582262070503***630475C7",
"codeBase64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAAC4klEQVR4Xu2XMc7bMAyFaWjQZl9AgK6hTVdyLuDYF4ivpE3XMKAL2JsGwexjij9Oi3aIBBQdfiFIYn1B6JDU4wvx3xb9vvFa3+SbyPqXJFCXC3l1+nJjXiORbiCRj8CzVrNTD1dGbbHTQOiWt9Hx6WgI9tSmayRhI0/3YBfeet9Msj09z2TIl4EbCR8xsQRBUk3Hv2TnY4L6RHO7Hr9U7mOCldPC9mCLKu3+51YtCTTSdo94tqcr95AeAmtJNpOzs+M1IBnb5O36lYMaEjbEmXS5RfUg02V0ZQPJKAgN8ma7B3Vq6lsIq5kSYBft7rZR895CgplIsoimvmVcm943ELZLNkNQKz7i1e54+cpoDcnmHkwvYqCOqFamoYUEfDd6x0Jjdo++tkcLyfah0Ttp19vopXeuTqwgEXuli+mIuHe7hPTqxBrC6fQ0+jLpbYCguisHNSQkXEH5iNLpkIO33qkg2SKpeH3oQsQPr96y8zmJG5GCtOxEkza3cN11DZGjRkNGX6sD0qJLE+GCidH755nzpteShgZi7ngrcUBEZq44FSSjMpg/ZSTqibqATDSQ5zmDBiwyOnjNfNWngiCOL9B4aPPpZeSOb3fwOSk9ld49vYmIlp1fcSqIFFmm0IThw+bdodQQDAoHI4CDq3BiDkhpG5k9dFTKsuMc++3q+ArCdsV4hETphF9/vmlVDYl2pkIOMB3BkDbXHVQQ5hNjltPuCA2+ZF5lr5aISdw6eAovskf6rXcqSOCTYCswxCDJCHLloIbARHhCRjG9V5YcvHxiFYGIliHbNdhd0x05aCHBHhmeAjpqH26biPAPoJ5gRVQ7iU/0Uqu3an9OICpIqlcLDOwzBy+tqiHw15AEBxsrXhga//JiVYRuUbQKaopmhJq+eqeSYOw4PhDH4xK2opGg+3DUEnRr95ZlVRPYavwjQRycYIjf5a9riNRHPOwQ4KHEeF5uo4L8eX2TbyLrfyY/AFFaGvzwyar/AAAAAElFTkSuQmCC",
"expirationDate": "2026-01-15T23:59:59",
"paymentInstructions": "<div><b>Two ways to pay:</b></div><div><ul><li>Scan the QR code:</li></ul></div><div>Open your bank app → Scan → Pay</div><div>-OR-</div><div><ul><li>Copy & paste (“Copia e Cola”)</li></ul></div><div>Copy “Copia e Cola” ID→ Open your bank app → Paste → Pay</div>"
},
"merchant": {
"type": "COMPANY",
"name": "Merchant",
"document": {
"type": "CNPJ",
"id": "34669130000133"
},
"email": "info@email.com"
},
"payer": {
"bank": {
"name": "Bank name",
"code": "341",
"branch": {
"code": "0004",
"name": "Santander"
},
"account": {
"type": "s",
"number": "000000000"
}
},
"type": "COMPANY",
"name": "Payer Name",
"lastname": "BRASIL",
"document": {
"type": "CNPJ",
"id": "34669131234567"
},
"email": "user@example.com"
},
"intermediaries": [],
"date": {
"creationDate": "2026-01-08T15:01:33.44+00:00",
"processedDate": "2026-01-08T15:01:37.6484808",
"expirationDate": "2026-01-15T23:59:59"
},
"paymentInstructions": "<div><b>Two ways to pay:</b></div><div><ul><li>Scan the QR code:</li></ul></div><div>Open your bank app → Scan → Pay</div><div>-OR-</div><div><ul><li>Copy & paste (“Copia e Cola”)</li></ul></div><div>Copy “Copia e Cola” ID→ Open your bank app → Paste → Pay</div>",
"errors": []
}
关键响应字段
| 参数 | 描述 | 用例 |
|---|---|---|
qr.image | 二维码的 Base64 编码 PNG 图片。 | 直接显示,无需额外生成。 |
qr.code | EMVCo 标准中的原始 Pix 有效载荷。 | 该字符串可以渲染成二维码,也可以显示为文本代码,供客户复制并粘贴到他们的银行应用程序(Copia e Cola)中。 |
qr.codeBase64 | 另一种采用 base64 编码的二维码有效载荷。 | 自定义二维码渲染备份。 |
qr.expirationDate | 二维码失效的时间戳。 | 显示倒计时器并处理过期逻辑。 |
externalId | 您的原始参考编号。 | 内部核对和订单匹配。 |
status.code | 当前交易状态(100 = INPROGRESS) | 确定付款流程的后续步骤。 |
date.creationDate | 交易创建时。 | 分析和绩效跟踪。 |
错误响应
当巴西地区的 Pix 生成失败时,您将收到具体的错误信息:{
"externalId": "ce0aaa1a-4532-43b9-930a-26e780aba99b",
"status": {
"code": "812",
"description": "REJECTED"
},
"errors": [
{
"code": "812",
"detail": "External Id already used - duplication"
}
]
}
步骤 3. 展示 Pix 付款
您可以通过两种方式之一向客户展示 Pix 付款。API 响应提供了两种方式所需的数据。选项 A:以二维码形式显示
- 生成二维码: 使用 API 响应中
qr.code字段的字符串,通过任意二维码库生成可扫描的二维码图片。 - 客户扫描: 客户使用银行应用程序扫描二维码。
- 授权: 客户在其应用程序内确认付款详情并授权转账。
- 实时确认:Localpayment 可立即收到付款通知。
- 状态更新:您的系统已收到包含付款确认信息的 webhook。

二维码展示的最佳实践
- 移动扫描的最小显示尺寸:250x250 像素。
- 保持 1:1 宽高比,不失真。
- 确保高对比度(浅色背景上使用深色)。
- 在二维码周围添加静默区(白色边框)。
- 添加替代文字(例如“二维码支付”)。
- 显示清晰的付款说明。
- 处理生存时间(TTL)和过期时间。
选项 B:显示为复制粘贴代码(Copia e Cola)
- 展示代码: 将
qr.code字段中的完整字符串以可选择文本的形式展示给客户。 - 客户复制粘贴: 客户复制整个代码并打开他们的银行或数字钱包应用程序。
- 粘贴支付: 客户将代码粘贴到应用程序的“使用 Pix 代码支付”或类似字段中,以加载支付详情。
- 授权: 客户审核并授权转账。
- 实时确认:Localpayment 可立即收到付款通知。
- 状态更新:您的系统已收到包含付款确认信息的 webhook。

步骤 4. 跟踪交易状态
您可以通过以下方式监控 Pix 付款进度:Webhooks(推荐)
交易状态变更时接收实时通知。最适用于生产环境。
状态 API endpoint
以编程方式查询交易状态。可用于轮询或恢复丢失的 webhook 通知。
Business Portal 视图
用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。
常用状态码
Localpayment API 提供各种状态代码,以在响应中指示付款的进度和结果。| 代码 | 状态 | 描述 |
|---|---|---|
103 | APPROVED | 付款已确认,但尚未到账。 |
200 | Completed | 付款已完成。 |
811 | Rejected | 请求金额高于或低于允许的最大/最小值。 |
完整参考请查看我们的交易状态文档,了解所有状态代码。
测试您的集成
沙盒环境
使用测试环境:https://api.stage.localpayment.com/api/payin/
测试二维码场景
请确认您的集成方案能够处理以下场景:- 付款成功:Pix 付款已完成,即时结算。
- 二维码过期:妥善处理过期的 Pix 付款。
- 多次支付尝试:同一个二维码被多次扫描。
- 状态更新:Webhook 处理和状态轮询。
后续步骤
实施 Pix 支付后,请考虑以下附加功能:退款
如有必要,您可以将款项退还给客户。详情请参阅相关文档。
查看交易详情
您可以使用 Localpayment API 获取交易信息,以获得更详细的分析。

