tags: GLO UA BR

UA_GLO商户对接文档 - 巴西(1.02)

change log

接入流程

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

API说明

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

签名步骤

1. 将所有非空值(null)请求参数按照名称字符ASCII升序排列，轉換為{key}={value}字串並以&拼接，最後将密钥作为最后一个参数，参数名为key
2. 若参数值的数据类型为dict，则按照其中参数名称字符ASCII升序排列(不需排除null)，再转为JSON字串作为value

示例：

{
    "p1": {
        "c": 3,
        "a": 1,
        "b": null
    }
}

字符串

p1={"a":1,"b":null,"c":3}

3. 将待签名字符串进行MD5杂凑运算并转为大写，得到签名

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

• 示例，待签名数据：

{
    "mch_id": 1,
    "mch_withdraw_no": "1234567890",
    "amount": 56500,
    "withdraw_type": "bankcard",
    "withdraw_name": "Ida Bagus Sudjana",
    "withdraw_account": "168168168168168168",
    "withdraw_bank_code": "BMRI",
    "user_id": "1002026573",
    "timestamp": 1650276377
}

• 签名字符串：

amount=56500&mch_id=1&mch_withdraw_no=1234567890&timestamp=1650276377&user_id=1002026573&withdraw_account=168168168168168168&withdraw_bank_code=BMRI&withdraw_name=Ida Bagus Sudjana&withdraw_type=bankcard&key=9ce23be4-a31b-498f-b951-ad7e771c3d73

• 签名值(需大写)：

D5C222E7BB941A0D13FCB236D53F159B

代付下单接口

注意

调用代付下单接口时，只有接口明确返回了不成功的状态码才表示下单失败。
其它比如请求超时，服务器错误等非约定场景均不能表示下单失败。
重新下单前请务必通过查询接口判断订单状态。

API请求方式

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

接口地址：

http://<HOST>/api/withdraw/

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

PIX提现扩展参数

• 请求数据示例

{
    "mch_id": 1,
    "mch_withdraw_no": "1234567890",
    "amount": 41700,
    "withdraw_type": "pix",
    "withdraw_name": "João Luiz Ferreira Silva",
    "withdraw_account": "123.456.789-01",
    "pix_withdraw_ext": {
        "pix_key_type": "CPF",
        "identity": "123.456.789-01"
    },
    "user_id": "1002026573",
    "device_type": "ios",
    "device_ip": "127.0.0.1",
    "device_id": "EC:51:BC:97:FF:19",
    "timestamp": 1657189611,
    "sign": "892CDBD230792ACEE232B590488A8415"
}

• 待签名字符串：

amount=41700&device_id=EC:51:BC:97:FF:19&device_ip=127.0.0.1&device_type=ios&mch_id=1&mch_withdraw_no=1234567890&pix_withdraw_ext={"identity":"123.456.789-01","pix_key_type":"CPF"}&timestamp=1657189611&user_id=1002026573&withdraw_account=123.456.789-01&withdraw_name=João Luiz Ferreira Silva&withdraw_type=pix&key=9ce23be4-a31b-498f-b951-ad7e771c3d73

• 签名值(需大写)：

892CDBD230792ACEE232B590488A8415

下单返回参数

• 下单成功返回数据示例

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-04-19 10:39:38",
    "data": {
        "order_id": "2204191039380826",
        "mch_withdraw_no": "1234567890",
        "status": "new",
        "remark": null
    }
}

• 下单失败返回数据示例

{
    "status": 5001,
    "msg": "暂无可用提现资源",
    "timestamp": "2022-04-19 10:46:09"
}

代付回调

• 支付结果会以HTTP POST JSON形式从平台服务器发往贵司提供的回调地址

• 贵司收到通知处理成功后回复{"status": 0}

• 回复内容可加上msg以具体描述处理情形（非必填）

• 示例

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

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

注意

• 請同时校验商户订单号及订单金额是否正确。
• 建议商户添加回调IP白名单。
• 一个订单可能会多次发送给接入方系统，接入方系统必须能够正确处理重复的通知。
• 已回调成功的订单也有可能会再转为失败，我方会将款项退回给商户，并发起status为callback的回调(沖正)给商户，商户收到此回调也应将款项退回给用户。

回调参数

• 回调请求数据示例

{
    "order_id": "2204191039380826",
    "mch_withdraw_no": "1234567890",
    "status": "success",
    "remark": null,
    "merchant_code": "test",
    "timestamp": 1650343502,
    "sign": "9CD29D2F819C747268B6500BAB5358AF"
}

