Efecty现金收款API接入教程开发者连锁门店全面指南

Efecty现金收款API接入教程开发者连锁门店全面指南

要点速读（TL;DR）

• Efecty 是哥伦比亚主流的现金支付网络，允许消费者在实体连锁门店用现金完成线上订单支付。
• 跨境卖家可通过接入 Efecty 收款 API 实现与本地支付系统的对接，提升拉美市场转化率。
• 主要适用于面向 哥伦比亚消费者 的电商平台或独立站，尤其适合高客单价、货到付款替代场景。
• 接入需技术开发支持，涉及 API 调用、支付状态回调处理、订单映射等环节。
• 必须通过具备 本地收单资质 的支付网关或 PSP（支付服务提供商）间接集成，不支持卖家直接注册。
• 常见坑：未正确配置异步通知、超时未支付订单未自动取消、用户信息验证不严导致欺诈。

Efecty现金收款API接入教程开发者连锁门店全面指南 是什么

Efecty 是哥伦比亚广泛使用的非银行现金支付网络，覆盖超过 14,000 家便利店、超市和药店（如 Alkosto、Exito、D1）。消费者在线下单后生成 Efecty 支付单，凭编号前往任意合作门店以现金付款。

现金收款API 指由支付服务商提供的程序接口，允许电商平台系统与 Efecty 网络进行数据交互，实现支付单创建、状态查询、回调通知等功能。

开发者 指负责技术对接的技术人员或团队；连锁门店 指 Efecty 合作的线下零售网点，是最终完成现金收取的终端节点。

它能解决哪些问题

• 痛点：拉美消费者信用卡渗透率低 → 价值： 提供现金支付选项，扩大可触达客群。
• 痛点：货到付款（COD）物流成本高且拒收率高 → 价值： 前置现金收款，降低尾程风险与运营成本。
• 痛点：本地电子钱包账户开通难 → 价值： 无需银行账户即可完成支付，提升转化。
• 痛点：国际信用卡拒付率高 → 价值： 使用本地化支付方式，减少支付失败。
• 痛点：缺乏信任感导致弃单 → 价值： 在知名连锁店付款增强用户安全感。
• 痛点：资金结算周期长 → 价值： 支付成功后较快确认，加速订单履约。
• 痛点：无法覆盖无网银人群 → 价值： 触达低收入、偏远地区消费群体。
• 痛点：平台需本地收单牌照 → 价值： 通过第三方 PSP 合规接入，规避资质门槛。

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

一、确认是否适用你的业务

• 目标市场为哥伦比亚；
• 销售商品为实物类目（禁售虚拟、金融产品）；
• 具备基本技术开发能力或有合作开发团队；
• 已接入支持 Efecty 的支付服务提供商（PSP）。

二、选择支持 Efecty 的支付服务商（PSP）

目前 Efecty 不向跨境卖家直接开放 API 接入。必须通过以下类型机构：

• 本地持牌收单行（如 Bancolombia 商户服务）；
• 国际支付网关（如 PagueloFacil、Dlocal、PayU Latam、Checkout.com 拉美方案）；
• 专注拉美的跨境支付平台（如 Asiabill、Cashfree 国际版）。

建议：优先选择已在 Colombia 有商户主体备案的服务商，避免审核延误。

三、注册并申请开通 Efecty 收款权限

1. 联系选定 PSP 客服或商务代表，说明需要“Colombia - Efecty”支付方式；
2. 提交企业资料：营业执照、法人身份证、网站/APP 信息、SKU 示例、预计月交易额；
3. 签署商户协议（可能含本地代理条款）；
4. 等待风控审核（通常 3–7 个工作日）；
5. 获得商户 ID（Merchant ID）、密钥（API Key / Secret）及测试环境接入文档。

四、技术接入 Efecty API（开发者流程）

1. 获取 API 文档：从 PSP 下载完整接口说明，重点关注“Cash Payment”或“Offline Payment”模块。
2. 配置测试环境：使用沙箱账号创建模拟 Efecty 订单，验证流程。
3. 发起支付请求：调用 /create-payment 接口，传入金额、货币（COP）、订单号、用户手机号、有效期（通常 24–72 小时）。
4. 接收支付单信息：成功响应包含 Efecty 参考码（reference code）、付款链接、二维码、合作门店列表。
5. 展示支付凭证：将参考码和付款指引页面返回给用户，支持下载 PDF 或短信发送。
6. 监听异步通知：配置 Webhook URL 接收支付成功/失败/过期状态推送（注意签名验证）。
7. 更新订单状态：根据回调结果标记订单为“已付款”或“关闭”。
8. 对账与结算：每日下载 PSP 提供的结算文件，核对 Efecty 交易明细。

五、上线前必做事项

• 完成至少 10 笔沙盒测试订单全流程；
• 确保 Webhook 地址公网可访问且 HTTPS 加密；
• 设置订单超时自动取消机制（建议 ≤72 小时）；
• 编写用户引导文案（如何在 Alkosto/D1 门店付款）；
• 准备客服 SOP：处理“已付未到账”、“参考码无效”等问题。

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

