tags: GLO JP

JP_GLO商户对接文档(1.02)

change log

接入流程

• 获取商户ID(mch_id)、密钥、API域名(API_HOST & CASHIER_HOST)
• 提供贵司下单IP，以开通IP白名单，并提供订单回调地址的
• 依照此文档进行api接口对接

API说明

• 接口采用HTTP请求的形式
• 签名采用MD5杂凑运算
• 所有的金额单位为「分」
• 请求成功时，返回参数中的status固定为0且msg为OK，其他情况请参考请求错误状态列表

签名步骤

1. 将所有非空值(null)请求参数按照名称字符ASCII升序排列，轉換為{key}={value}字串並以&拼接，最後将商户密钥作为最后一个参数，参数名为key
2. 将待签名字符串进行MD5杂凑运算并转为大写，得到签名

• 本文档所有示例皆使用以下配置：
  商戶ID： 1
  密钥： 9ce23be4-a31b-498f-b951-ad7e771c3d73

• 示例，待签名数据：

{
    "mch_id": 1,
    "mch_order_no": "111123456789",
    "apply_amount": 10000000,
    "pay_type": "bankcard",
    "order_type": "normal",
    "remark": "",
    "user_id": "123456",
    "device_type": "ios",
    "device_ip": "1.1.1.1",
    "real_name": "Thomas",
    "bank_code": "VCB",
    "timestamp": 1630000000
}

• 待签名字符：

apply_amount=10000000&bank_code=VCB&device_ip=1.1.1.1&device_type=ios&mch_id=1&mch_order_no=111123456789&order_type=normal&pay_type=bankcard&real_name=Thomas&remark=&timestamp=1630000000&user_id=123456&key=9ce23be4-a31b-498f-b951-ad7e771c3d73

• 签名值(需大写)：

F916EF22B036E81E122DC647B6E2F243

获取当前收银台下单金额区间

API请求方式

• HTTP GET
• Header{"Content-Type": "application/json"}
• body为JSON字符串
• 注意参数的类型，区分integer和string

接口地址：

http://<CASHIER_HOST>/api/cashier/valid_amount/

请求参数（非必填参数值可不传）

• 请求数据示例

{
    "mch_id": 1,
    "user_id": "123456",
    "device_type": "ios",
    "device_ip": "1.1.1.1",
    "device_id": "EC:51:BC:97:FF:19",
    "brand_code": "TEST",
    "timestamp": 1657000217,
    "sign": "5C8719D3F5448882FE0074E1FD0AF659"
}

返回参数

• 注意：

我方系统将支付类型分类为定额/非定额
amount_range统计可用非定额类型上下限并集
quota统计可用定额类型的去重额度
实际quota内的额度可能会超出amount_range

• 请求成功返回数据示例

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-02-17 14:19:25",
    "data": {
        "base_unit": 100,
        "amount_range": [1000, 1000000],
        "quota": [100, 500, 1000, 4000]
    }
}

获取各支付类型下单金额区间

• HTTP GET
• Header{"Content-Type": "application/json"}
• body为JSON字符串
• 注意参数的类型，区分integer和string

接口地址：

http://<CASHIER_HOST>/api/cashier/valid_pay_types/

请求参数（非必填参数值可不传）

• 请求数据示例

{
    "mch_id": 1,
    "user_id": "123456",
    "device_type": "ios",
    "device_ip": "1.1.1.1",
    "device_id": "EC:51:BC:97:FF:19",
    "brand_code": "TEST",
    "timestamp": 1657000217,
    "sign": "5C8719D3F5448882FE0074E1FD0AF659"
}

返回参数

• 注意：

当支付类型包含子类型时，data.pay_types[i]内展示的区间/额度为所有子类型取并集

• 请求成功返回数据示例

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-02-17 14:19:25",
    "data": {
        "base_unit": 100,
        "pay_types": [
            {
                "code": "qris",
                "with_sub_types": false,
                "min_amount": 100,
                "max_amount": 150000000,
                "quota": [],
                "sub_pay_types": []
            },
            {
                "code": "va",
                "with_sub_types": true,
                "min_amount": 100,
                "max_amount": 150000000,
                "quota": [],
                "sub_pay_types": [
                    {
                        "code": "BDIN",
                        "min_amount": 100,
                        "max_amount": 150000000
                    },
                    {
                        "code": "BMRI",
                        "min_amount": 100,
                        "max_amount": 150000000
                    },
                    {
                        "code": "CENA",
                        "min_amount": 1000000,
                        "max_amount": 150000000
                    }
                ]
            },
            {
                "code": "bankcard",
                "with_sub_types": true,
                "min_amount": 3000000,
                "max_amount": 150000000,
                "quota": [],
                "sub_pay_types": [
                    {
                        "code": "PDKB",
                        "min_amount": 3000000,
                        "max_amount": 150000000
                    },
                    {
                        "code": "PDKT",
                        "min_amount": 3000000,
                        "max_amount": 150000000
                    }
                ]
            },
            {
                "code": "dana",
                "with_sub_types": false,
                "min_amount": 100,
                "max_amount": 150000000,
                "quota": [],
                "sub_pay_types": []
            },
            {
                "code": "ovo",
                "with_sub_types": false,
                "min_amount": 100,
                "max_amount": 2000000000,
                "quota": [],
                "sub_pay_types": []
            }
        ]
    }
}

