Alpha Pay 支付接口

Overview

接入前准备

1. 商户在开始技术集成前,需要先跟Alpha Pay签订相关产品的合同。如需帮助,请联系Alpha Pay商务团队
2. 商户获得测试账户的商户编码与商户密钥
3. APP或者小程序接入需提供APPID给Alpha Pay进行绑定才能成功接入微信支付。

适用于支付场景


渠道区分

根据调用接口不同分为线上和线下两个渠道,两个渠道分别使用不同的汇率和手续费费率,为避免混淆在此区分:
  • 线上渠道:包含QR CODE、Web、JSAPI、H5、APP SDK、MiniProgram 六种支付方式
  • 线下渠道:包含Retail Pay 支付方式
相似接口区别:
  • JSAPI和H5 Mobile:JSAPI只能在微信、支付宝客户端内访问的页面调起支付,H5可以在移动设备任意浏览器或App的WebView调起支付
  • Web支付和QR Code: Web支付会跳转到支付宝官方收银台,用户可以选择登陆账号或用客户端扫码完成支付;QR Code方式商户可以自行展示创建的二维码,也可以跳转到AlphaPay展示的收银台页面显示二维码,用户只能用支付宝客户端扫码完成支付。

案例

demo.alphapay.ca

Wordpress 案例 - 测试WooCommerce支付插件

demo.alphapay.ca/wp

适用货币

AlphaPay接受人民币和加元两个币种的支付订单
  • CAD:加元
  • CNY:人民币

业务规则

  • QRCode支付是在网页上展示二维码,用户使用微信扫一扫扫码后直接进入微信支付页面,适用于商城类web网站;
  • JSAPI支付是在微信浏览器内直接跳转到AlphaPay让用户选择支付订单,页面只能在微信客户端打开,适用于微店;
  • 创建订单时需要提供订单号,同一个订单允许重复提交,系统会自动根据订单状态判断是否创建新订单并关闭旧订单。因此商户端应该同一个订单只用一个单号,避免重复付款;
  • 由于存在自动创建新订单机制,创建订单后返回的AlphaPay单号不代表最终支付的单号;
  • QRCode支付订单创建后会直接返回QRCode和pay_url,商户可以自行选择展示支付二维码或跳转至AlphaPay支付页;
  • JSAPI支付订单创建后会返回pay_url,商户应该跳转到这个地址让用户完成支付;
  • 跳转pay_url时必须加上签名信息;
  • 每次请求都应该生成新的签名;
  • 订单成功支付后会调用订单中提供的notify_url,详情可以查看API定义;若创建订单时未提供,商户需要在创建订单后轮询订单状态接口,直到订单被支付或过期;
  • 订单支付有效期为5分钟,超时可以用相同的订单号重新发起请求,建议重新发起请求的时机为用户再次打开支付页的时候;
  • 使用跳转支付页前应该先调用后台服务输入金额等参数创建订单后再跳转;
  • 创建订单、创建退款接口都允许同订单号重复调用,但是具体参数以初次请求的参数为准;
  • 所有和金额相关的数字均以货币最小面值为单位,以CAD为例,100表示CAD 1.00。

请求参数说明

请求方式和参数格式

支付单和退款单提交均为PUT方式,订单查询均为GET方式;包含Request Entity的请求参数格式为json
除跳转页面外,所有的Accept均为application/json,所有的PUT/POST请求Content-Type为application/json。
系统使用UTF-8字符集。

参数分为三种:Path Variable/Query Param/JSON entity
  • Path Variable: 包含在URI内的参数
  • Query Param: 在URI末尾?后的key=value形式的参数
  • JSON entity: 只在PUT/POST请求中使用

所有返回JSON的API,成功访问返回状态值均为200(不论执行结果)。
JSON固定包含字段return_code
  • 若值为SUCCESS则表示执行成功。
  • 其他值表示执行失败,此时可查询错误码了解对应的错误类型,此时还会携带return_msg字段作为错误描述信息。

多语言支持

系统错误提示支持中文、英文两种语言,默认根据Request Header中的Accept-Language值自动选择,如需调整亦可以添加locale cookie进行指定。

签名算法

每次请求都必须加入签名信息作为请求校验。校验参数全部以Query Param参数的方式附加在URL后面,顺序不分先后。

