帮助中心

支付宝支付API

2018-11-14

支付Api地址:

测试环境:http://test.ezrpro.cn:3309

正式环境:http://pay.ezrpro.cn

支付宝支付API

签名算法:

API接口请求加签算法:

签名生成的通用步骤如下:

签名生成规则如下:参与签名的字段包括AppIdTimestamp(时间戳),Token 以及业务参数。对所有待签名参数按照字段名的ASCII 码从小到大排序(字典序)后,使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串string1。这里需要注意的是所有参数名均区分大小写数组类型参数不参与计算。对string1作sha1加密,然后转换成小写,字段名和字段值都采用原始值,不进行URL 转义


 即signature=sha1(string1)。 示例:

  • AppId = EZP

  • Token = HH1232D

  • Timestamp = 20160523235959

  • ShopCode = HQ01S001

  • UserCode = KB1001


    步骤1.

    对所有待签名参数按照字段名的ASCII 码从小到大排序(字典序)后,使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串string1:

    AppId=EZP&AuthCode=130115575166786427&Subject=刷卡支付测试&ShopCode=HQ01S001&Timestamp=20160523235959&Token=1234Tk123&TotalAmount=1&UserCode=323231&VipOldCode=EZ0541688

    ·              

    步骤2. 

    对string1进行sha1签名,转成小写,得到signature:e0afdde6ff59081f18609f8d77926d88bc43a3db


    注意事项:

    • 空值不参与签名

    • 属性值区分大小写

    • Sha1之后需要转换成小写

    接口返回码说明(BusinessCode):

    0 :成功

    500:业务异常

    4001:参数错误

    1、条码支付下单

    接口说明:

    收银员使用扫码设备读取用户手机支付宝“付款码”,将二维码或条码信息通过本接口进行支付下单


    请求说明:

    • http请求方式:POST

    • 返回数据格式:JSON

    • 请求路径:/alipay/open/createalipay

    请求参数:

    参数类型必填长度描述示例值
    AppIdstring

    EZR
    提供的
    AppId

    Timestampstring
    时间戳
    Signstring
    签名
    TradeNostring64商户订单号
    ,
    可包含字母、数字、下划线
    20150320010101001
    AuthCodestring32支付授权码28763443825664394
    ShopCodestring16门店代号SH001
    TotalAmountdecime11订单支付金额88.88
    Subjectstring64订单标题
    Bodystring128订单描述Iphone6 16G
    DiscountableAmountdecime11参与优惠计算的金额,单位为元,精确到小数点后两位,取值范围
    [0.01,100000000]

    如果该值未传入,但传入了【订单总金额】和【不可打折金额】,则该值默认为【订单总金额】
    -
    【不可打折金额】
    8.88
    UndiscountableAmountdecime11不参与优惠计算的金额,单位为元,精确到小数点后两位,取值范围
    [0.01,100000000]
    。如果该值未传入,但传入了【订单总金额】和【可打折金额】,则该值默认为【订单总金额】
    -
    【可打折金额】
    80.00
    UserCodestring16员工工号HY001
    VipOldCodestring20会员老卡号OLDHY001
    OperatorIdstring28商户操作员编号yx_001
    TerminalIdString32商户机具终端编号NJ_T_001
    AlipayStoreIdString32支付宝的店铺编号2016041400077000000003314986
    GoodsDetailGoodsDetail[]
    订单包含的商品列表信息,json格式,其它说明详见商品明细说明



    GoodsDetail[]:商品明细说明

    字段类型必填描述示例值
    goods_idstring商品的编号apple-01
    goods_namestring商品名称ipad
    quantitynumber商品数量1
    priceprice商品单价,单位为元2000
    goods_categorystring商品类目34543238
    bodystring商品描述信息特价手机
    show_urlstring商品的展示地址http://www.alipay.com/xxx.jpg


     


    响应参数:

    字段类型描述示例值
    OrderIdlong订单编号,用户获取
    ezr
    支付订单的编号
    46
    TradeNostringEzr
    的支付订单订单号(不是传入的商户订单号)
    WP01126317041000000015
    Codestring返回码40004
    Msgstring返回码描述Business Failed
    SubCodestring业务返回码aop.invalid-auth-token
    SubMsgstring业务返回码描述无效的访问令牌


     

    请求参数示例代码(json对象):

    {
        "AppId": "EZP",
        "Timestamp": "20160523235959",
        "Sign": "AB52DAC1832949EAC322FCFD7F515A987C9E8A67",
        "TradeNo": "2017050301001",
        "AuthCode": "282078355612576520",
        "ShopCode": "21015",
        "TotalAmount": 0.1,
        "Subject": "鞋子",
        "GoodsDetail": [
            {
                "goods_id": "PR10000",
                "goods_name": "测试商",
                "quantity": 1,
                "price": "0.05"
            }
        ]
    }


    系统返回参数示例(json对象):

    {
        "Success": true,
        "Msg": "操作成功",
        "Status": 200,
        "BusinessCode": 0,
        "ServerTime": " 2017-04-18T17:57:17.3094616+08:00",
        "Result": {
            "OrderId": 38,
            "TradeNo": " WP01953717041800000004",
            "Code": "10000",
            "IsError": false,
            "Msg": "SUCCESS",
            "SubCode": null,
            "SubMsg": null
        }
    }



    避免不合法的传参

    原因:传参错误会导致支付异常。

    建议方案:对所有返回INVALID_PARAMETER的响应进行监控,一旦发现请停止调用并检查请求参数,修改后重新发起请求。

     

    支付等待(如等待用户输入密码等)

    对所有唤起收银台的交易(支付宝返回状态10003) EZR接口将发起轮询,3秒一次 一共5分钟,直至交易成功。如果轮询结束后还是支付处理中,EZR将会调用撤销接口,取消当前交易。

    支付等待返回结果:

    Code:10003

    Msg:   order success pay inprocess

     

    POS支付结果回调:

    交易状态获取完成后会将状态回调到POS支付结果Callback地址,回传的时候如果出现网络超时,会尝试多次回调,同时ezr也提供了查询订单信息的接口(接口详情可以看订单信息查询接口),在出现回调不成功的情况下,可以通过订单查询接口获取订单状态

     

    回调返回参数:

    字段类型描述
    Brandstring所属品牌
    TradeNostring订单号
    TotalFeeint订单金额(分)
    CashFeeint支付金额(分)
    TransactionIdstring支付宝支付订单号
    PayTimestring支付时间
    TradeStatestring订单状态
    PayErrorCodestring支付错误代码
    PayErrorMsgstring支付错误描述


     

    订单状态码(TradeState)

    • SUCCESS—支付成功

    • INRROCESS—支付等待

    • FAILED--支付失败(其他原因,如银行返回失败)

    业务错误码(PayErrorCode)

         详见 附表1

       

     2、订单信息查询接口

     

    接口说明:

    • 用于获取单个订单的信息(可用于订单callback接收失败获取订单状态)

    请求说明:

    • http请求方式:POST

    • 返回数据格式:JSON

    • 请求路径:/alipay/open/getorderinfo

    请求参数:

    字段类型必填长度描述
    AppIdstring

    EZR
    提供的
    AppId
    Timestampstring
    时间戳
    Signstring
    签名
    ShopCodestring
    门店代号
    TradeNostring特殊可选
    EZR
    的商户订单号
    OutTradeNostring特殊可选
    商户生成支付传入的TradeNo


    注意:订单查询时传入的商户订单号,和EZR的商户订单号不能同时为空。 TradeNo,OutTradeNo如果同时存在优先取TradeNo。

     

    返回参数:

    字段类型描述
    TradeNostring支付订单号
    OutTradeNostring外部订单号
    UserCodestring员工工号
    TotalFeeInt订单金额(分)
    CashFeeInt支付金额(分)
    RefundFeeInt退款金额(分)
    CreateDateDateTime订单创建时间
    TradeStatestring订单状态
    PayErrorMsgstring订单支付失败原因
    PayTimeDateTime订单支付时间


     

    请求参数示例代码(json对象):

    {
        "AppId": "EZP",
        "Timestamp": "20160523235959",
        "Sign": "AB52DAC1832949EAC322FCFD7F515A987C9E8A67",
        "ShopCode": "HQ01S001",
        "TradeNo": "WP01631316101000000017"
    }


    系统返回结果示例:

    {
        "TradeNo": "WP01631316101000000017",
        "OutTradeNo": "",
        "UserCode": "323231",
        "TotalFee": 1,
        "CashFee": 1,
        "RefundFee": 0,
        "CreateDate": "2016-10-10T16:58:15",
        "TradeState": "SUCCESS",
        "PayErrorMsg": "",
        "PayTime": "2016-10-10T16:58:32"
    }


     

     

    3、支付订单列表获取

     

    接口说明:

    • 用户获取支付订单列表

    请求说明:

    • http请求方式:POST

    • 返回数据格式:JSON

    • 请求路径:/alipay/open/getorderlist

    请求参数:

    字段类型必填长度描述
    AppIdstring

    EZR
    提供的
    AppId
    Timestampstring
    时间戳
    Signstring
    签名
    TradeNostring
    Ezr
    支付订单号,用户查询
    BeginTimestring
    查询开始时间时间戳,秒
    EndTimestring
    查询结束时间时间戳,秒
    ShopCodestring
    门店
    code
    PageIndexInt

    1
    开始的页码(默认值
    1
    PageSizeInt
    分页条数(默认值
    100


    返回参数:

    字段类型描述
    OrderIdlong订单编号,用户获取
    ezr
    支付订单的编号
    PayTypeInt支付方式,
    默认值
    2
    支付宝支付
    TradeNostring支付订单号
    OutTradeNostring外部订单号
    UserCodestring员工工号
    TotalFeeInt订单金额(分)
    CashFeeInt支付金额(分)
    RefundFeeInt退款金额(分)
    CreateDateDateTime订单创建时间
    TradeStatestring订单状态
    PayErrorMsgstring订单支付失败原因
    PayTimeDateTime订单支付时间
    VipMobileNostring会员手机号
    VipNamestring会员名字


     

    请求参数示例:

    {
        "AppId": "EZP",
        "Timestamp": "20160523235959",
        "Sign": "AB52DAC1832949EAC322FCFD7F515A987C9E8A67",
        "ShopCode": "HQ01S001",
        "PageIndex": 1,
        "PageSize": 20
    }


    返回参数示例:

    {
      "Success": false,
      "Msg": "操作成功",
      "Status": 200,
      "ServerTime": "2016-09-18T16:39:01.3853029+08:00",
      "Count": 1,
      "Result": [
        {
          "OrderId": 79,
          "PayType": 0,
          "TradeNo": "WP01366216091800000001",
          "UserCode": "323231",
          "TotalFee": 1,
          "CashFee": 0,
          "RefundFee": 0,
          "CreateDate": "2016-09-18T15:15:38",
          "TradeState": "FAILED",
          "PayErrorMsg": 支付失败,请刷新付款码后重试,
          "PayTime": "2016-09-18T15:15:38",
          "VipMobileNo": "18302188990",
          "VipName": "cycle"
        }
      ],
      "PageTotal": 1,
      "BusinessCode": 0
    }


     

     4、退款申请接口

     

    接口说明:

    • 用于支付订单进行退款申请,一个订单可以多次退款

    请求说明:

    • http请求方式:POST

    • 返回数据格式:JSON

    • 请求路径:/alipay/open/createalipayrefund

    请求参数:

    字段类型必填长度描述
    AppIdString

    EZR
    提供的
    AppId
    TimestampString
    时间戳
    SignString
    签名
    TradeNoString
    Ezr
    支付订单号
    RefundFeeInt
    退款金额
    (
    退款金额不能大于可退金额
    ,
    单位:分
    )
    GoodsDetailGoodsDetail[]
    订单包含的商品列表信息,json格式,其它说明详见商品明细说明


     

    GoodsDetail[]:商品明细说明

    字段类型必填描述示例值
    goods_idstring商品的编号apple-01
    goods_namestring商品名称ipad
    quantitynumber商品数量1
    priceprice商品单价,单位为元2000
    goods_categorystring商品类目34543238
    bodystring商品描述信息特价手机
    show_urlstring商品的展示地址http://www.alipay.com/xxx.jpg


     

    返回参数:

    返回退款单号

    请求参数示例:

    {
        "AppId": "EZP",
        "Timestamp": "20160523235959",
        "Sign": "AB52DAC1832949EAC322FCFD7F515A987C9E8A67",
        "TradeNo": 21,
        "RefundFee": 50
    }


     

    返回参数示例:

    {
      "Success": true,
      "Msg": "操作成功",
      "Status": 200,
      "BusinessCode": 0,
      "ServerTime": "2016-09-18T17:01:01.3977386+08:00",
      "Result": "WPR01408316091800000001"
    }


     

    5、退款单列表查询

     

    接口说明:

    • 用户获取支付订单退款列表

    请求说明:

    • http请求方式:POST

    • 返回数据格式:JSON

    • 请求路径:/alipay/open/getorderrefundlist

    请求参数:

    字段类型必填长度描述
    AppIdstring

    EZR
    提供的
    AppId
    Timestampstring
    时间戳
    Signstring
    签名
    RefundNostring
    Ezr
    支付退款单号,用户查询
    BeginTimestring
    查询开始时间时间戳,秒
    EndTimestring
    查询结束时间时间戳,秒
    ShopCodestring
    门店
    code
    PageIndexInt

    1
    开始的页码,默认值:
    1
    PageSizeInt
    分页条数,默认值:
    100


    返回参数:

    字段类型描述
    OrderRefundIdlong退款订单编号
    RefundTypeInt退款支付方式:
    默认

    2
    支付宝支付
    RefundNostring支付退款单号
    UserCodestring员工工号
    CashFeeInt支付金额(分)
    RefundFeeInt退款金额(分)
    CreateDateDateTime订单创建时间
    RefundStatusstring退款单状态
    VipMobileNostring会员手机号
    VipNamestring会员名字


     

    请求参数示例:

    {
        "AppId": "EZP",
        "Timestamp": "20160523235959",
        "Sign": "AB52DAC1832949EAC322FCFD7F515A987C9E8A67",
        "ShopCode": "HQ01S001",
        "PageIndex": 1,
        "PageSize": 20
    }


    返回参数示例:

    {
      "Success": false,
      "Msg": "操作成功",
      "Status": 200,
      "ServerTime": "2016-09-18T17:07:36.1546628+08:00",
      "Count": 2,
      "Result": [
        {
          "OrderRefundId": 6,
          "RefundType": 0,
          "RefundNo": "WPR01408316091800000001",
          "UserCode": "323231",
          "CashFee": 1,
          "RefundFee": 1,
          "CreateDate": "2016-09-18T17:01:01",
          "RefundStatus": "PROCESSING",
          "VipMobileNo": "18302188990",
          "VipName": "cycle"
        },
        {
          "OrderRefundId": 5,
          "RefundType": 0,
          "RefundNo": "WPR01944916091300000003",
          "UserCode": null,
          "CashFee": 1,
          "RefundFee": 1,
          "CreateDate": "2016-09-13T19:40:01",
          "RefundStatus": "PROCESSING",
          "VipMobileNo": "18302188990",
          "VipName": "cycle"
        }
      ],
      "PageTotal": 1,
      "BusinessCode": 0
    }


     

    退款单状态:

    • SUCCESS—退款成功

    • FAIL—退款失败

    • PROCESSING—退款处理中

     

    6、支付订单取消接口

     

    接口说明:

    • 支付交易返回失败或支付系统超时,调用该接口撤销交易。如果此订单用户支付失败,支付宝系统会将此订单关闭;如果用户支付成功,支付宝系统会将此订单资金退还给用户。 注意:只有发生支付系统超时或者支付结果未知时可调用撤销,其他正常支付的单如需实现相同功能请调用申请退款API。提交支付交易后调用【查询订单API】,没有明确的支付结果再调用【撤销订单API】。

    请求说明:

    • http请求方式:POST

    • 返回数据格式:JSON

    • 请求路径:/alipay/open/tradecancel

    请求参数:

    字段类型必填长度描述
    AppIdstring

    EZR
    提供的
    AppId
    Timestampstring
    时间戳
    Signstring
    签名
    ShopCodestring
    门店代号
    TradeNostring特殊可选
    EZR
    的商户订单号
    OutTradeNostring特殊可选
    商户生成支付传入的TradeNo


    注意:订单取消时传入的商户订单号,和EZR的商户订单号不能同时为空。 TradeNo,OutTradeNo如果同时存在优先取TradeNo。

    返回参数:

    字段类型描述示例值
    TradeNostring支付宝交易号2013112011001004330000121536
    OutTradeNostring外部订单号AP01631316101000000017
    RetryFlagstring是否需要重试N
    Actionstring本次撤销触发的交易动作 
    close:关闭交易,无退款 
    refund:产生了退款
    close


     

    请求参数示例代码(json对象):

    {
    "AppId": "EZP",
    "Timestamp": "20160523235959",
    "Sign": "AB52DAC1832949EAC322FCFD7F515A987C9E8A67",
    "ShopCode": "HQ01S001",
    "TradeNo": "WP01631316101000000017"
    }


    系统返回结果示例:

    {
        "TradeNo": "AP01631316101000000017",
        "OutTradeNo": "",
        "RetryFlag": "N",
        "Action": "close",
        "Code": 1000,
        "Msg": "Success"
    }


     业务错误码:

    错误码错误描述解决方案
    AQC.SYSTEM_ERROR系统错误请使用相同的参数再次调用
    ACQ.INVALID_PARAMETER参数无效请求参数有错,重新检查请求后,再调用撤销
    ACQ.SELLER_BALANCE_NOT_ENOUGH商户的支付宝账户中无足够的资金进行撤销商户支付宝账户充值后重新发起撤销即可
    ACQ.REASON_TRADE_BEEN_FREEZEN当前交易被冻结,不允许进行撤销联系支付宝小二,确认该笔交易的具体情况


    附表1

    错误码错误描述解决方案
    ACQ.SYSTEM_ERROR接口返回错误请立即调用查询订单API,查询当前订单的状态,并根据订单状态决定下一步的操作,如果多次调用依然报此错误码,请联系支付宝客服
    ACQ.INVALID_PARAMETER参数无效检查请求参数,修改后重新发起请求
    ACQ.ACCESS_FORBIDDEN无权限使用接口未签约条码支付或者合同已到期
    ACQ.EXIST_FORBIDDEN_WORD订单信息中包含违禁词修改订单信息后,重新发起请求
    ACQ.TOTAL_FEE_EXCEED订单总金额超过限额修改订单金额再发起请求
    ACQ.PAYMENT_AUTH_CODE_INVALID支付授权码无效用户刷新条码后,重新扫码发起请求
    ACQ.CONTEXT_INCONSISTENT交易信息被篡改更换商家订单号后,重新发起请求
    ACQ.TRADE_HAS_SUCCESS交易已被支付确认该笔交易信息是否为当前买家的,如果是则认为交易付款成功,如果不是则更换商家订单号后,重新发起请求
    ACQ.TRADE_HAS_CLOSE交易已经关闭更换商家订单号后,重新发起请求
    ACQ.BUYER_BALANCE_NOT_ENOUGH买家余额不足买家绑定新的银行卡或者支付宝余额有钱后再发起支付
    ACQ.BUYER_BANKCARD_BALANCE_NOT_ENOUGH用户银行卡余额不足建议买家更换支付宝进行支付或者更换其它付款方式
    ACQ.ERROR_BALANCE_PAYMENT_DISABLE余额支付功能关闭用户打开余额支付开关后,再重新进行支付
    ACQ.BUYER_SELLER_EQUAL买卖家不能相同更换买家重新付款
    ACQ.TRADE_BUYER_NOT_MATCH交易买家不匹配更换商家订单号后,重新发起请求
    ACQ.BUYER_ENABLE_STATUS_FORBID买家状态非法用户联系支付宝小二(联系支付宝文档右边的客服头像或到支持中心咨询),确认买家状态为什么非法
    ACQ.PULL_MOBILE_CASHIER_FAIL唤起移动收银台失败用户刷新条码后,重新扫码发起请求
    ACQ.MOBILE_PAYMENT_SWITCH_OFF用户的无线支付开关关闭用户在PC上打开无线支付开关后,再重新发起支付
    ACQ.PAYMENT_FAIL支付失败用户刷新条码后,重新发起请求,如果重试一次后仍未成功,更换其它方式付款
    ACQ.BUYER_PAYMENT_AMOUNT_DAY_LIMIT_ERROR买家付款日限额超限更换买家进行支付
    ACQ.BEYOND_PAY_RESTRICTION商户收款额度超限联系支付宝小二提高限额(联系电话:0571-88158090)
    ACQ.BEYOND_PER_RECEIPT_RESTRICTION商户收款金额超过月限额联系支付宝小二提高限额(联系电话:0571-88158090)
    ACQ.BUYER_PAYMENT_AMOUNT_MONTH_LIMIT_ERROR买家付款月额度超限让买家更换账号后,重新付款或者更换其它付款方式
    ACQ.SELLER_BEEN_BLOCKED商家账号被冻结联系支付宝小二,解冻账号(联系电话:95188)
    ACQ.ERROR_BUYER_CERTIFY_LEVEL_LIMIT买家未通过人行认证让用户联系支付宝小二并更换其它付款方式(联系电话:95188)
    ACQ.PAYMENT_REQUEST_HAS_RISK支付有风险更换其它付款方式
    ACQ.NO_PAYMENT_INSTRUMENTS_AVAILABLE没用可用的支付工具更换其它付款方式
    ACQ.USER_FACE_PAYMENT_SWITCH_OFF用户当面付付款开关关闭让用户在手机上打开当面付付款开关
    ACQ.INVALID_STORE_ID商户门店编号无效检查传入的门店编号是否有效