Efecty现金取现API接入教程开发者SaaS平台怎么开通
2026-02-24 3
详情
报告
跨境服务
文章
Efecty现金取现API接入教程开发者SaaS平台怎么开通
要点速读（TL;DR）
- Efecty 是哥伦比亚主流的线下现金支付网络，支持消费者通过便利店、ATM等渠道用现金付款，常用于跨境电商本地化支付。
- 其 现金取现API 允许卖家或SaaS平台生成带付款码的账单，买家凭码在网点现金支付。
- 接入需通过官方或授权聚合支付网关（如Paddle、Dlocal、Checkout.com等），个人卖家通常无法直接对接。
- 开发者需具备基础API调用能力，熟悉RESTful接口、JSON数据格式与Webhook回调处理。
- 开通流程包括：注册商户账户、申请API权限、技术对接、沙箱测试、上线审批。
- 合规要求高，需提供公司主体、经营范围、交易品类说明等材料，建议由本地实体或合作机构代为申请。
Efecty现金取现API接入教程开发者SaaS平台怎么开通 是什么
Efecty现金取现API 是Efecty为其合作商户提供的程序化接口，允许电商平台、ERP系统或SaaS服务商自动生成可在线分发、线下现金支付的账单凭证。用户下单后获取唯一付款码，在Colpatria、Éxito、Correos de Colombia等合作网点以现金完成支付，资金经清算后结算至商户指定账户。
关键词解释
- Efecty：哥伦比亚领先的非银行支付网络，覆盖超3万家线下支付点，主要服务无银行卡人群。
- 现金取现API：指通过API创建“待支付账单”并返回条形码/二维码的能力，非字面意义的“提现”功能。
- 开发者SaaS平台：指为跨境卖家提供集成支付、订单管理等功能的技术服务平台，如独立站建站工具、跨境ERP、收单中间件等。
- API接入：通过编程方式调用第三方服务接口，实现系统间数据自动交互，无需人工操作。
它能解决哪些问题
- 痛点：拉美消费者信用卡渗透率低 → 价值： 支持现金支付，提升转化率，尤其适合中低价商品。
- 痛点：国际卡拒付率高 → 价值： 本地化支付方式降低风控拦截概率。
- 痛点：支付确认延迟 → 价值： API实时返回支付状态，加快订单履约速度。
- 痛点：多平台手动开单效率低 → 价值： 自动化生成Efecty账单，减少人工错误。
- 痛点：缺乏支付追踪能力 → 价值： 通过Webhook接收支付成功通知，触发库存扣减和物流打单。
- 痛点：本地清关需要付款证明 → 价值： 可下载官方支付凭证用于报关材料。
- 痛点：资金回款周期长 → 价值： Efecty结算周期相对稳定（通常T+1至T+3工作日）。
- 痛点：小卖家难独立签约本地支付 → 价值： 通过SaaS平台批量接入，降低准入门槛。
怎么用/怎么开通/怎么选择
一、确认适用对象与接入路径
- 判断是否具备哥伦比亚本地公司或合作代理——无本地实体者建议通过已接入Efecty的支付网关或SaaS平台间接使用。
- 选择接入方式：
- 直接接入：适用于有本地注册公司的大型卖家或技术服务商。
- 间接接入：通过Dlocal、Pagar.me、Mercado Pago、Checkout.com等聚合支付平台调用Efecty作为下游通道。
二、注册商户账户（以直接接入为例）
- 访问Efecty商业合作官网（comercios.efecty.com.co），点击“Quiero ser Aliado”申请成为合作伙伴。
- 提交企业资料：营业执照（或RUT）、法人身份证、银行账户信息、业务描述、预计月交易量。
- 签署合作协议，等待审核（通常5-10个工作日）。
- 获得商户ID（Código de Comercio）与终端号（Terminal ID）。
三、申请API权限
- 联系Efecty技术支持或客户经理，申请开通Web Services API访问权限。
- 获取测试环境（sandbox）URL、生产环境地址、认证方式（通常为用户名+密码+商户ID组合）。
- 下载API文档（PDF或Swagger格式），确认支持的方法：
- CrearRecibo（创建收款单）
- ConsultarRecibo（查询状态）
- AnularRecibo（作废账单）
- Webhook配置（接收支付通知）
四、技术对接步骤
- 在开发环境中配置沙箱参数，使用测试账号发起请求。
- 调用
CrearRecibo接口，传入订单号、金额、到期时间、客户手机号等字段，接收返回的BarCode 和ReferenceNumber。 - 将条码展示给买家，或发送短信/邮件指引其前往任意Efecty网点支付。
- 设置公网可访问的Webhook URL，用于接收支付成功回调（HTTP POST JSON格式）。
- 在生产环境切换前完成至少10笔模拟交易验证全流程。
- 提交上线申请，由Efecty团队进行最终验收。
五、SaaS平台用户特别说明
- 若使用Shopify、WooCommerce插件或某ERP系统，查看其支付模块是否已集成Efecty。
- 在后台启用Efecty支付选项，填写由SaaS平台分配的集成密钥（Integration Key）。
- 无需自行编码，但需确保订单同步逻辑正确，避免重复生成账单。
费用/成本通常受哪些因素影响
- 商户所属行业类目（高风险类目费率更高）
- 月均交易笔数与总额（量大可协商折扣）
- 是否拥有哥伦比亚本地公司主体
- 结算币种（COP vs USD）及汇率转换方式
- 是否使用第三方支付网关（会叠加通道费）
- 退款处理机制与频率
- API调用频次限制（超出可能收费）
- 技术对接支持服务需求（是否需要定制开发）
- 合同签订语言版本（西语为主，翻译成本另计）
- 是否有反欺诈监控附加服务
为了拿到准确报价/成本，你通常需要准备以下信息：
公司名称、RUT税号、主营业务、目标市场、预估月交易量、平均订单金额、网站/App流量截图、历史支付方式分布。
常见坑与避坑清单
- 未验证Webhook签名校验：忽略签名验证可能导致伪造支付通知，造成虚假发货。建议实现HMAC-SHA256校验逻辑。
- 条码过期未刷新：Efecty账单通常72小时内有效，超时需重新生成，应在前端提示倒计时。
- 未处理异步结算延迟：即使收到支付通知，资金到账仍有1-3天延迟，不要立即释放高价值商品。
- 忽略西语客服支持：出现问题时Efecty客服仅提供西班牙语沟通，建议配备双语对接人。
- 测试环境参数混淆：沙箱与生产环境证书不可混用，部署前务必检查API域名与密钥。
- 批量创建订单冲突：同一订单号重复提交会失败，建议增加唯一性校验与重试机制。
- 缺少支付凭证归档：未保存条码图像和支付回执，后续争议无法举证。
- 忽视合规申报义务：在哥伦比亚销售需遵守DIAN税务规定，Efecty不承担代扣责任。
- 过度依赖单一通道：应同时接入PSE、Baloto等其他本地支付方式，提高覆盖率。
- 未监控API调用成功率：定期检查HTTP响应码，及时发现网络中断或认证失效问题。
FAQ（常见问题）
- Efecty现金取现API靠谱吗/正规吗/是否合规？
是的，Efecty受哥伦比亚金融监管局（Superintendencia Financiera de Colombia）监督，为合法支付服务机构，API接入符合当地电子交易法规。 - Efecty现金取现API适合哪些卖家/平台/地区/类目？
主要适用于面向哥伦比亚消费者的电商卖家；平台包括独立站、App、B2C商城；不适合成人用品、虚拟货币、高仿类等受限类目。 - Efecty现金取现API怎么开通/注册/接入/购买？需要哪些资料？
需通过Efecty官网或授权网关申请，提供公司营业执照（或RUT）、法人证件、银行账户、业务说明、联系方式。个人卖家可通过SaaS平台间接接入。 - Efecty现金取现API费用怎么计算？影响因素有哪些？
费用结构由商户协议约定，通常包含每笔手续费+月固定费，具体取决于交易量、行业、结算方式等因素，需单独谈判确定。 - Efecty现金取现API常见失败原因是什么？如何排查？
常见原因：API认证失败、订单号重复、金额超限、网络超时、Webhook地址不可达。排查方法：检查日志中的错误代码（如401、409、500）、确认请求头格式、测试端点连通性。 - 使用/接入后遇到问题第一步做什么？
首先查看API返回的错误码与消息，其次确认是否处于沙箱环境，然后检查时间戳与时区设置是否一致，最后联系Efecty技术支持或你的支付网关客服。 - Efecty现金取现API和替代方案相比优缺点是什么？
对比Baloto：两者均为现金支付，但Efecty网点更多；对比PSE：PSE为网银转账，转化更快但需银行卡；对比Mercado Pago：后者整合度更高但抽成也高。建议组合使用。 - 新手最容易忽略的点是什么？
一是忘记配置Webhook安全验证，二是未设置账单有效期提醒，三是误以为“支付成功”等于“资金到账”，四是未保留完整的交易日志用于对账。
相关关键词推荐
关联词条
活动
服务
百科
问答
文章
社群
跨境企业