签名过程:
  1. 连接生成签名的原始字符串,需要4个参数,使用 & 连接,无需转码
    valid_string = partner_code&time&nonce_str&credential_code
    参数说明
    • partner_code: 商户编码,由4位大写字母或数字构成
    • time: UTC毫秒时间戳,取当前UTC时间的毫秒数时间戳,Long类型,5分钟内有效
    • nonce_str: 随机字符串(支持数字和字母),无长度限制,请使用URL安全字符(避开&,=等符号),请注意HTTP URL的最大长度限制,建议长度在10到30位
    • credential_code: 系统为商户分配的开发校验码,请妥善保管,不要在公开场合泄露

  2. 使用SHA256进行签名,并转为Hex小写字符串
  3. sign=hex(sha256(valid_string)).toLowerCase()
  4. 在请求中把签名使用的time, nonce_str和生成的sign一同作为Query Param参数发送
  5. valid_string=TestPay&1468691301081&aaf2a94c8c2d56d5b43a1a3d9d811102&pQ5Jc9eoTcsxqPY5uQ3p2WmvSy0zEYeP
    sign=64712672795f94fa3bfb2e88ac09cb75d09bcf8a3c3dcaa529d8290dd6587060

测试地址:


支付成功回调

若订单创建时提供了notify_url,系统会在用户支付成功后向这个地址主动发送支付成功状态推送。推送校验参数会包含在json内,商户系统应该验证校验参数,确定来源正确后再进行后续操作。推送动作最多会重试3次,商户系统应当能够处理收到的重复请求。
注意:商户域名必须绑定ssl证书(https)才能收到异步回调。

返回JSON

字段 类型 描述
time Long UTC时间戳
nonce_str String 随机字符串
sign String 签名, 使用time和nonce_str获得sign, 且验证是否与此sign一致
partner_order_id String 商户订单ID
order_id String AlphaPay 订单ID
total_fee String 订单金额,单位是最小货币单位
real_fee String 支付金额,单位是最小货币单位
rate Double 交易时使用的汇率,1CAD=?CNY
currency String 币种
channel String 支付渠道 Alipay|支付宝、Wechat|微信
create_time String 订单创建时间(最新订单为准)(yyyy-MM-dd HH:mm:ss,加拿大西部时间)
pay_time String 订单支付时间(最新订单为准)(yyyy-MM-dd HH:mm:ss,加拿大西部时间)

回调格式实例


双重保障检验订单支付成功

  1. 被动:当客人支付成功,支付服务器会推送支付成功数据给商户服务器
  2. 主动查询:在跳转界面通过查询订单状态接口来获得订单状态
    • 订单需查询数次以防数据未更新

QR Code - 创建QR Code支付单

QR Code支付单适用于PC端网页/手机浏览器进行支付。电脑会自动生成一个带有消费金额的二维码,消费者使用微信客户端/支付宝客户端扫描二维码后输入支付密码即可支付成功。

接入流程


返回值包括二维码字符串,二维码图片,支付地址,商户可以自行决定直接展示二维码或跳转支付页,跳转支付页需要带上签名信息(详见签名算法)。 货币类型如果是CNY,注意通过汇率转换后不得低于0.01CAD,否则订单可以创建成功,但支付时会报金额不合法错误。

put https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}

Header

字段 描述
Accept application/json
Content-Type application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求同一商户唯一 (最大长度50字符)

JSON字段

字段 类型 描述
description String 必填,订单标题(最大长度128字符,超出自动截取)
price int 必填,金额,单位为货币最小单位,例如使用100表示CAD1.00
currency String 币种代码
默认值: CAD
允许值: CAD , CNY
channel String 支付渠道,大小写敏感
允许值: Alipay , Wechat
notify_url String 支付通知url,详见支付成功回调,不填则不会推送支付通知
operator String 操作人员标识,用于商户系统识别操作人员

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
channel String 支付渠道
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Alpha Pay订单ID,同时也是微信、支付宝订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
code_url String 支付码字符串,商户可以据此自行生产二维码
qrcode_img String Base64封装的二维码图片,可直接作为img的src属性
pay_url String 跳转URL,需加上必要参数才能点击进行支付

错误码

名称 描述
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

发送请求示例

put https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/20180101122549?time=1535753255985&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=a7a706541544bb3552a7dab8dd67d16574bbd1eafb0f7672cdb739710311ef14

返回数据示例


两种方式显示二维码进行支付

  1. 在商户页面生成二维码支付,使用
    • qrcode_img: Base64封装的二维码图片,可直接作为img的src属性
    • code_url: 支付码字符串,商户可以据此自行生产二维码
  2. 跳转至Alpha Pay支付界面,需加上参数才能点击进行支付,详见QR Code支付跳转页

QR Code - 创建QR Code支付跳转页

必须先调用创建QR Code订单接口再进行跳转。建议在用户回调到对应页时通过后台查询订单状态接口确认订单的支付状态。

get https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}/pay

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求已预先创建

Query Params

