Efecty现金收款API接入教程开发者SaaS平台案例
2026-02-24 1
详情
报告
跨境服务
文章
Efecty现金收款API接入教程开发者SaaS平台案例
要点速读（TL;DR）
- Efecty 是哥伦比亚主流的线下现金支付网络，允许消费者在无银行卡情况下通过便利店、超市等网点完成支付。
- 跨境卖家可通过API接入将Efecty整合至电商平台或SaaS系统，支持本地化支付方式，提升拉美市场转化率。
- 主要适用于面向哥伦比亚消费者销售的独立站或区域电商平台卖家。
- 接入需技术开发能力，或借助支持Efecty的第三方SaaS支付网关简化流程。
- 成功支付后有到账延迟（通常24-72小时），需设置订单状态同步机制。
- 合规性要求高，需确保商户具备当地税务登记信息及KYC文件。
Efecty现金收款API接入教程开发者SaaS平台案例 是什么
Efecty 是哥伦比亚领先的非银行现金收单网络，覆盖超过10,000个实体网点（如Droguería Simi、Alkosto、Éxito等），用户可在线下单后生成付款码，前往门店以现金支付。该服务由Grupo Aval旗下运营，受哥伦比亚金融监管机构监督。
现金收款API 指Efecty为商户提供的程序接口，允许电商平台、ERP系统或SaaS平台通过HTTPS请求创建支付订单、查询状态、接收回调通知。
开发者 指具备前后端开发能力的技术人员或团队，负责对接API并实现业务逻辑。
SaaS平台案例 指已集成Efecty的第三方软件服务商（如支付网关、电商中台、ERP系统）所提供的标准化接入方案，降低技术门槛。
它能解决哪些问题
- 痛点：哥伦比亚信用卡渗透率低（不足30%）→ 价值： 提供现金支付选项，触达更广泛消费人群。
- 痛点：国际信用卡拒付率高 → 价值： 本地化支付减少风控拦截，提高支付成功率。
- 痛点：独立站缺乏本地支付信任背书 → 价值： 显示Efecty标识增强消费者信心。
- 痛点：手动核销现金付款效率低 → 价值： API自动回传支付状态，减少人工对账。
- 痛点：多渠道订单分散难管理 → 价值： 与SaaS系统集成后统一处理Efecty订单流。
- 痛点：跨境支付结算周期长 → 价值： 资金先入本地账户，再批量结算至海外主体，优化资金周转。
- 痛点：无法满足B2B小额预付款需求 → 价值： 支持企业客户通过Efecty支付定金或尾款。
- 痛点：平台不支持小语种支付指引 → 价值： SaaS平台提供西语版操作界面和客服支持。
怎么用/怎么开通/怎么选择
一、直接通过Efecty官方申请API接入（适合有技术团队的大型卖家）
- 确认资质： 拥有在哥伦比亚注册的企业实体或与本地公司合作代理收款。
- 提交申请： 访问Efecty for Business官网，填写商户信息表单，上传营业执照、税号（NIT）、法人身份证件、银行账户证明。
- 签署协议： 审核通过后签署服务合同与数据使用条款。
- 获取测试环境密钥： 开发者登录商户后台下载API文档，获取测试环境的Client ID和Secret Key。
- 开发对接： 实现以下核心接口：
– 创建支付单（POST /payments）
– 查询支付状态（GET /payments/{id}）
– 接收Webhook回调（需公网可访问URL） - 上线审核： 提交测试报告，等待Efecty技术团队验收后开通生产环境权限。
二、通过支持Efecty的SaaS支付平台接入（推荐中小卖家）
- 选择支持Efecty的SaaS平台： 如PayU Latam、Mercado Pago、Dlocal、Paddle等，确认其在哥伦比亚支持Efecty作为支付方式。
- 注册商户账号： 在SaaS平台完成KYC认证，提供公司信息、财务资料、网站域名。
- 配置支付方式： 在后台启用Efecty，并设置结算币种（COP）、退款策略、通知邮箱。
- 嵌入支付代码： 复制JS SDK或使用插件（如Shopify App、WooCommerce扩展）添加到结账页面。
- 测试交易： 使用沙箱模式生成测试订单，验证支付跳转、回调通知、订单状态更新是否正常。
- 正式上线： 关闭测试模式，监控首周交易成功率与异常订单。
费用/成本通常受哪些因素影响
- 商户月交易 volume（交易量越大费率可能越低）
- 是否拥有哥伦比亚本地公司主体（本地主体通常费率更低）
- 结算频率（T+1 vs T+7 影响流动性成本）
- 币种转换需求（COP兑USD/EUR的汇率差价）
- 退款率水平（高退款率可能导致附加费）
- API调用频次（高频查询可能产生额外费用）
- 是否使用SaaS平台中间层（增加一层服务费）
- 是否有定制化开发需求（如多仓库分账、发票自动生成）
- 合规审计与反洗钱监测成本（大额商户需定期提交财报）
- 技术支持等级（是否购买SLA保障服务）
为了拿到准确报价/成本，你通常需要准备以下信息：
– 预估月均交易笔数与金额
– 目标市场（仅哥伦比亚 or 多国）
– 商户法律实体所在地
– 是否已有本地银行账户
– 所用电商平台或自研系统类型
– 对账单格式要求（CSV/API）
– 是否需要发票自动化
常见坑与避坑清单
- 未核实商户准入资格： 中国注册公司无法直接对接Efecty，必须通过本地实体或合规代理通道。
- 忽略Webhook安全性： 未校验签名导致伪造支付通知触发虚假发货。
- 回调URL不可达： 服务器防火墙阻止Efecty IP段访问，造成状态不同步。
- 未设置超时规则： 用户未在24小时内完成现金支付，订单仍显示“待支付”。
- 语言本地化不足： 支付说明仍为英文，导致消费者误解操作流程。
- 对账缺失时间戳： 批量导出数据无精确到秒的时间字段，难以匹配订单。
- 忽视税务合规： 未按哥伦比亚DIAN要求开具电子发票，面临罚款风险。
- 依赖单一接入方： 全部流量走一个SaaS平台，一旦宕机影响全站支付。
- 未监控失败原因码： 忽略“INSUFFICIENT_FUNDS”或“EXPIRED”等标准错误码，错过优化时机。
- 测试不充分： 仅测试成功路径，未模拟网络中断、重复回调等异常场景。
FAQ（常见问题）
- Efecty现金收款API接入教程开发者SaaS平台案例靠谱吗/正规吗/是否合规？
是的，Efecty为哥伦比亚持牌支付服务机构，受Superintendencia Financiera de Colombia监管。所有接入需完成KYC与反洗钱审查，合规性强。 - 适合哪些卖家/平台/地区/类目？
主要适用于：
– 面向哥伦比亚消费者的独立站、区域电商平台；
– 类目包括电子产品、时尚服饰、家居用品、数字服务；
– 平台类型：Shopify、Magento、自建站；
– 不适合成人用品、赌博、虚拟货币等受限行业。 - 怎么开通/注册/接入/购买？需要哪些资料？
两种方式：
– 官方直连： 需提供哥伦比亚NIT税号、本地银行账户、公司章程、法人ID。
– 通过SaaS平台： 提供全球公司执照、法人证件、网站URL、预计交易量。具体材料以平台要求为准。 - 费用怎么计算？影响因素有哪些？
无固定费率，通常包含：
– 交易手续费（百分比+固定费）
– 结算费（每笔出金）
– 币种转换费
– 可选技术服务年费
影响因素见上文“费用/成本通常受哪些因素影响”部分。 - 常见失败原因是什么？如何排查？
常见原因：
– 用户未在24小时内完成支付（状态变为EXPIRED）
– API密钥无效或IP白名单未配置
– Webhook未返回HTTP 200响应
– 商户账户余额不足（用于垫资场景）
排查建议：
1. 查看API日志中的error_code
2. 核实回调地址可达性
3. 登录SaaS平台查看交易详情页
4. 联系技术支持提供trace_id - 使用/接入后遇到问题第一步做什么？
第一步应：
– 检查API返回的状态码与message字段
– 确认Webhook是否收到且已正确处理
– 查阅SaaS平台的操作日志或Efecty商户后台的交易记录
– 截图保存错误页面，并准备好request_id、timestamp、user_id等上下文信息再联系客服。 - 和替代方案相比优缺点是什么？
对比PSE（在线银行转账）、Baloto（另一现金支付网络）：
- Efecty优势： 网点更多、支持分期付款、部分支持移动端扫码
- 劣势： 到账慢于PSE（后者实时）、不开具银行回单
- Baloto对比： 覆盖相似，但Efecty在城市便利店密度更高
– Efecty更适合无卡人群，但仅限哥伦比亚境内使用。 - 新手最容易忽略的点是什么？
– 忽视支付有效期：Efecty订单默认24小时过期，需在前端明确提示用户；
– 未建立人工复核机制：自动回调失败时应有人工查单流程；
– 忘记西语用户指引：支付成功页也应提供西班牙语说明；
– 缺少退款流程设计：Efecty原路退款需7-14工作日，需提前告知客户。
相关关键词推荐
关联词条
活动
服务
百科
问答
文章
社群
跨境企业