Efecty现金充值API接入教程开发者独立站全面指南
2026-02-24 1
详情
报告
跨境服务
文章
Efecty现金充值API接入教程开发者独立站全面指南
要点速读（TL;DR）
- Efecty 是哥伦比亚主流的现金支付网络，支持消费者在便利店、超市等线下网点以现金完成线上订单支付。
- 通过 Efecty 现金充值 API，独立站开发者可将该支付方式集成至结账流程，提升本地转化率。
- 主要适用于面向哥伦比亚消费者的跨境独立站或本地化电商项目。
- 接入需完成商户注册、KYC认证、技术对接（API）、测试与上线四阶段。
- 关键注意事项：确保订单状态同步机制健全、退款流程合规、交易信息准确传递。
- 常见失败原因包括：回调地址不可达、签名验证错误、订单金额超限、用户未及时付款。
Efecty现金充值API接入教程开发者独立站全面指南 是什么
Efecty 现金充值API 是 Efecty 提供给企业用户的程序接口，允许电商平台或独立站在用户下单后生成带有唯一代码的现金支付凭证，用户凭此码在 Efecty 合作网点以现金完成支付，平台随后收到支付确认通知。
关键词解释
- Efecty：哥伦比亚领先的非银行支付网络，覆盖超 2 万家线下支付点，广泛用于水电费、话费、电商等场景。
- 现金充值：指消费者不使用银行卡或电子钱包，而是在线生成支付单据后，前往实体网点用现金完成付款。
- API 接入：应用程序编程接口（Application Programming Interface），开发者通过调用 API 实现系统间数据交互，如创建支付单、查询状态、接收回调。
- 独立站：指卖家自主搭建并运营的电商网站（如基于 Shopify、WooCommerce 或自研系统），区别于第三方平台（如亚马逊、Mercado Libre）。
它能解决哪些问题
- 痛点：哥伦比亚信用卡渗透率低 → 价值：支持现金支付，触达无卡人群，扩大客群基础。
- 痛点：本地消费者对国际支付方式信任度低 → 价值：使用本土熟悉渠道，增强购买信心。
- 痛点：PayPal 或信用卡拒付率高 → 价值：现金支付不可逆，降低欺诈与争议风险。
- 痛点：独立站支付方式单一 → 价值：丰富本地化支付选项，提升结算页转化率。
- 痛点：订单支付后无法自动确认 → 价值：API 支持异步回调，实现订单状态自动化更新。
- 痛点：人工核销效率低易出错 → 价值：系统自动匹配付款记录，减少客服介入。
- 痛点：资金到账周期长 → 价值：Efecty 完成清算后，资金可快速结算至商户账户（具体时效依合作模式而定）。
怎么用/怎么开通/怎么选择
一、开通流程（常见做法）
- 确认业务适配性：评估目标市场是否为哥伦比亚，销售类目是否符合 Efecty 商户准入要求（如禁止赌博、成人内容等）。
- 注册企业账户：访问 Efecty 官方商户门户（或通过支付网关合作伙伴），提交公司注册信息、法人身份、税务编号（NIT）、营业执照等文件。
- 完成 KYC 审核：提供银行账户信息、经营地址证明、网站链接、预计交易量级等资料，等待风控审核（通常需数个工作日）。
- 获取 API 凭据：审核通过后，Efecty 或其技术合作伙伴提供 API Key、Secret Key、测试环境 Endpoint 等接入参数。
- 技术对接开发：
- 在独立站支付环节增加 Efecty 选项；
- 调用
/createPayment接口生成支付单，返回参考号（reference）和条码（barcode）； - 前端展示支付指引页面，含金额、截止时间、二维码；
- 配置 Webhook 回调地址，接收支付成功/失败通知。
- 沙箱测试与上线：使用测试账号模拟全流程，验证订单创建、状态同步、回调处理逻辑无误后，切换至生产环境。
二、开发者技术对接要点
- 使用 HTTPS 协议进行所有 API 调用。
- 请求头需包含授权令牌（Authorization: Bearer {api_key}）。
- 请求体常用 JSON 格式，必填字段包括：商户订单号、金额、币种（COP）、客户邮箱/手机号、过期时间。
- 服务器需正确响应回调（Webhook），返回 HTTP 200 状态码，避免重复通知。
- 建议实现定时轮询机制，作为回调失败的补充方案。
费用/成本通常受哪些因素影响
- 商户所属行业类目（高风险类目费率可能更高）
- 月均交易笔数与总交易额（volume-based pricing）
- 是否通过第三方支付网关接入（如 PayU、Redsys、Cybersource）
- 结算周期（T+1、T+3 或周结）
- 是否有定制化开发需求（如专属支付页面）
- 是否包含反欺诈服务或对账工具
- 汇率转换成本（若结算为美元）
- 退款处理费用（如有）
为了拿到准确报价/成本，你通常需要准备以下信息：
常见坑与避坑清单
- 未设置合理订单有效期：建议设置 24-72 小时内完成支付，避免长期占用未付款订单库存。
- 忽略回调验证机制：必须校验签名（signature）防止伪造通知，推荐使用 HMAC-SHA256 验证。
- 未处理异步延迟：Efecty 系统可能存在几分钟到几小时的状态同步延迟，避免立即判定为“未支付”。
- 用户信息填写错误：确保传递正确的邮箱或手机号，便于 Efecty 发送支付提醒。
- 缺乏支付失败引导：用户超时未付后应提供重新发起选项，而非直接取消订单。
- 未监控 API 调用成功率：定期检查接口响应码（如 401 权限错误、500 服务异常），及时发现集成问题。
- 忽视本地合规要求：哥伦比亚要求电子发票包含特定字段，确保订单数据满足税务规范。
- 跳过沙箱测试：直接在生产环境调试可能导致无效订单产生或客户投诉。
FAQ（常见问题）
- Efecty现金充值API靠谱吗/正规吗/是否合规？
是的，Efecty 是哥伦比亚受 Superintendencia Financiera de Colombia 监管的合法支付机构，其 API 接入属于正规商业合作，符合当地金融法规。 - Efecty现金充值API适合哪些卖家/平台/地区/类目？
主要适合：
- 面向哥伦比亚消费者的跨境独立站
- 销售中低价商品（通常 COP 50,000 - 2,000,000）
- 类目如电子产品配件、时尚服饰、家居用品等普通消费品
- 不适用于虚拟币、博彩、药品等受限类目 - Efecty现金充值API怎么开通/注册/接入/购买？需要哪些资料？
需通过 Efecty 官方或其授权支付网关申请，常见所需资料：
- 公司营业执照（英文或西班牙语翻译件）
- 法人身份证或护照
- 公司银行账户证明（对账单）
- 网站 URL 及隐私政策、退货政策页面
- NIT（Número de Identificación Tributaria）
- 预计月交易量 - Efecty现金充值API费用怎么计算？影响因素有哪些？
费用结构通常为“交易手续费 + 结算费”，按笔或按比例收取。影响因素包括交易量、类目、结算周期、是否通过中间商接入等。具体费率需与 Efecty 或其合作伙伴签署协议后确定。 - Efecty现金充值API常见失败原因是什么？如何排查？
常见原因：
- 回调地址无法访问（检查防火墙、SSL 证书）
- 签名验证失败（核对 secret key 和算法）
- 订单金额超出限制（确认单笔上限）
- 用户未在有效期内支付（优化提醒机制）
- API 密钥无效或过期（重新获取凭证）
排查建议：查看日志中的 HTTP 状态码与错误描述，使用 Postman 测试接口连通性。 - 使用/接入后遇到问题第一步做什么？
首先检查 API 文档中的错误码说明，确认请求格式与认证方式正确；其次查看服务器是否正常接收并响应 Webhook；最后联系 Efecty 技术支持或你的支付服务商，提供时间戳、订单号、请求ID等信息协助排查。 - Efecty现金充值API和替代方案相比优缺点是什么？
对比 PSE（在线银行转账）：Efecty 更适合无网银用户，但需线下操作；PSE 实时到账但依赖银行账户。
对比 Baloto（另一现金支付网络）：两者覆盖率相似，Efecty 在城市便利店更密集，Baloto 在加油站网点更多。建议同时接入以最大化覆盖。
对比信用卡：Efecty 拒付风险低，但资金到账慢（通常 T+1 起）。 - 新手最容易忽略的点是什么？
忽略三点：
一是未配置自动对账机制，导致人工核销压力大；
二是未在用户支付后发送明确指引（如打印条码）；
三是未设置订单过期自动关闭策略，影响库存管理。
相关关键词推荐
关联词条
活动
服务
百科
问答
文章
社群
跨境企业