字段 类型 描述
redirect String 必填,支付成功后跳转页面,详见支付成功回调
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

错误码

名称 描述
ORDER_NOT_EXIST 订单不存在
ORDER_MISMATCH 订单号与商户不匹配
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

链接示例

get https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/2018010112254915/pay?redirect=%22https://www.alphapay.ca/success%22&time=1535759759798&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=d976fd4bfed4d28e96b6c8600507229f666943adc5122937a0f762d3e38b3a7f

Alipay Online Payment - 创建支付宝Web订单

用于PC端支付宝支付,创建订单后跳转到返回的pay_url(需附加签名参数和redirect参数),随后进入支付宝支付页面完成支付 该接口仅现仅支持支付宝。

接入流程


put https://pay.alphapay.ca/api/v1.0/alipay/partners/{partner_code}/orders/{order_id}

Header

字段 描述
Accept application/json
Content-Type application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求同一商户唯一 (最大长度50字符)

JSON字段

字段 类型 描述
description String 必填,订单标题(最大长度128字符,超出自动截取)
price int 必填,金额,单位为货币最小单位,例如使用100表示CAD1.00
currency String 币种代码
默认值: CAD
允许值: CAD , CNY
notify_url String 支付通知url,详见支付成功回调,不填则不会推送支付通知
operator String 操作人员标识,用于商户系统识别操作人员

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Alpha Pay订单ID,同时也是微信、支付宝订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
pay_url String 跳转URL,需加上必要参数才能点击进行支付

错误码

名称 描述
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限

ERROR

名称 描述
return_code Error Code
return_msg Error Description

发送请求示例

put https://pay.alphapay.ca/api/v1.0/alipay/partners/ZZZ6/orders/2018010112258455?time=1535760771439&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=dba59bffd4dba6040ec6cbb80bb34bf0311931b0e0574a0eae78570777868f5e

返回数据示例


跳转至支付宝页面进行支付

pay_url 加上 time, nonce_str, sign 参数
get https://pay.alphapay.ca/api/v1.0/alipay/partners/ZZZ6/orders/2018010112258455/web_pay?time=1535761172065&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=124d2ba7eca94c8adedad84aa3dd892f3558d1aa310bf702945700ecbfe54dfb

JSAPI - 创建JSAPI订单

JSAPI适用于在微信APP或者支付宝APP内打开的网页进行支付,如果用户从公众号进入支付页要求公众号已完成认证。用户下单后跳转至Alpha Pay订单页,并拉起微信或者支付宝内置收银台完成支付

接入流程


返回值包括支付地址,商户应该引导用户跳转支付页,跳转支付页需要带上签名信息; 货币类型如果是CNY,注意通过汇率转换后不得低于0.01CAD,否则订单可以创建成功,但支付时会报金额不合法错误。

put https://pay.alphapay.ca/api/v1.0/jsapi_gateway/partners/{partner_code}/orders/{order_id}

Header

字段 描述
Accept application/json
Content-Type application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求同一商户唯一 (最大长度50字符)

JSON字段

字段 类型 描述
description String 必填,订单标题(最大长度128字符,超出自动截取)
price int 必填,金额,单位为货币最小单位,例如使用100表示CAD1.00
currency String 币种代码
默认值: CAD
允许值: CAD , CNY
channel String 支付渠道,大小写敏感
允许值: Alipay , Wechat
notify_url String 支付通知url,详见支付成功回调,不填则不会推送支付通知
operator String 操作人员标识,用于商户系统识别操作人员

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
channel String 支付渠道
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Alpha Pay订单ID,同时也是微信、支付宝订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
pay_url String 跳转URL,需加上必要参数才能点击进行支付

错误码

名称 描述
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

发送请求示例

put https://pay.alphapay.ca/api/v1.0/jsapi_gateway/partners/ZZZ6/orders/20180101122549?time=1535753255985&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=a7a706541544bb3552a7dab8dd67d16574bbd1eafb0f7672cdb739710311ef14

返回数据示例


进行支付

pay_url需加上参数才能点击进行支付,详见微信JSAPI支付跳转页或者支付宝JSAPI支付跳转页


JSAPI - 微信JSAPI支付跳转页

必须先调用创建JSAPI订单接口再进行跳转,最终URL以下单api返回的pay_url为准。建议在用户回调到对应页时通过后台查询订单状态接口确认订单的支付状态。

get https://pay.alphapay.ca/api/v1.0/wechat_jsapi_gateway/partners/{partner_code}_order_{order_id}

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求已预先创建

Query Params

字段 类型 描述
redirect String 必填,跳转页面 (无论用户是否支付成功,都会跳转到此页面,需要在跳转页面查询订单状态)
directpay Boolean 是否直接支付
默认值: false
允许值: true , false
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