收银台获取接口

API请求方式

• HTTP POST
• Header{"Content-Type": "application/json"}
• body为JSON字符串
• 注意参数的类型，区分integer和string

接口地址：

http://<CASHIER_HOST>/api/cashier/

请求参数（非必填参数值可不传）

• 请求数据示例

{
    "mch_id": 1,
    "mch_order_no": "111123456789",
    "apply_amount": 10000000,
    "user_id": "123456",
    "device_type": "ios",
    "device_id": "EC:51:BC:97:FF:19",
    "device_ip": "1.1.1.1",
    "brand_code": "TEST",
    "real_name": "Thomas",
    "timestamp": 1656929507,
    "sign": "5DC800E8F4AB62C63172CA6C66A0C2D6"
}

返回参数

• 收银台下单成功返回数据示例

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-02-17 12:38:50",
    "data": {
        "order_no": "2202171238501159",
        "mch_order_no": "111123456789",
        "status": "new",
        "pay_type": null,
        "sub_pay_type": null,
        "open_type": "sys_url",
        "url": "http://test.cashier.com/?token=9af14fec-1a15-4230-b809-ef5e582ab989"
    }
}

获取用户订单查询入口（使用此接口前需要事前申请）

API请求方式

• HTTP POST
• Header{"Content-Type": "application/json"}
• body为JSON字符串
• 注意参数的类型，区分integer和string

接口地址：

http://<CASHIER_HOST>/api/cashier/orders/

请求参数（非必填参数值可不传）

• 请求数据示例

{
    "mch_id": 1,
    "user_id": "123456",
    "brand_code": "TEST",
    "timestamp": 1656947588,
    "sign": "4BD9AC2BF58503E389A3E916E33F3227"
}

返回参数

• 返回数据示例

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-02-17 12:38:50",
    "data": {
        "mch_id": 1,
        "user_id": "123456",
        "brand_code": "TEST",
        "url": "http://test.cashier.com/order_history/?token=9af14fec-1a15-4230-b809-ef5e582ab989"
    }
}

代收补单接口(商户用)

API请求方式

• HTTP POST
• Header{"Content-Type": "application/json"}
• body为JSON字符串
• 注意参数的类型，区分integer和string

接口地址：

http://<API_HOST>/api/order/replenish/

请求参数（非必填参数值可不传）

• 请求数据示例

{
    "mch_id": 1,
    "mch_order_no": "111123456789",
    "apply_amount": 10000000,
    "pay_type": "pix",
    "user_id": "123456",
    "real_name": "Thomas",
    "timestamp": 1657003362,
    "sign": "B9BBBB222845C00E30AD38DEB6393AC5"
}

补单流程

1. 补单由商户代替用户向JP提出
2. 我方运营人员处理补单
3. 订单完成后JP自动发起回调请求
4. 商户收到补单成功的回调后，补发用户充值金

返回参数

• 补单下单成功返回数据示例

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-05-04 09:06:40",
    "data": {
        "order_no": "2205040906401871",
        "mch_order_no": "111123456789",
        "status": "new",
        "pay_type": "pix",
        "sub_pay_type": null
        "apply_amount": 10000000,
        "real_amount": null,
        "remark": null
    }
}

• 下单失败返回数据示例

{
    "status": 2012,
    "msg": "商户订单ip不在白名单中",
    "timestamp": "2022-02-17 12:41:25"
}

支付回调

• 支付结果会以HTTP POST JSON形式从平台服务器发往贵司提供的回调地址
• 贵司收到通知处理成功后回复{"status": 0}
• 回复内容可加上msg以具体描述处理情形（非必填）
• 示例

{
    "status": 0,
    "msg": "处理成功"
}

• 我司在没有收到贵司成功响应前，会通过一定的策略定期重新发起通知

注意

• 請同时校验商户订单号及订单金额是否正确。
• 建议商户添加回调IP白名单。
• 一个订单可能会多次发送给接入方系统，接入方系统必须能够正确处理重复的通知。
  例如：商户手动处理为成功的订单，可能会再收到来自JP的成功回调

回调参数

• 回调请求数据示例

{
    "order_no": "2202171238501159",
    "mch_order_no": "111123456789",
    "status": "success",
    "apply_amount": 10000000,
    "real_amount": 10000000,
    "pay_type": "pix",
    "sub_pay_type": null,
    "remark": null,
    "timestamp": 1656945134,
    "sign": "DCB154D0C14F1B8803B1224A8DCC82D1"
}

