Efecty现金取现API接入教程开发者APP应用2026最新

Efecty现金取现API接入教程开发者APP应用2026最新

要点速读（TL;DR）

• Efecty 是拉美地区主流的现金支付方式，支持消费者在线下单后线下网点付款或取现。
• 其 现金取现API 允许跨境电商平台/ERP/支付网关接入，实现订单生成、状态同步与资金结算自动化。
• 主要覆盖市场为哥伦比亚，适合面向当地无银行卡用户的B2C卖家。
• 接入需通过官方开发者门户注册应用，获取密钥并完成沙箱测试。
• 2026年预计升级点包括：更强的风控规则、更细粒度的回调通知、移动端SDK优化。
• 常见失败原因：商户资质不全、IP未白名单、签名算法错误、超时未支付。

Efecty现金取现API接入教程开发者APP应用2026最新 是什么

Efecty 是哥伦比亚领先的非银行支付网络，提供现金支付、账单缴纳和汇款服务。用户可在便利店、药店、邮局等超过15,000个网点完成现金交易。

现金取现API 指 Efecty 向商户开放的技术接口，允许第三方系统（如电商平台、ERP、支付中台）创建取现订单、查询状态、接收支付结果回调。

开发者APP应用 指在 Efecty 开发者平台注册的应用实体，用于管理API凭证（Client ID / Secret）、配置回调地址、查看调用日志。

关键名词解释

• API：应用程序编程接口，用于系统间数据交互，如创建订单、查询状态。
• 回调（Webhook）：Efecty 在用户完成支付后主动通知商户系统的URL接口。
• 商户ID（Merchant ID）：Efecty分配给合作商户的唯一标识。
• 签名机制：请求参数需按指定算法（如HMAC-SHA256）加密，确保数据安全。
• 沙箱环境：测试环境，用于模拟全流程而不产生真实交易。

它能解决哪些问题

• 痛点：拉美消费者信用卡渗透率低 → 价值：支持现金支付提升转化率
• 痛点：本地支付方式缺失 → 价值：接入Efecty增强本地化体验
• 痛点：人工对账效率低 → 价值：API自动同步支付状态减少漏单
• 痛点：订单状态延迟更新 → 价值：实时Webhook通知触发发货流程
• 痛点：跨境收款链路长 → 价值：本地清分缩短回款周期
• 痛点：技术对接门槛高 → 价值：标准化API文档降低开发成本
• 痛点：拒付争议难处理 → 价值：提供支付凭证（voucher code）作为证据

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

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

1. 确认业务合规性：确保公司主体可开展跨境电商业务，具备进出口权及外汇账户。
2. 联系Efecty或其授权支付服务商：直接申请或通过PayU、Dlocal、Paddle等聚合支付平台间接接入。
3. 提交商户资料：通常包括营业执照、法人身份证、网站/App信息、预计交易量、KYC问卷。
4. 签署合作协议：明确费率结构、结算周期、责任划分（以合同为准）。
5. 注册开发者APP：登录 Efecty Developer Portal，创建应用，获取 Client ID 和 Secret Key。
6. 接入API并测试：
   • 配置沙箱环境域名与IP白名单
   • 调用 /payments/cash 接口生成取现订单
   • 实现 Webhook 回调接口接收 PAID 状态
   • 使用测试凭证完成全流程验证
7. 上线审批：提交生产环境切换申请，等待Efecty技术审核。

二、典型API调用流程

1. 用户在商城选择 Efecty 现金支付
2. 后端构造请求体（含金额、货币COP、订单号、过期时间）
3. 使用 HMAC-SHA256 对参数签名
4. POST 请求至 https://api.efecty.com/v1/payments/cash（生产环境）
5. 接收响应中的 voucher_code 和 payment_link
6. 展示给用户用于打印或前往网点支付
7. 监听 Webhook 回调（URL需公网可访问）
8. 收到 status: "PAID" 后触发订单履约

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

• 商户所属行业类目（高风险类目费率更高）
• 月均交易笔数与总额（量大可能议价）
• 是否通过聚合支付平台接入（中间商会加价）
• 结算币种与频率（USD/COP，T+1/T+7）
• 退款率与争议率（过高可能触发风控审查）
• 技术支持等级（是否需要专属客户经理）
• 是否使用增值服务（如反欺诈引擎、报表定制）
• 汇率转换成本（若以COP结算需换汇）

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