错误码

名称 描述
ORDER_NOT_EXIST 订单不存在
ORDER_MISMATCH 订单号与商户不匹配
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

链接示例

get https://pay.alphapay.ca/api/v1.0/wechat_jsapi_gateway/partners/ZZZ6_order_20180101122585566?redirect=%22https://www.alphapay.ca/success%22&directpay=true&time=1535759759798&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=d976fd4bfed4d28e96b6c8600507229f666943adc5122937a0f762d3e38b3a7f

JSAPI - 支付宝JSAPI支付跳转页

必须先调用创建JSAPI订单接口再进行跳转,最终URL以下单api返回的pay_url为准。建议在用户回调到对应页时通过后台查询订单状态接口确认订单的支付状态。

get https://pay.alphapay.ca/api/v1.0/gateway/alipay/partners/{partner_code}/orders/{order_id}/app_pay

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求已预先创建

Query Params

字段 类型 描述
redirect String 必填,跳转页面 (无论用户是否支付成功,都会跳转到此页面,需要在跳转页面查询订单状态)
directpay Boolean 是否直接支付
默认值: false
允许值: true , false
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

错误码

名称 描述
ORDER_NOT_EXIST 订单不存在
ORDER_MISMATCH 订单号与商户不匹配
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

链接示例

get https://pay.alphapay.ca/api/v1.0/gateway/alipay/partners/ZZZ6/orders/20180101122585566/app_pay?redirect=%22https://www.alphapay.ca/success%22&directpay=true&time=1535759759798&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=d976fd4bfed4d28e96b6c8600507229f666943adc5122937a0f762d3e38b3a7f

MobileH5 - 创建H5支付单

注意:微信支付暂时不支持H5支付
H5支付适用场景为移动端App或者手机自带浏览器进行支付,用户下单后浏览器跳转至支付宝支付页面并自动拉起支付宝客户端完成支付。

接入流程


返回值包括跳转支付地址,跳转支付页需要带上签名信息。 货币类型如果是CNY,注意通过汇率转换后不得低于0.01CAD,否则订单可以创建成功,但支付时会报金额不合法错误。

put https://pay.alphapay.ca/api/v1.0/h5_payment/partners/{partner_code}/orders/{order_id}

Header

字段 描述
Accept application/json
Content-Type application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求同一商户唯一 (最大长度50字符)

JSON字段

字段 类型 描述
description String 必填,订单标题(最大长度128字符,超出自动截取)
price int 必填,金额,单位为货币最小单位,例如使用100表示CAD1.00
currency String 币种代码
默认值: CAD
允许值: CAD , CNY
channel String 支付渠道,大小写敏感
允许值: Alipay
notify_url String 支付通知url,详见支付成功回调,不填则不会推送支付通知
operator String 操作人员标识,用于商户系统识别操作人员

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
channel String 支付渠道
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Alpha Pay订单ID,同时也是微信、支付宝订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
pay_url String 跳转URL,需加上必要参数才能点击进行支付

错误码

名称 描述
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

发送请求示例

put https://pay.alphapay.ca/api/v1.0/h5_payment/partners/ZZZ6/orders/20180905112525?time=1536177012365&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=b180ed81ef2e84f0ed94710d23e47539f8a1af84ed4d8da1961b92abec1be384

返回数据示例


进行支付

pay_url需加上参数才能点击进行支付,详见支付宝H5支付跳转页


MobileH5 - H5支付跳转页

必须先调用创建H5支付订单再进行跳转,最终URL以下单api返回的pay_url为准。建议在用户回调到对应页时通过后台查询订单状态接口确认订单的支付状态。

get https://pay.alphapay.ca/api/v1.0/h5_payment/partners/{partner_code}/orders/{order_id}/pay

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求已预先创建

Query Params

字段 类型 描述
redirect String 必填,跳转页面 (无论用户是否支付成功,都会跳转到此页面,需要在跳转页面查询订单状态)
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

错误码

名称 描述
ORDER_NOT_EXIST 订单不存在
ORDER_MISMATCH 订单号与商户不匹配
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

链接示例

get https://pay.alphapay.ca/api/v1.0/h5_payment/partners/ZZZ6/orders/20180101122585566/pay?redirect=%22https://www.alphapay.ca/success%22&time=1535759759798&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=d976fd4bfed4d28e96b6c8600507229f666943adc5122937a0f762d3e38b3a7f

SDKPayment - 创建SDK订单

