latheesan-k/gist:b3ba0dc0b5de8ccda3f088ed72e395bb

## gistfile1.md

      
    Raw
  

              gistfile1.md
            
          
    这是一份为您专门准备的中文版自动售货机集成指南。您可以直接将这份材料发给中国开发人员，里面详细说明了业务流程、集成步骤以及适用于较旧 Android 系统的代码示例。

DripPay 加密货币支付集成指南 (Android 自动售货机)

您好！本指南旨在帮助您在现有的自动售货机 Android 系统（Java/Kotlin）上，快速无缝地集成 DripPay 加密货币支付功能。
📚 1. 专用 API 官方文档

在开始开发之前，请务必参考我们完整的专用 API 接口文档，里面包含所有字段说明与规范：
👉 https://drippay-dev.com/docs

⚙️ 2. 业务交互流程与应用场景

为了使加密货币支付与您现有的法币支付体系完美结合，自动售货机的交互流程应如下设计：

后台设置 (Settings)：在现有的自动售货机操作系统（UI设置界面）中，添加一个**“启用加密货币支付 (Enable Crypto Payments)”**的开关。开启后，需配置 API 密钥 (API Key) 等必要参数。
用户选品 (Select Product)：顾客在售货机屏幕上选择商品。
选择支付方式 (Select Payment Method)：结算时，在现有的支付方式（微信/支付宝/银行卡）旁，展示已开启的**“加密货币 (Crypto)”**选项。
生成支付订单 (Create Payment Request)：当用户点击“加密货币”时，售货机系统向 DripPay API 发起请求，生成支付订单。
展示二维码 (Show QR Code)：拿到后台返回的支付二维码图片链接后，在屏幕上展示二维码，并启动 60 秒倒计时。
轮询状态 (Polling Status)：售货机开始每隔 3 秒向 DripPay API 轮询一次支付结果。
出货/取消 (Dispense / Cancel)：

成功：如果 DripPay 链上索引确认收到付款，API 返回 paid，售货机立即停止轮询，并执行硬件出货指令（与法币出货逻辑一致）。
超时/手动退出：如果 60 秒内未支付或用户点击取消，系统必须调用 API 取消该订单，并返回首页。


💻 3. 核心 API 集成步骤与示例 (Java)

考虑到售货机可能运行较早版本的 Android，以下示例基于 Android 开发中最通用的网络请求库 OkHttp 以及 JSON 处理方式编写。
步骤一：创建支付请求 (Create Payment Request)

当用户选择加密货币支付时调用。
// POST: /api/v1/invoices
OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json; charset=utf-8");

// 构建请求参数 (传入机器ID, 订单号, 货币, 商品详情)
String jsonBody = "{\n" +
        "  \"machine_id\": \"MACHINE-001\",\n" +
        "  \"trade_no\": \"ORDER-123456\",\n" +
        "  \"currency\": \"USD\",\n" +
        "  \"items\":[\n" +
        "    {\n" +
        "      \"description\": \"Coca Cola\",\n" +
        "      \"amount\": 1.50\n" +
        "    }\n" +
        "  ]\n" +
        "}";

RequestBody body = RequestBody.create(JSON, jsonBody);
Request request = new Request.Builder()
        .url("https://api.drippay-dev.com/api/v1/invoices") // 替换为实际环境的域名
        .addHeader("Authorization", "Bearer 您的API_KEY")
        .post(body)
        .build();

client.newCall(request).enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) throws IOException {
        if (response.isSuccessful()) {
            String res = response.body().string();
            // 解析返回的 JSON，提取 `reference` 和 `qr_code_image_url`
            // 使用 Glide 或 Picasso 将 qr_code_image_url 加载到屏幕 UI 上
            // 记录下 reference 字段，用于后续的轮询
        }
    }
    // ... 省略 onFailure 处理
});
步骤二：轮询支付状态 (Poll Payment Status)

展示二维码后，每隔 3 秒调用一次此接口，持续 60 秒。
// GET: /api/v1/invoices/{reference}/status
String reference = "上一步获取的 reference 字符串";

Request request = new Request.Builder()
        .url("https://api.drippay-dev.com/api/v1/invoices/" + reference + "/status")
        .addHeader("Authorization", "Bearer 您的API_KEY")
        .get()
        .build();

// 建议使用 Android 的 Handler 或 Timer 安排每 3 秒执行一次该请求
client.newCall(request).enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) throws IOException {
        if (response.isSuccessful()) {
            String res = response.body().string();
            // 解析 JSON 中的 "status" 字段
            // 如果 status == "paid" -> 支付成功！停止轮询 -> 调用售货机出货接口
            // 如果 status == "pending" -> 继续等待下一次轮询
        }
    }
});
步骤三：处理超时与取消 (Handle Timeout & Cancellation)

极度重要：如果 60 秒倒计时结束，或者用户在中途点击了“取消/返回”，您必须调用此接口通知 DripPay 取消该订单，以防发生异常支付扣款。
// DELETE: /api/v1/invoices/{reference}
Request request = new Request.Builder()
        .url("https://api.drippay-dev.com/api/v1/invoices/" + reference)
        .addHeader("Authorization", "Bearer 您的API_KEY")
        .delete() // DELETE 请求
        .build();

client.newCall(request).enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) throws IOException {
        // 订单已成功作废，清理 UI，返回主页面
    }
});

⚠️ 4. 集成注意事项 (Important Notes)


控制轮询频率：请严格按照 3 秒一次 的频率查询状态，如果频率过快可能会触发 API 速率限制 (Rate limit)。
60秒支付窗口：加密货币汇率波动快，二维码和订单的有效时间固定为 60 秒。UI 界面上必须给用户明确的倒计时提示。
安全存储：API Key 是鉴权的核心，请将它配置并保存在系统内部设置中，不要在日志中明文打印。
处理网络异常：由于售货机可能处于复杂的网络环境（如 4G 信号不稳定），请务必为网络请求增加重试 (Retry) 逻辑与错误提示。
No results found