• 支付服务商（PSP）的定价策略
• 月交易 volume（量级越高费率越低）
• 是否使用本地收单通道（本地收单通常费率更低）
• 结算币种（COP 本币结算 vs USD 结算）
• 提现频率与方式（电汇、本地转账）
• 是否存在额外服务费（如 API 技术支持、定制开发）
• 拒付或争议处理费用
• 汇率转换差价（若最终结算为非 COP）
• 是否包含反欺诈系统使用费
• 合同中是否有最低交易额承诺

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

• 公司注册国家与主体名称
• 电商平台类型（独立站/Magento/Shopee 等）
• 目标市场（仅 Colombia 还是多国）
• 预计首月交易笔数与总金额
• 主要销售类目（避免敏感品类影响审批）
• 是否已有支付服务商合作
• 技术对接方式（API / 插件 / Hosted Page）

常见坑与避坑清单

1. 误以为可直接注册 Efecty 账户 → 实际必须通过 PSP 间接接入，提前锁定合作方。
2. 忽略 Webhook 签名验证 → 可能被伪造支付通知，造成虚假发货。
3. 未设置订单有效期 → 用户无限期持有参考码，库存被长期占用。
4. 用户手机号格式错误 → 影响 Efecty 系统通知推送，建议前端校验 + 国际区号默认+57。
5. 未提供清晰付款指引 → 用户找不到门店或输错参考码，增加客服压力。
6. 回调地址未备案或屏蔽 → PSP 无法推送状态，订单卡在“待支付”。
7. 未监控对账差异 → 长期漏单导致资金损失，建议自动化比对。
8. 忽视本地合规要求 → 如未在当地申报税务或未满足数据存储规定。
9. 技术文档依赖英文翻译 → 关键字段含义误解，建议索取西班牙语原文对照。
10. 测试环境未覆盖异常场景 → 如超时支付、部分付款、重复通知等。

FAQ（常见问题）

1. Efecty现金收款API接入靠谱吗/正规吗/是否合规？
   是正规支付方式，Efecty 为哥伦比亚合法运营的支付网络，但跨境卖家需通过持牌 PSP 接入以符合当地金融监管要求，确保资金流合规。
2. Efecty现金收款API接入适合哪些卖家/平台/地区/类目？
   适合面向哥伦比亚消费者的独立站、B2C 电商、高单价电子产品或家具类卖家；不适用于虚拟商品、金融服务、成人用品等受限类目。
3. Efecty现金收款API接入怎么开通/注册/接入/购买？需要哪些资料？
   需通过支持 Efecty 的 PSP 开通，提供企业营业执照、法人身份证明、网站信息、SKU 清单、预计交易量等资料，具体以 PSP 要求为准。
4. Efecty现金收款API接入费用怎么计算？影响因素有哪些？
   费用由 PSP 设定，通常包含交易手续费、结算费、月费等，影响因素包括交易量、收单模式、结算币种、合同条款等，需与服务商协商获取报价单。
5. Efecty现金收款API接入常见失败原因是什么？如何排查？
   常见原因：API 密钥错误、参数格式不符（如金额单位应为分）、Webhook 无法访问、用户未在有效期内付款、手机号无效。排查建议：查看 PSP 日志、测试沙箱环境、检查服务器防火墙设置。
6. 使用/接入后遇到问题第一步做什么？
   首先确认问题类型：支付创建失败 → 检查 API 请求日志；支付成功未通知 → 查看 Webhook 是否收到并正确响应；用户投诉 → 核对 Efecty 参考码与 PSP 对账单。然后联系 PSP 技术支持提供 trace ID 或 transaction ID。
7. Efecty现金收款API接入和替代方案相比优缺点是什么？
   对比 PSE（网银转账）：Efecty 无需网银，但需线下操作；对比 Baloto：两者均为现金支付，Efecty 门店更密集；对比 PayPal：Efecty 更本地化，但无买家保护机制。建议组合使用多种本地支付方式。
8. 新手最容易忽略的点是什么？
   最易忽略：① Webhook 安全校验；② 订单超时自动关闭逻辑；③ 用户付款后的状态同步延迟；④ 未准备西班牙语客服话术；⑤ 忽视 PSP 的结算周期与提现限制。

相关关键词推荐

• Efecty 支付
• 哥伦比亚现金支付
• 拉美本地支付接入
• PayU Latam API
• Dlocal 现金支付
• PagueloFacil 接入
• 独立站 拉美支付
• 海外现金收款方案
• Latam 支付方式
• 跨境支付 PSP
• Shopify Colombia 支付
• cash payment API
• offline payment integration
• Colombia e-commerce payment
• Alkosto 付款
• D1 store payment
• Baloto vs Efecty
• 本地收单 vs 跨境收单
• Webhook 支付回调
• 防欺诈 现金支付