用于移动端APP调用微信/支付宝SDK支付,调用API创建订单,得到微信/支付宝SDK调用参数,将参数传递给SDK拉起微信/支付宝支付,并由微信/支付宝客户端直接返回支付结果。 强烈建议获得支付结果后再调用AlphaPay订单查询API确认完成支付后再进行后续流程,避免因超时自动撤单导致资金损失

接入流程


put https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/app_orders/{order_id}

Header

字段 描述
Accept application/json
Content-Type application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求同一商户唯一 (最大长度50字符)

JSON字段

字段 类型 描述
description String 必填,订单标题(最大长度128字符,超出自动截取)
price int 必填,金额,单位为货币最小单位,例如使用100表示CAD1.00
currency String 币种代码
默认值: CAD
允许值: CAD , CNY
channel String 支付渠道,大小写敏感
允许值: Alipay , Wechat
notify_url String 支付通知url,详见支付成功回调,不填则不会推送支付通知
operator String 操作人员标识,用于商户系统识别操作人员
system String 客户端操作系统类型
允许值: android , iphoneipad
version String 客户端版本号
appid String 微信 appid,微信通道要求必填

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Alpha Pay订单ID,同时也是微信、支付宝订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
sdk_params String 调用SDK的参数字符串

错误码

名称 描述
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

发送请求示例

put https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/app_orders/201801011225855451?time=1536086256103&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=836c14b1d1eb6e9ea67c68064e78152cff354e47f5b6907107321d8dde72c65b

返回数据示例



进行支付

获得Sdk_params之后,将参数传递给SDK拉起微信/支付宝支付,并由微信/支付宝客户端直接返回支付结果。 关于客户端和支付宝整合的更多信息: 支付宝SDK文档 支付宝官方实例代码
关于客户端和微信支付整合的更多信息: 微信支付SDK文档微信官方实例代码


Miniprogram_Payment - 创建小程序订单

接入微信小程序需完成海外主体认证,并且认证主体需要与在AlphaPay开通的商户主体一致。具体如何认证请查看微信公众平台相关文档。 用于小程序中发起支付,创建订单后返回小程序支付所需参数,该接口现仅支持微信小程序。 接入参考文档

接入流程


put https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/microapp_orders/{order_id}

Header

字段 描述
Accept application/json
Content-Type application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求同一商户唯一 (最大长度50字符)

JSON字段

字段 类型 描述
description String 必填,订单标题(最大长度128字符,超出自动截取)
price int 必填,金额,单位为货币最小单位,例如使用100表示CAD1.00
currency String 币种代码
默认值: CAD
允许值: CAD , CNY
notify_url String 支付通知url,详见支付成功回调,不填则不会推送支付通知
operator String 操作人员标识,用于商户系统识别操作人员
appid String 小程序 appid
customer_id String 小程序 openid

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Alpha Pay订单ID,同时也是微信订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
sdk_params String 小程序支付所需参数(Json字符串)

错误码

名称 描述
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

发送请求示例

put https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/microapp_orders/201801011225855451?time=1536086256103&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=836c14b1d1eb6e9ea67c68064e78152cff354e47f5b6907107321d8dde72c65b

返回数据示例


进行支付

获得Sdk_params之后,使用参数接入微信小程序的支付,具体接入可参考 接入文档




RetailPay - 创建线下支付订单

线下支付订单接口用于带有扫码设备的收银终端进行对接,商户输入金额后要求客户出示支付码,用扫码枪扫码后将扫码内容和金额一并提交并完成支付操作。 线下支付订单接口现已兼容微信、支付宝通道

接入流程


put https://pay.alphapay.ca/api/v1.0/micropay/partners/{partner_code}/orders/{order_id}

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求同一商户唯一 (最大长度50字符)

JSON字段

字段 类型 描述
description String 必填,订单标题(最大长度128字符,超出自动截取)
price int 必填,金额,单位为货币最小单位,例如使用100表示CAD1.00
currency String 币种代码
默认值: CAD
允许值: CAD , CNY
notify_url String 支付通知url,详见支付成功回调,不填则不会推送支付通知
device_id String 必填,设备ID
auth_code String 必填,扫描用户微信/支付宝客户端得到的支付码

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
result_code String
  • PAYING: 等待支付
  • CREATE_FAIL: 订单创建失败
  • CLOSED: 已关闭
  • PAY_FAIL: 支付失败
  • PAY_SUCCESS: 支付成功
order_id String Alpha Pay订单ID,同时也是微信、支付宝订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
total_fee int 订单金额,单位是货币最小面值单位
real_fee int 实际支付金额,单位是货币最小面值单位(目前等于订单金额,为卡券预留)
input_fee int 输入金额 (不含手续费)
create_time String 订单创建时间(最新订单为准)(yyyy-MM-dd HH:mm:ss,加拿大西部时间)
currency String 币种,通常为CAD
channel String 支付渠道 Alipay|支付宝、Wechat|微信
order_description String 订单描述
customer_id String 微信、支付宝用户ID

