Laravel Boleto 集成 PIX 终极指南在 Boleto 上渲染 copia-e-cola 二维码与付款链接【免费下载链接】laravel-boletoPacote para gerar boletos e remessas项目地址: https://gitcode.com/gh_mirrors/la/laravel-boletolaravel-boleto 是一个面向 Laravel 的巴西电子汇票Boleto生成工具包支持生成 Boleto、CNAB 240/400 汇款文件remessa并解析回执文件retorno。它的 PIX 集成能力让传统 Boleto 票面上直接渲染copia-e-cola复制粘贴字符串、EMV 格式的 PIX 二维码甚至支持动态 PIX付款链接。本指南带你快速上手只需一个pix_qrcode参数就能让 PDF 版 Boleto 同时具备扫一下和输一串两种收款方式 为什么要在 Boleto 上加 PIX 收款PIX 是巴西央行的即时支付系统用户可用 App 扫码或用 copia-e-cola 字符串粘贴付款。把 PIX 二维码印在 Boleto 票面上收款方无需等待 1~2 个工作日的传统清算周期客户付款意愿也更高。laravel-boleto 的 PIX 功能集中在以下模块能力位置票面 QR Code 渲染PDF/HTMLsrc/Boleto/Render/Pdf.php、src/Boleto/Render/Html.phpcopia-e-cola 生成与解析src/Util.php票面字段与票面布局src/Boleto/AbstractBoleto.php、src/Boleto/Render/view/partials/ficha-compensacao.blade.phpLaravel Boleto 票面可渲染 PIX copia-e-cola 二维码与行内数字可打印行一键上手在 Boleto 上输出 PIX 二维码核心思路只有一句话创建 Boleto 时传入pix_qrcode参数渲染 PDF 时票面就会出现 PIX 二维码。下面三种写法任选其一。方式一传 copia-e-cola 字符串推荐把 EMV 格式的 copia-e-cola 字符串直接传给pix_qrcode库会自动转成二维码图片。参考示例pix_boleto_qrcode_copia_cola.php。$boleto new Eduardokum\LaravelBoleto\Boleto\Banco\Itau([ beneficiario $beneficiario, pagador $pagador, valor 100, numero 1, // EMV copia-e-cola 字符串以 000201 开头 pix_qrcode 00020104141234567890123426660014BR.GOV.BCB.PIX01..., ]);字符串过长时可用省略展示实际传入完整字符串即可。方式二传 base64 图片如果二维码由你方系统或银行接口生成可直接传 base64 图片数据纯 base64见 pix_boleto_qrcode_img.php带data:image/png;base64,...前缀的 Data URI见 pix_boleto_qrcode_img_data.php两种方式内部都会经过getPixQrCodeBase64()统一处理src/Boleto/AbstractBoleto.php自动识别是 base64 还是 EMV 文本。方式三传 PIX 键让库自动生成 copia-e-cola不想自己拼 EMV 字符串只要提供PIX 键 键类型调用gerarPixCopiaECola()就能根据票面金额和 Beneficiário 信息自动生成标准 copia-e-cola实现见 Util.php 的gerarPixCopiaECola$boleto-setPixChave(financeiroempresa.com.br); $boleto-setPixChaveTipo(\Eduardokum\LaravelBoleto\Boleto\AbstractBoleto::TIPO_CHAVEPIX_EMAIL); $copiaECola $boleto-gerarPixCopiaECola(); // 自动写入 pix_qrcode支持的键类型CPF、CNPJ、手机号、EMAIL、随机 UUID。传错格式比如 CPF 位数不对会抛出ValidationException属于快速失败设计方便联调时定位问题。动态 PIX付款链接如果pix_chave是一个 URL银行返回的 PIX 动态链接gerarPixCopiaECola会自动走 EMV 的25字段Dynamic QR Code金额由银行端确认这正是付款链接场景的实现路径。选择二维码在票面上的位置默认二维码印在付款说明区域。想放到条形码旁边只需在渲染前切换位置$pdf new Eduardokum\LaravelBoleto\Boleto\Render\Pdf(); $pdf-addBoleto($boleto); // 位置一付款说明区默认 $pdf-setLocalizacaoPix(Eduardokum\LaravelBoleto\Boleto\Render\Pdf::PIX_INSTRUCAO); // 位置二条形码右侧 // $pdf-setLocalizacaoPix(Eduardokum\LaravelBoleto\Boleto\Render\Pdf::PIX_COD_BARRAS); echo $pdf-gerarBoleto();HTML 渲染Html.php与 Caixa 专用渲染器PdfCaixa.php都提供相同开关完整示例见 pix_boleto_qrcode_copia_cola_localizacao.php。传其他值会抛出ValidationException提示避免悄悄渲染到错误位置。二维码风格方块还是圆点通过qr_code_style参数控制视觉风格src/Boleto/AbstractBoleto.php常量效果QRCODE_ESTILO_QUADRADOsquare经典方块模块默认QRCODE_ESTILO_PONTOdot圆点模块更接近银行 App 风格qr_code_style Eduardokum\LaravelBoleto\Boleto\Banco\Itau::QRCODE_ESTILO_PONTO,解析回执Retorno里的 copia-e-cola银行回执文件中也会带回 copia-e-cola或 location 地址解析示例见 pix_retorno.php$retorno Eduardokum\LaravelBoleto\Cnab\Retorno\Factory::make(arquivos/xxx.ret); $retorno-processar(); $detalhe $retorno-getDetalhe(1); $detalhe-getPixQrCode(); // 回执中返回的 copia-e-cola $detalhe-getLocation(); // 动态 PIX 的 location 地址 // 也可按本方 Beneficiário 重新生成一份 copia-e-cola $detalhe-gerarPixCopiaECola(EMPRESA, SÃO PAULO, true);Util::decodePixCopiaECola()还能把任意 copia-e-cola 字符串解析成键值对数组可用于校验银行返回内容与预期是否一致。常见问题速查票面上没有二维码确认 Boleto 对象设置了pix_qrcode或调用过gerarPixCopiaECola()未设置时渲染器会跳过 QR 区域不会报错。二维码扫不出来copia-e-cola 必须是完整 EMV 串以000201开头、以 CRC16 结尾截断或多余空格都会导致无法解码。传了键却报错检查setPixChaveTipo的常量与setPixChave是否成对设置且键值格式与类型匹配如 EMAIL 需是合法邮箱。金额没写进二维码静态键会在54字段写入票面金额动态链接25字段不带金额由银行端确认属正常现象。小结pix_qrcode传 copia-e-cola 字符串或 base64 图片票面自动出 QR Codepix_chavegerarPixCopiaECola()按 PIX 键一键生成 copia-e-colaURL 键即为动态 PIX 付款链接setLocalizacaoPix()控制二维码印在说明区还是条形码旁qr_code_style方块/圆点两种风格随需切换Retorno 端可读取银行返回的 copia-e-cola / location完成对账闭环照着 exemplos/ 目录下的pix_boleto_*.php系列示例几分钟就能把 PIX 能力接入你的 Laravel 收票流程。【免费下载链接】laravel-boletoPacote para gerar boletos e remessas项目地址: https://gitcode.com/gh_mirrors/la/laravel-boleto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考