• 公司注册地与运营国家
• 目标市场（如仅哥伦比亚）
• 预计月交易额与订单量
• 销售类目（如电子产品、时尚服饰）
• 现有技术架构（自建站/Magento/Shopee等）
• 是否已有本地收单通道

常见坑与避坑清单

1. 未提前备案IP白名单 → 提前向Efecty提交服务器出口IP，否则API调用被拒。
2. 忽略时区问题 → 所有时间戳使用UTC，避免因时差导致订单失效。
3. 回调地址不可达 → Webhook URL必须公网可访问且返回HTTP 200。
4. 签名算法实现错误 → 严格对照官方文档校验参数排序与编码格式。
5. 未设置订单有效期 → 建议设定24-72小时过期，防止长期占单。
6. 缺乏异常监控 → 记录所有API响应码（如401/422），设置告警机制。
7. 跳过沙箱测试 → 必须完整走通测试流程再上线。
8. 忽视用户指引 → 提供清晰的 voucher 使用说明与网点查询链接。
9. 未保留支付凭证 → 长期存储 voucher_code 与支付截图用于争议处理。
10. 依赖单一支付方式 → 建议同时接入 PSE、Baloto 等哥伦比亚主流方式。

FAQ（常见问题）

1. Efecty现金取现API接入教程开发者APP应用2026最新靠谱吗/正规吗/是否合规？
   是正规支付渠道，受哥伦比亚金融监管局（Superintendencia Financiera de Colombia）监督。建议核查合作协议中的法律适用条款与争议解决机制。
2. 适合哪些卖家/平台/地区/类目？
   适合面向哥伦比亚消费者的中国跨境卖家，尤其适用于电子、家居、服装配饰等B2C类目。不适用于虚拟商品、博彩、成人用品等受限类目。
3. 怎么开通/注册/接入/购买？需要哪些资料？
   需通过Efecty官网或其合作支付网关提交：
   • 企业营业执照
   • 法人身份证明
   • 网站/App截图
   • KYC调查表
   • 银行账户信息（用于结算）
   具体材料以官方要求为准。
4. 费用怎么计算？影响因素有哪些？
   费用由交易手续费构成，具体费率取决于行业、交易量、结算方式等因素。通常不收取接入费或年费。详细计价模型需与Efecty或其代理协商确定。
5. 常见失败原因是什么？如何排查？
   常见原因：
   • API签名错误 → 核对密钥与加密逻辑
   • IP不在白名单 → 联系技术支持添加
   • 参数缺失或格式错误 → 查阅最新API文档
   • 订单超时未支付 → 检查有效期设置
   • 回调未成功接收 → 日志检查HTTP状态码
   建议启用调试日志并与Efecty技术支持共享request_id。
6. 使用/接入后遇到问题第一步做什么？
   首先检查API响应码与错误信息，确认是否为客户端错误（4xx）或服务端问题（5xx）。保存完整请求/响应记录，联系Efecty技术支持并提供 request_id 和时间戳。
7. 和替代方案相比优缺点是什么？
   对比 Baloto：两者覆盖相似，但Efecty网点略多；
   对比 PSE：PSE为网银转账，Efecty为现金支付，受众不同；
   对比信用卡：Efecty触达无卡人群，但支付确认延迟较长（最长48小时）。
8. 新手最容易忽略的点是什么？
   忽略支付成功后的状态同步延迟——Efecty可能在用户付款后数小时才发送Webhook，需设置异步轮询机制作为补充；另外常忘记在用户界面展示清晰的支付指引。

相关关键词推荐

• Efecty API文档
• 哥伦比亚现金支付接入
• Latam本地支付方式
• Dlocal Efecty集成
• 跨境支付API对接
• 拉美电商支付解决方案
• cash payment gateway Latin America
• PayU Colombia
• 商户KYC审核材料
• Webhook回调配置
• API签名生成工具
• 沙箱测试环境地址
• 支付凭证voucher code
• 订单状态同步机制
• 跨境收款结算周期
• 拉美市场准入指南
• 非持卡用户支付方案
• 本地化支付用户体验
• 高拒付率类目风控
• 多支付方式聚合策略