错误码

名称 描述
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
AUTHCODEEXPIRE 二维码已过期
NOTENOUGH 余额不足
NOTSUPORTCARD 不支持卡类型
AUTH_CODE_ERROR 二维码被重复提交
AUTH_CODE_INVALID 不是微信支付二维码
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

RetailPay - 创建线下QRCode支付单

线下QRCode支付用于对接无扫码设备的收银终端,下单后得到二维码地址,自行生成二维码图片后展示在收银终端屏幕上,并由用户使用对应支付客户端进行扫码支付。 线下QRCode现已同时兼容支付宝、微信支付客户端进行支付

接入流程


put https://pay.alphapay.ca/api/v1.0/retail_qrcode/partners/{partner_code}/orders/{order_id}

Header

字段 描述
Accept application/json
Content-Type application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求同一商户唯一 (最大长度50字符)

JSON字段

字段 类型 描述
description String 必填,订单标题(最大长度128字符,超出自动截取)
price int 必填,金额,单位为货币最小单位,例如使用100表示CAD1.00
currency String 币种代码
默认值: CAD
允许值: CAD , CNY
notify_url String 支付通知url,详见支付成功回调,不填则不会推送支付通知
device_id String 必填,设备ID
operator String 操作人员标识,用于商户系统识别操作人员

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Alpha Pay订单ID,同时也是微信、支付宝订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
code_url String 支付码字符串,商户可以据此自行生产二维码

错误码

名称 描述
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

CommonApi - 获取当前汇率

获取当前微信CAD兑CNY汇率值(1CAD=?CNY),该汇率仅做参考,以实际成交汇率为准。

get https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/channel_exchange_rate

Header

字段 描述
Accept application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
wechat_rate Double 微信汇率
alipay_retail_rate Double 支付宝线下渠道汇率
alipay_online_rate Double 支付宝线上渠道汇率

错误码

名称 描述
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

发送请求示例

get https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/channel_exchange_rate?time=1536093518031&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=b307328d9b7d72b3341cf6430441125e944e4813e0a3536b2a9a128bf21ed436

返回数据示例



CommonApi - 查询订单状态

查询范围包括QRCode订单、JSAPI订单和线下支付订单。

get https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}

Header

字段 描述
Accept application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
result_code String
  • PAYING: 等待支付
  • CREATE_FAIL: 订单创建失败
  • CLOSED: 已关闭
  • PAY_FAIL: 支付失败
  • PAY_SUCCESS: 支付成功
  • PARTIAL_REFUND: 部分退款
  • FULL_REFUND: 全额退款
如果需要可以用相同订单号再次发起支付单,支付成功或支付中的无法重复发起订单。
order_id String AlphaPay订单ID,同时也是微信、支付宝订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
input_fee int 订单输入金额,不含手续费
total_fee int 订单金额,单位是货币最小面值单位
real_fee int 实际支付金额,单位是货币最小面值单位(目前等于订单金额,为卡券预留)
rate Double 交易时使用的汇率,1CAD=?CNY
pay_time String 支付时间(yyyy-MM-dd HH:mm:ss,加拿大西部时间)
create_time String 订单创建时间(最新订单为准)(yyyy-MM-dd HH:mm:ss,加拿大西部时间)
currency String 币种,通常为CAD
channel String 支付渠道 Alipay|支付宝、Wechat|微信
customer_id String 微信用户id、支付宝用户id

错误码

名称 描述
ORDER_NOT_EXIST 订单不存在
ORDER_MISMATCH 订单号与商户不匹配
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

发送请求示例

get https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/20180101122585566?time=1536093994255&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=07be0e9f9cb017111beb17f93e215ed5a97f5578b8578f1f6c9975bcd0454dac

返回数据示例



CommonApi - 申请退款

一笔支付订单可以分多次退款,退款总金额不得超过实际支付金额,退款币种与支付订单一致。

put https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}/refunds/{refund_id}

Header

字段 描述
Accept application/json
Content-Type application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求同一商户唯一 (最大长度50字符)
refund_id String 必填,商户退款单号(如商户系统没有refund_id, 可与order_id一致)

JSON字段

字段 类型 描述
fee int 必填,退款金额,单位是货币最小单位,单个订单退款单金额总和不能超过用户支付金额(如客人支付手续费:需要检验订单获得real_fee, 退款可同时退手续费)

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
result_code String
  • WAITING: 正在提交
  • CREATE_FAILED: 提交失败
  • SUCCESS: 提交成功
  • FAILED: 退款失败
  • FINISHED: 退款成功
  • CHANGE: 退款无法到账,需要人工介入