订单查询(商户用)

API请求方式

• HTTP GET
• Header{"Content-Type": "application/json"}
• 注意参数的类型，区分integer和string

接口地址：

http://<API_HOST>/api/order/query/<str:mch_order_no>/

• mch_order_no为商戶订单号

请求参数（非必填参数值可不传）

• 请求示例

http://<API_HOST>/api/order/query/111123456789/?mch_id=1&timestamp=1657003725&sign=2DB6CA61B12EAC901B15E76C014F0B01

返回参数

• 查询成功返回数据示例(new)

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-04-08 16:15:39",
    "data": {
        "mch_order_no": "111123456789",
        "order_no": "2203240014034824",
        "status": "new",
        "pay_type": null,
        "sub_pay_type": null,
        "apply_amount": 60000,
        "real_amount": null,
        "remark": null,
        "user_ext": "{\"user_id\":\"123456\"}"
    }
}

• 查询成功返回数据示例(commit)

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-04-08 16:15:39",
    "data": {
        "mch_id": 1,
        "mch_order_no": "111123456789",
        "order_no": "2203240014034824",
        "status": "commit",
        "pay_type": "pix",
        "sub_pay_type": null,
        "apply_amount": 60000,
        "real_amount": null,
        "remark": null,
        "user_ext": "{\"user_id\":\"123456\"}"
    }
}

• 查询失败返回数据示例

{
    "status": 5001,
    "msg": "订单不存在",
    "timestamp": "2022-04-08 16:33:16"
}

代收申訴接口(商户用)

API请求方式

• HTTP POST
• Header{"Content-Type": "application/json"}
• body为JSON字符串
• 注意参数的类型，区分integer和string

接口地址：

http://<API_HOST>/api/order/inquiry/

请求参数（非必填参数值可不传）

• 请求数据示例

{
    "mch_id": 1,
    "order_no": "2203240014034824",
    "mch_inquiry_no": "111234567890",
    "inquiry_amount": 1000000,
    "user_id": "123456",
    "user_real_name": "Ida Bagus Sudjana",
    "notify_url": "http://test_inquiry.com/v3/trade/appeal_notify/jp/",
    "receipt": [
        "https://imgur.com/gallery/VWjRf"
    ],
    "user_remark": "I've paid!",
    "timestamp": 1657004710,
    "sign": "0AF3ED4FEF59843AE7027F5D86869927"
}

返回参数

• 申訴请求成功返回数据示例

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-05-04 11:33:42",
    "data": {
        "mch_order_no": "1234567890",
        "order_no": "2203240014034824",
        "mch_inquiry_no": "111234567890",
        "inquiry_order_no": "2205041133420031",
        "status": "new",
        "inquiry_amount": 1000000,
        "user_remark": "I've paid!",
        "reason": null
    }
}

• 申訴请求失败返回数据示例

{
    "status": 5100,
    "msg": "申诉订单已存在",
    "timestamp": "2022-05-04 11:27:16"
}

{
    "status": 5001,
    "msg": "订单不存在",
    "timestamp": "2022-05-04 12:15:24"
}

申诉回调

• 申诉结果会以HTTP POST JSON形式从平台服务器发往申诉请求时提供的回调地址(notify_url)
• 贵司收到通知处理成功后回复{"status": 0}
• 回复内容可加上msg以具体描述处理情形（非必填）
• 示例

{
    "status": 0,
    "msg": "处理成功"
}

• 我司在没有收到贵司成功响应前，会通过一定的策略定期重新发起通知

回调参数

• 回调请求数据示例

{
    "mch_order_no": "1234567890",
    "order_no": "2203240014034824",
    "mch_inquiry_no": "111234567890",
    "inquiry_order_no": "2205041133420031",
    "status": "success",
    "inquiry_amount": 1000000,
    "user_remark": "I've paid!",
    "reason": "已完成充值",
    "timestamp": 1651648963,
    "sign": "FE4117A73E8EA77784DE4FFF1FDAD64B"
}

新增商户品牌（或更新品牌名稱）

API请求方式

• HTTP PUT
• Header{"Content-Type": "application/json"}
• body为JSON字符串
• 注意参数的类型，区分integer和string

接口地址：

http://<API_HOST>/api/mch/brand/

请求参数（非必填参数值可不传）

• 请求数据示例

{
    "mch_id": 1,
    "brand_code": "TEST",
    "brand_name": "测试品牌",
    "timestamp": 1656314694,
    "sign": "DC322F75136CE3B0A43E93321B1A8B8D"
}

• 请求成功返回数据示例

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-06-27 14:31:05",
    "data": {}
}

订单状态列表

请求错误状态列表

支付类型列表

印度银行编码列表

• 代码为IFSC前四码
• 列表若更新，会通知商户

印尼银行编码列表

用户个人信息（下单）

用户个人信息（回调＆查询）

• 蓝色 参数为相较于下单时增加的参数