Efecty现金收款API接入教程商家APP应用2026最新

Efecty现金收款API接入教程商家APP应用2026最新

要点速读（TL;DR）

• Efecty 是哥伦比亚主流的现金支付网络，允许消费者在线下单后线下现金付款。
• 跨境卖家可通过API接入将 Efecty 支付方式集成至独立站或电商平台。
• 2026年更新重点：商家APP功能增强、API响应优化、商户审核流程电子化。
• 主要适用于面向哥伦比亚市场销售的中国跨境卖家，尤其是中低价商品。
• 需准备企业营业执照、银行账户信息、税务登记文件等材料完成商户入驻。
• 常见失败原因包括IP限制、回调地址未验证、KYC资料不全，建议提前测试沙箱环境。

Efecty现金收款API接入教程商家APP应用2026最新 是什么

Efecty 是哥伦比亚领先的非银行支付网络，为无银行卡人群提供线上订单+线下现金支付服务。用户在电商平台选择 Efecty 后生成支付码，前往超过 15,000 个合作网点（如药店、便利店）用现金完成付款。

现金收款API 指 Efecty 提供给第三方商户的技术接口，用于创建支付订单、查询状态、接收支付结果通知，实现自动化对账与订单管理。

商家APP 是 Efecty 面向跨境商户推出的移动端管理工具，支持查看交易记录、下载结算报表、处理异常订单、接收风控提醒等功能。2026年版本新增多店铺切换、实时汇率换算和API调用日志追踪。

关键名词解释

• API接入：应用程序编程接口（Application Programming Interface），允许系统间数据交互。此处指将你的电商系统与 Efecty 支付系统对接。
• 现金收款：消费者不使用银行卡或电子钱包，而通过实体网点以现金完成支付。
• KYC：Know Your Customer，反洗钱合规要求，需提交企业身份、法人信息、经营地址等证明材料。
• 回调通知（Webhook）：支付成功后，Efecty 主动向你服务器发送支付结果，确保订单自动更新状态。
• 商家APP：Efecty 官方推出的移动端管理平台，用于监控交易、管理结算、配置API参数。

它能解决哪些问题

• 痛点：哥伦比亚信用卡渗透率低（不足30%）→ 价值：覆盖更广消费群体，提升转化率。
• 痛点：本地消费者信任海外平台直接扣款→ 价值：先下单后现金支付，降低决策门槛。
• 痛点：PayPal或信用卡拒付率高→ 价值：现金支付不可逆，减少争议与资金风险。
• 痛点：缺乏本地化支付方式影响SEO排名→ 价值：接入本地主流支付可提升Google Shopping和地区电商平台权重。
• 痛点：手动核销订单效率低易出错→ 价值：API自动同步支付状态，减少人工干预。
• 痛点：对账困难，资金到账延迟→ 价值：商家APP提供每日结算清单，支持CSV导出。
• 痛点：风控拦截导致订单失效→ 价值：APP内可查看风控标记原因并申诉。
• 痛点：无法追踪支付网点与时间→ 价值：API返回详细支付地点与时间戳，便于物流调度。

怎么用/怎么开通/怎么选择

一、开通流程（适用于中国跨境卖家）

1. 注册Efecty商户账号：访问 Efecty 商户门户（merchant.efecty.com.co），选择“International Seller Onboarding”通道。
2. 提交KYC材料：包括公司营业执照（中英文公证件）、法人身份证、银行账户证明（SWIFT/BIC）、VAT/TAX ID（如有）、网站或App截图。
3. 签署合作协议：在线签署服务协议与数据共享条款，明确结算周期与手续费承担方。
4. 申请API接入权限：在商家后台提交API使用申请，填写系统用途、预计交易量、回调URL地址。
5. 获取测试凭证：Efecty 提供沙箱环境（Sandbox）的 API Key、Secret 和测试终端号，用于开发联调。
6. 上线前验证：完成接口对接后，运行至少10笔模拟交易，确认支付创建、状态查询、Webhook接收正常。

二、API接入技术步骤

1. 配置开发环境：确保服务器支持 TLS 1.2+，开放出站请求至 Efecty API 域名（api.efecty.com.co）。
2. 调用创建订单接口：POST /payments，传入金额、币种（COP）、订单号、用户手机号、有效期（通常24小时）。
3. 接收支付二维码：API 返回 payment_id 与 barcode/png_url，展示给用户用于打印或扫码。
4. 设置Webhook监听：在后台配置 HTTPS 回调地址，接收 payment.confirmed 或 payment.expired 事件。
5. 主动查询支付状态：若未收到回调，可通过 GET /payments/{payment_id} 每小时轮询一次。
6. 完成订单履约：确认支付后触发发货流程，并通过商家APP标记订单为“已处理”。

三、商家APP应用操作指南（2026版）

• 登录 App 后绑定主商户ID，支持双因素认证（2FA）。
• 首页显示昨日交易总数、待处理异常订单、最近结算批次。
• “API监控”页可查看近7天调用成功率、平均响应时间、错误代码分布。
• “结算管理”支持筛选日期范围，下载包含汇率、手续费明细的对账文件。
• 新功能：“支付地图”可视化展示各城市付款网点活跃度，辅助选品区域策略。

费用/成本通常受哪些因素影响

• 月均交易笔数（阶梯式费率）
• 单笔交易金额区间（小额高频 vs 大额低频）
• 是否使用Efecty推荐的物流合作伙伴
• 结算货币（COP本币结算 or USD跨境结算）
• 退款频率与争议处理复杂度
• API调用量超出免费额度部分
• 是否启用高级风控包（如AI欺诈识别）
• 跨境提现通道（电汇 vs 第三方支付网关）
• KYC审核加急服务（标准7工作日 vs 加急3日）
• 多店铺管理需求（是否需子账户权限分离）