refund_id String AlphaPay退款单号
partner_refund_id String 商户提交的退款单号
amount int 退款金额,单位是货币最小单位
currency String 币种, 通常为CAD

错误码

名称 描述
ORDER_NOT_EXIST 订单不存在
ORDER_MISMATCH 订单号与商户不匹配
ORDER_NOT_PAID 订单未支付完成,无法退款
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

CommonApi - 查询退款状态

get https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}/refunds/{refund_id}

Header

字段 描述
Accept application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成
order_id String 必填,商户支付订单号,要求同一商户唯一 (最大长度50字符)
refund_id String 必填,商户退款单号(如商户系统没有refund_id, 可与order_id一致)

Query Params

字段 类型 描述
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

Success 200

字段 类型 描述
return_code String 执行结果
result_code String
  • WAITING: 正在提交
  • CREATE_FAILED: 提交失败
  • SUCCESS: 提交成功
  • FAILED: 退款失败
  • FINISHED: 退款成功
  • CHANGE: 退款无法到账,需要人工介入
refund_id String AlphaPay退款单号
partner_refund_id String 商户提交的退款单号
amount int 退款金额,单位是货币最小单位
currency String 币种, 通常为CAD

错误码

名称 描述
ORDER_NOT_EXIST 订单不存在
ORDER_MISMATCH 订单号与商户不匹配
ORDER_NOT_PAID 订单未支付完成,无法退款
REFUND_NOT_EXIST 退款单不存在
REFUND_MISMATCH 退款单号与支付单不匹配
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

CommonApi - 查看账单

get https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders

Header

字段 描述
Accept application/json
Content-Type application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成

Query Params

字段 类型 描述
date String 订单创建日期,'yyyyMMdd'格式,加拿大西部时间,不填默认查询所有订单
status String 订单状态
  • ALL: 全部订单,包括未完成订单和已关闭订单
  • PAID: 只列出支付过的订单,包括存在退款订单
  • REFUNDED: 只列出存在退款订单
  • 默认值: ALL
    允许值: ALL , PAID, REFUNDED
page int 页码,从1开始计算
默认值: 1
limit int 每页条数
默认值: 10
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

ROOT

字段 类型 描述
return_code String 执行结果
data JSON[] 订单列表
pagination JSON 分页信息
analysis JSON 统计信息

data

字段 类型 描述
order_id String AlphaPay订单ID
partner_order_id String 商户订单ID
total_fee int 订单金额,单位是货币最小单位
real_fee int 订单支付金额,单位是货币最小单位
channel String 支付渠道 Alipay|支付宝、Wechat|微信
currency String 币种
create_time String 格式'yyyy-MM-dd HH:mm:ss',加拿大西部时间,订单创建时间
pay_time String 格式'yyyy-MM-dd HH:mm:ss',加拿大西部时间,支付时间,未支付订单为空
status String 订单状态
  • SUBMITTING: 提交中
  • SUBMIT_FAIL: 提交失败
  • WAITING_PAYMENT: 等待支付
  • CLOSED: 已关闭
  • PAYMENT_FAIL: 支付失败
  • SUCCESS: 支付成功
  • PARTIAL_REFUND: 部分退款
  • FULL_REFUND: 全额退款
order_body String 订单标题
gateway String 订单模式
  • Retail In-Store: AlphaPay 线下支付
  • QRCODE: 商户静态二维码
  • Online API: 网站QRCode API支付
  • WeChat HTML5: JSAPI支付
  • Retail API: 线下API支付
  • Mobile H5: H5 API支付
  • APP: APP SDK支付
  • Miniprogram: 小程序支付
partner_code String 商户编码
partner_name String 商户名称
refund_fee String 当前订单退款金额,货币最小单位

pagination

字段 类型 描述
page int 页码
limit int 每页条数
totalCount int 总条数
totalPages int 总页数

analysis

字段 类型 描述
order_count int 支付成功订单数(包含有退款订单)
total_fee int 成交订单总额,货币最小单位
real_fee int 支付总额,货币最小单位

错误码

名称 描述
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

CommonApi - 查看账单流水

本接口将列出商户当日所有流水,包括所有接口(含非网关接口)支付通道的付款、AlphaPay优惠补贴、退款、 退款失败补正、系统补正、营销账户转入转出等,不含清算信息。
注意一笔付款订单或退款订单均可能对应多条流水记录

get https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/transactions

Header

字段 描述
Accept application/json
Content-Type application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成

Query Params