• 签名字符串：

mch_withdraw_no=1234567890&merchant_code=test&order_id=2204191039380826&status=success&timestamp=1650343502&key=9ce23be4-a31b-498f-b951-ad7e771c3d73

• 签名值(需大写)：

9CD29D2F819C747268B6500BAB5358AF

获取当前提现区间

API请求方式

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

接口地址

http://<HOST>/api/withdraw/withdraw_type/

注意

• 本接口提供商户大致的提现区间

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

• 请求数据示例

{
    "mch_id": 1,
    "timestamp": 1650343839,
    "sign": "E351CA51F588B3D8C0676A5B6B06F394"
}

• 签名字符串：

mch_id=1&timestamp=1650343839&key=9ce23be4-a31b-498f-b951-ad7e771c3d73

• 签名值(需大写)：

E351CA51F588B3D8C0676A5B6B06F394

返回参数

• 请求成功返回数据示例

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-04-19 13:23:28",
    "data": [
        {
            "withdraw_type": "pix",
            "min_amount": 30000000,
            "max_amount": 500000000
        }
    ] 
}

获取当前精准提现区间

API请求方式

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

接口地址：

http://<HOST>/api/withdraw/withdraw_type/detail/

注意

• 本接口提供商户精准的提现区间
• 商户应根据此接口返回参数展示可用提现区间给用户
• 根据用户可提供的个人信息，展示给用户的区间也会不同
• 以下图为例，假设用户名及身分证明在下单时皆为选填，若用户不能提供用户名及身分证明，实际可用的提现区间则为default, unidentified, anonymous三者交集
  
• 接口返回参数说明中若无default之外的金额区间，直接使用default即可

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

• 请求数据示例

{
    "mch_id": 1,
    "timestamp": 1650343839,
    "sign": "E351CA51F588B3D8C0676A5B6B06F394"
}

• 签名字符串：

mch_id=1&timestamp=1650343839&key=9ce23be4-a31b-498f-b951-ad7e771c3d73

• 签名值(需大写)：

E351CA51F588B3D8C0676A5B6B06F394

返回参数

无子类结构

含子类结构

金额区间

• 请求成功返回数据示例

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-04-19 13:23:28",
    "data": [
        {
            "withdraw_type": "pix",
            "sub_withdraw_types": [
                {
                    "sub_withdraw_type": "CPF",
                    "default": {
                        "quota": [],
                        "min_amount": 30000000,
                        "max_amount": 500000000
                    },
                    "unidentified": {
                        "quota": [],
                        "min_amount": 30000000,
                        "max_amount": 400000000
                    }
                },
                {
                    "sub_withdraw_type": "EMAIL",
                    "default": {
                        "quota": [],
                        "min_amount": 30000000,
                        "max_amount": 500000000
                    },
                    "unidentified": {
                        "quota": [],
                        "min_amount": 30000000,
                        "max_amount": 400000000
                    }
                },
                {
                    "sub_withdraw_type": "PHONE",
                    "default": {
                        "quota": [],
                        "min_amount": 30000000,
                        "max_amount": 500000000
                    },
                    "unidentified": {
                        "quota": [],
                        "min_amount": 30000000,
                        "max_amount": 400000000
                    }
                }
            ]
        }
    ] 
}

订单查询

API请求方式

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

接口地址：

http://<HOST>/api/withdraw/query/<str:mch_withdraw_no>/

• mch_withdraw_no为商户订单号

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

• 请求地址示例

http://<HOST>/api/order/query/2204191039380826/

• 请求数据示例

{
    "mch_id": 1,
    "timestamp": 1650343839,
    "sign": "E351CA51F588B3D8C0676A5B6B06F394"
}

• 签名字符串：

mch_id=1&timestamp=1650343839&key=9ce23be4-a31b-498f-b951-ad7e771c3d73

• 签名值(需大写)：

E351CA51F588B3D8C0676A5B6B06F394

返回参数

• 查询成功返回数据示例

{
    "status": 0,
    "msg": "OK",
    "timestamp": "2022-04-19 13:31:27",
    "data": {
        "order_id": "2204191039380826",
        "mch_withdraw_no": "1234567890",
        "status": "fail",
        "remark": null
    }
}

• 查询失败返回数据示例

{
    "status": 5002,
    "msg": "提现订单不存在",
    "timestamp": "2022-04-19 13:38:18"
}

提现类型列表

PIX键类型列表

请求错误状态列表