为了拿到准确报价，你通常需要准备以下信息：

• 过去6个月月均订单量与GMV
• 目标市场细分（城市层级：一线/二线/全国）
• 期望结算周期（T+1, T+3, T+7）
• 现有技术栈（PHP/Node.js/Shopify/WooCommerce等）
• 是否已有本地清关代理或合规顾问

常见坑与避坑清单

1. 未配置HTTPS回调地址：Efecty 不接受HTTP回调，否则无法接收支付通知 → 使用Let's Encrypt免费证书部署SSL。
2. 忽略时区差异：Efecty 系统使用 Colombia Time (UTC-5)，订单过期时间需转换一致 → 所有时间戳统一用UTC存储。
3. KYC材料翻译不规范：非公证翻译件可能被拒 → 建议由使馆认证翻译机构出具英文版。
4. 沙箱测试不充分：上线后出现签名算法不匹配 → 在沙箱完成全流程跑通再申请生产密钥。
5. 未监控API限流：默认每分钟100次调用，超限返回429 → 实现退避重试机制。
6. 忽视用户手机号格式：必须为+57开头的10位数字 → 前端输入框强制格式校验。
7. 结算延迟归因错误：Efecty 结算周期为T+3工作日，遇节假日顺延 → 查看APP内“资金流水”而非银行到账时间。
8. 未设置支付超时自动取消：用户未在24小时内付款 → 系统应定时扫描未支付订单并释放库存。
9. 过度依赖APP通知：重要状态变更仍需服务端Webhook兜底 → 不以APP推送作为唯一判断依据。
10. 忽略本地税务要求：超过一定金额需申报DIAN（哥伦比亚税务局）→ 咨询本地合规服务商。

FAQ（常见问题）

1. Efecty现金收款API接入教程商家APP应用2026最新靠谱吗/正规吗/是否合规？
   是的，Efecty 受哥伦比亚金融监管局（Superintendencia Financiera de Colombia）监管，具备支付服务牌照。其API接入流程符合PCI-DSS基础安全要求，数据传输加密。中国卖家需自行确保跨境收单行为符合外汇管理局规定。
2. 适合哪些卖家/平台/地区/类目？
   主要适合：
   - 销售至哥伦比亚的独立站或拉美本地电商平台（如Linio、Mercado Libre CO）；
   - 商品单价在 5万~50万 COP（约13~130美元）之间；
   - 类目如3C配件、家居用品、服饰鞋包、小家电等大众消费品；
   - 已具备基础技术开发能力或使用支持Efecty插件的SaaS建站工具。
3. 怎么开通/注册/接入/购买？需要哪些资料？
   开通路径：
   1) 访问 merchant.efecty.com.co 注册国际商户；
   2) 提交：
   - 公司营业执照（加盖公章）
   - 法人护照或身份证
   - 银行账户证明（含SWIFT）
   - 网站/App截图及隐私政策链接
   - 联系人邮箱与WhatsApp号码
   3) 审核周期通常为5-7个工作日，通过后获得API凭证。
4. 费用怎么计算？影响因素有哪些？
   费用结构由三部分组成：
   - 交易手续费：按比例收取，具体取决于签约等级；
   - 结算费：跨境提现可能产生中间行费用；
   - API调用费：超出免费额度后按次计费。
   影响因素见上文“费用/成本通常受哪些因素影响”列表。
5. 常见失败原因是什么？如何排查？
   常见原因：
   - IP不在白名单（Efecty 生产环境限制访问来源）→ 提前报备服务器IP；
   - 签名算法错误（HMAC-SHA256）→ 核对密钥与拼参顺序；
   - 回调地址无法访问 → 使用curl测试公网可达性；
   - 订单金额超出限额 → 查看商户协议中的单笔上限；
   - KYC审核未通过 → 登录商家APP查看驳回理由并补传材料。
6. 使用/接入后遇到问题第一步做什么？
   第一步：
   1) 登录商家APP查看是否有系统公告或风控警告；
   2) 进入“API监控”页检查最近调用日志与错误码；
   3) 若涉及资金问题，截图交易详情并通过官方工单系统提交；
   4) 技术类问题附上 request_id、timestamp、完整错误响应体。
7. 和替代方案相比优缺点是什么？
   对比 PSE（网银转账）、Nequi（移动钱包）、DaviPlata：
   优势：
   - 覆盖无卡人群最广；
   - 支付不可逆，降低拒付风险；
   - 操作简单，老年人也能使用。
   劣势：
   - 到账延迟（需用户实际付款后1-2小时）；
   - 无法支持即时发货；
   - 不适用于B2B大额交易。
8. 新手最容易忽略的点是什么？
   最容易忽略：
   - 忽视支付有效期（默认24小时），未及时关闭过期订单；
   - 未配置Webhook签名校验，存在伪造支付通知风险；
   - 忘记在商家APP中激活结算账户，导致资金滞留；
   - 缺少西语客服支持，用户在网点付款失败时无法及时协助；
   - 未定期导出对账单进行财务 reconciliation。

相关关键词推荐

• Efecty for international merchants
• Colombia cash payment gateway
• 独立站接入Efecty教程
• 拉美本地支付方式对接
• 跨境API收款集成
• 商家APP Efecty使用手册
• 如何开通Efecty商户账号
• Efecty沙箱测试指南
• 哥伦比亚KYC材料要求
• cash on delivery Colombia alternative
• Efecty支付失败原因
• API回调通知配置
• 跨境结算周期T+3
• 防止Efecty重复扣款
• 多语言支付页面适配
• 拉美市场支付偏好分析
• 独立站支付方式优化
• Shopify接入Efecty插件
• WooCommerce Efecty支付模块
• 跨境电商本地化支付方案