字段 类型 描述
date String 必填, 账单日期,'yyyyMMdd'格式,加拿大西部时间
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

ROOT

字段 类型 描述
return_code String 执行结果
result_code String 业务执行结果
transaction_count int 流水总条目
order_count int 付款单数
refund_count int 退款单数
transactions JSON[] 流水列表

transactions

字段 类型 描述
transaction_time String 交易时间,格式'yyyy-MM-dd HH:mm:ss',加拿大西部时间
order_id String AlphaPay订单ID
partner_order_id String 商户订单ID
channel_order_id String 渠道方(Alipay/Wechat)订单号
refund_id String AlphaPay退款单ID(仅退款或退款失败补正)
partner_refund_id String 商户系统提交退款ID(仅退款或退款失败补正)
gateway String 下单接口
  1. 线下扫码(扫描客户展示的付款码)
  2. 线下扫码(客户扫描POS展示的二维码)
  3. 商户静态码
  4. QRCode网关
  5. JSAPI网关
  6. 线下网关
  7. 线下网关
  8. 商户静态码
  9. Mobile H5
  10. 第三方网关
  11. APP网关
  12. 账单码
  13. 小程序
  14. 原生二维码
  15. 账单链接
channel String 支付渠道 Alipay|支付宝、Wechat|微信
type String 流水类型
  • Credit: 入账
  • Debit: 出账
currency String 币种
total_amount int 订单总金额,单位是货币最小单位
input_amount int 订单输入金额,单位是货币最小单位
customer_payment_amount int 用户实际支付金额,单位是货币最小单位
settle_amount int 结算金额,币种为CAD,单位是货币最小单位
exchange_rate Double 使用汇率
remark String 备注

错误码

名称 描述
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

CommonApi - 查看清算详情

本接口将列出商户当日所有流水,包括所有接口(含非网关接口)支付通道的付款、AlphaPay优惠补贴、退款、 退款失败补正、系统补正、营销账户转入转出等,不含清算信息。
注意一笔付款订单或退款订单均可能对应多条流水记录

get https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/settlements

Header

字段 描述
Accept application/json
Content-Type application/json

Path Variable

字段 类型 描述
partner_code String 必填,商户编码,由4位大写字母或数字构成

Query Params

字段 类型 描述
date String 必填, 清算日期,'yyyyMMdd'格式,加拿大西部时间
time Long 必填,UTC毫秒时间戳
nonce_str String 必填,随机字符串
sign String 必填,签名(需生成一个新的sign)

ROOT

字段 类型 描述
return_code String 执行结果
result_code String 业务执行结果
settle_from String 订单起始日期,yyyyMMdd
settle_to String 订单截止日期,yyyyMMdd
settle_days String 清算周期(T+n)
transaction_count int 流水总条目
order_count int 付款单数
refund_count int 退款单数
total_credit int 入账总金额(CAD分)
total_debit int 支出总金额(CAD分)
total_surcharge int 手续费总额(CAD分)
total_transfer int 打款总额(CAD分)
transactions JSON[] 流水列表

transactions

字段 类型 描述
transaction_time String 交易时间,格式'yyyy-MM-dd HH:mm:ss',加拿大西部时间
order_id String AlphaPay订单ID
partner_order_id String 商户订单ID
channel_order_id String 渠道方(Alipay/Wechat)订单号
refund_id String AlphaPay退款单ID(仅退款或退款失败补正)
partner_refund_id String 商户系统提交退款ID(仅退款或退款失败补正)
gateway String 下单接口
  1. 线下扫码(扫描客户展示的付款码)
  2. 线下扫码(客户扫描POS展示的二维码)
  3. 商户静态码
  4. QRCode网关
  5. JSAPI网关
  6. 线下网关
  7. 线下网关
  8. 商户静态码
  9. Mobile H5
  10. 第三方网关
  11. APP网关
  12. 账单码
  13. 小程序
  14. 原生二维码
  15. 账单链接
channel String 支付渠道 Alipay|支付宝、Wechat|微信
type String 流水类型
  • Credit: 入账
  • Debit: 出账
currency String 币种
total_amount int 订单总金额,单位是货币最小单位
input_amount int 订单输入金额,单位是货币最小单位
customer_payment_amount int 用户实际支付金额,单位是货币最小单位
settle_amount int 结算金额,币种为CAD,单位是货币最小单位
surcharge_rate String 手续费费率(x%)
surchargee int 手续费金额,单位是CAD分
transfer_amount int 打款金额,单位是CAD分
exchange_rate Double 使用汇率
remark String 备注

错误码

名称 描述
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

ERROR

名称 描述
return_code Error Code
return_msg Error Description

资源下载