Python SDK 使用文档¶

简介¶

目前 Adapay 的 Python SDK 支持的交易模块包括支付（Payment）、退款（Refund）、查询、关单功能，用户对象，结算账户，企业用户等功能，具体可参考 API文档。

SDK 版本记录¶

版本	日期	说明
v1.3.4	2022-04-08	优化代码调用
v1.3.3	2021-08-12	优化代码调用
v1.3.1	2021-03-15	新增服务商分账功能
v1.3.0.2	2020-12-03	增加快捷支付相关功能

版本要求¶

此 SDK 目前只支持 Python3，请确保在 Python3 工程接入。

接入方法¶

安装 SDK

执行 pip install adapay 即可

添加依赖

在当前环境确保已经安装以下版本的依赖库：

fishbase==1.1.15
chardet==3.0.4
pycryptodome==3.8.2
requests==2.22.0

使用方法¶

前提

如未进行商户入驻，或者未配置商户公私钥，可直接使用以下示例代码中提供的配置参数进行开发调试，调试成功后可直接替换自己的配置信息即可

注意： 以下配置信息中API key与APP ID是对应使用的，即APP ID 是本测试商户下的应用

初始化参数

初始化SDK，传入商户配置信息，SDK 内通过字典的形式管理商户的配置信息，所以在下文示例代码中，传入的配置信息字典对应的merchant_key 亦即调用接口时SDK 内部获取商户配置信息的mer_key值，商户端需做好管理维护

# 建议在服务启动时初始化，传入商户入网后获取到的，入网前可使用如下测试商户信息
config_info = {
    'api_key':'api_live_9c14f264-e390-41df-984d-df15a6952031',
    'mock_api_key':'api_test_e640fa26-bbe6-458f-ac44-a71723ee2176',
    'private_key':'MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBAMQhsygJ2pp4nCiDAXiqnZm6AzKSVAh+C0BgGR6QaeXzt0TdSi9VR0OQ7Qqgm92NREB3ofobXvxxT+wImrDNk6R6lnHPMTuJ/bYpm+sx397rPboRAXpV3kalQmbZ3P7oxtEWOQch0zV5B1bgQnTvxcG3REAsdaUjGs9Xvg0iDS2tAgMBAAECgYAqGFmNdF/4234Yq9V7ApOE1Qmupv1mPTdI/9ckWjaAZkilfSFY+2KqO8bEiygo6xMFCyg2t/0xDVjr/gTFgbn4KRPmYucGG+FzTRLH0nVIqnliG5Ekla6a4gwh9syHfstbOpIvJR4DfldicZ5n7MmcrdEwSmMwXrdinFbIS/P1+QJBAOr6NpFtlxVSGzr6haH5FvBWkAsF7BM0CTAUx6UNHb+RCYYQJbk8g3DLp7/vyio5uiusgCc04gehNHX4laqIdl8CQQDVrckvnYy+NLz+K/RfXEJlqayb0WblrZ1upOdoFyUhu4xqK0BswOh61xjZeS+38R8bOpnYRbLf7eoqb7vGpZ9zAkEAobhdsA99yRW+WgQrzsNxry3Ua1HDHaBVpnrWwNjbHYpDxLn+TJPCXvI7XNU7DX63i/FoLhOucNPZGExjLYBH/wJATHNZQAgGiycjV20yicvgla8XasiJIDP119h4Uu21A1Su8G15J2/9vbWn1mddg1pp3rwgvxhw312oInbHoFMxsQJBAJlyDDu6x05MeZ2nMor8gIokxq2c3+cnm4GYWZgboNgq/BknbIbOMBMoe8dJFj+ji3YNTvi1MSTDdSDqJuN/qS0='
}
adapay.mer_config = {
    'merchant_key':config_info  # merchant1为对应商户配置key 值，调用接口时需传入
}

支付对象¶

发起支付¶

当您想发起一次支付请求时需要通过 Adapay 提供的创建方法获取一个新的 Payment对象，您可使用此 Payment对象发起支付。对于支付结果，Adapay 会发送异步消息告知。

调用示例

response = adapay.Payment.create(
   order_no='1234567890',
   app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',
   pay_channel='alipay',
   pay_amt='100.00',
   goods_title='goods_title',
   goods_desc='goods_desc',
   mer_key='merchant1'
)

参数说明

调用参数详见创建支付

支付订单查询¶

查询已存在的 Payment对象

调用示例

response = adapay.Payment.query(payment_id='payment_id',mer_key='merchant1')

参数说明

调用参数详见支付查询。

关闭订单¶

针对已经创建的 Payment对象，您可以调用关闭订单接口进行交易的关闭。

调用示例

response = adapay.Payment.close(
   payment_id='payment_id',
   reason='reason',
   expend='expend',
   notify_url='notify_url',
   mer_key='merchant1'
   )

参数说明

调用参数详见关单。

查询支付对象列表¶

通过该接口，实现对已发起的支付对象查询功能，支持使用请求订单号、支付对象id、以及按时间范围分页查询。

调用示例

response = adapay.Payment.list(
   payment_id='payment_id',
   app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
   page_index='page_index',
   page_size='page_size',
   created_gte='created_gte',
   created_lte='created_lte',
   mer_key='merchant1'
   )

参数说明

调用参数详见支付对象列表查询。

退款对象¶

发起退款¶

当您的业务需要发起退款时，可通过 Adapay 系统提供的创建 Refund对象方法创建一个退款对象，发起退款请求。

response = adapay.Refund.create(
   id='payment_id',    # payment_id 或 payment_confirm_id
   refund_order_no='refund_order_no',
   refund_amt='100.00',
   mer_key='merchant1'
)

参数说明

调用参数详见创建退款。

退款订单查询¶

通过 Refund对象的 id 查询一个已创建的退款记录。

response = adapay.Refund.query(payment_id='payment_id',mer_key='merchant1')

参数说明

调用参数详见退款查询。

支付确认对象¶

创建支付确认对象¶

创建支付确认对象

调用示例

response = adapay.PaymentConfirm.create(
   payment_id='payment_id',
   order_no='order_no',
   confirm_amt='confirm_amt',mer_key='merchant1')

参数说明

调用参数详见创建支付确认对象。

查询支付确认对象¶

查询支付确认对象

调用示例

response = adapay.PaymentConfirm.query(payment_confirm_id='payment_confirm_id',mer_key='merchant1')

参数说明

调用参数详见查询支付确认对象。

查询支付确认对象列表¶

查询支付确认对象列表

调用示例

response = adapay.PaymentConfirm.list(app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,mer_key='merchant1')

参数说明

调用参数详见查询支付确认对象列表

支付撤销对象¶

创建支付撤销¶

撤销延时交易

调用示例

response = adapay.PaymentReverse.create(
    payment_id='payment_id',
    app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
    order_no='order_no',
    reverse_amt='reverse_amt',mer_key='merchant1')

参数说明

调用参数详见创建支付撤销对象。

查询支付撤销对象¶

查询撤销延时订单

调用示例

response = adapay.PaymentReverse.query(reverse_id='reverse_id',mer_key='merchant1')

参数说明

调用参数详见查询支付撤销对象。

查询支付撤销对象列表¶

查询撤销延时订单列表

调用示例

response = adapay.PaymentReverse.list(app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,mer_key='merchant1')

参数说明

调用参数详见查询支付撤销对象列表。

个人用户对象¶

创建用户对象¶

调用示例

response = adapay.Member.create(
   app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
   member_id='member_id',mer_key='merchant1')

参数说明

调用参数详见创建用户对象

查询用户对象¶

调用示例

response = adapay.Member.query(
   app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
   member_id='member_id',mer_key='merchant1')

参数说明

调用参数详见查询用户对象

查询用户对象列表¶

调用示例

response =  adapay.Member.list(app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,mer_key='merchant1')

参数说明

调用参数详见查询用户对象列表

更新用户对象¶

更新用户信息时采取的时全量更新模式，即当只更新一个字段时，其他字段需要传入原值；如果只传期望更新的字段，则其他字段会被替换为空值。

调用示例

response = adapay.Member.update(
   app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
   member_id='member_id',
   location='new_address',
   email='new_e_address@adapay.com',
   tel_no='new_mobile_phone_num',
   nickname='new_name',mer_key='merchant1')

参数说明

调用参数详见更新用户对象

企业用户对象¶

创建企业用户对象¶

通过本接口您可以创建企业用户，企业用户需要人工审核，审核完成后会发送异步消息通知，若审核成功，则商户用户 member_id 与 Adapay 系统关联成功，若审核失败，则可再次调用本接口提交正确的资料信息。

调用示例

response = adapay.CorpMember.create(
   app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
   order_no='order_no',
   member_id='corp_member_id',
   name='测试企业1',
   prov_code='prov_code',
   area_code='area_code',
   social_credit_code='social_credit_code',
   social_credit_code_expires='20200101',
   legal_person='frname',
   legal_certId='1234567890',
   legal_mp='13333333333',
   address='企业地址测试',
   attach_file='file_path',
   bank_acct_type='1',mer_key='merchant1'
)

参数说明

调用参数详见创建企业用户对象。

查询企业用户对象¶

调用示例

response = adapay.CorpMember.query(
   app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
   member_id='member_id',mer_key='merchant1')

参数说明

调用参数详见查询企业用户对象

结算账户对象¶

创建结算账户对象¶

创建结算账户时请保证传入的 member_id 已经存在。

调用示例

response =  adapay.SettleAccount.create(
    app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
    member_id='member_id',
    channel='bank_account',
    account_info={
        'card_id': 'card_id',
        'card_name': '测试账户',
        'cert_id': 'id_card_num',
        'cert_type': '00',
        'tel_no': '18888888888',
        'bank_code': '03060000',
        'bank_acct_type': '1',
        'prov_code': '0031',
        'area_code': '3100',mer_key='merchant1'
    })

参数说明

调用参数详见创建结算账户对象

查询结算账户对象¶

创建结算账户时请保证传入的 member_id 已经存在。

调用示例

response = adapay.SettleAccount.query(
   app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
   member_id='member_id',
   # 创建结算账户返回中的id
   settle_account_id='settle_account_id',mer_key='merchant1')

参数说明

调用参数详见查询结算账户对象

修改结算账户¶

修改账户结算时的金额配置

调用示例

response = adapay.SettleAccount.update(
     app_id=app_id,
     member_id=member_id,
     settle_account_id=settle_account_id,
     min_amt=min_amt,
     remained_amt=remained_amt,
     channel_remark=channel_remark,mer_key='merchant1')

参数说明

调用参数详见修改结算配置

删除结算账户对象¶

调用示例

response = adapay.SettleAccount.delete(
   app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
   member_id='member_id',
   settle_account_id='settle_account_id',mer_key='merchant1')

参数说明

调用参数详见删除结算账户对象

查询结算明细列表¶

使用 Adapay 系统生成的结算账户对象 id 查询已创建的结算账户对象信息。

调用示例

response = adapay.SettleAccount.query_details(
     app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
     member_id='member_id',
     begin_date='begin_date',
     settle_account_id='settle_account_id',
     end_date='end_date',mer_key='merchant1')

参数说明

调用参数详见查询结算明细列表

查询账户余额¶

通过本接口查询账户余额

调用示例

balance_query = adapay.SettleAccount.query_balance(app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
                                           member_id='member_id',
                                           settle_account_id='settle_account_id',mer_key='merchant1')

请求参数

调用参数详见查询账户余额

取现对象¶

创建取现对象¶

通过该接口，实现对指定商户或者商户下用户的结算账户可用余额发起主动提现操作，金额从账户中提到绑定的结算银行卡中。取现结果以异步通知为准。

调用示例

draw_result = adapay.Drawcash.create(order_no='order_no',
                                     app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
                                     cash_type='T1',
                                     cash_amt='0.02',
                                     member_id='member_id',
                                     notify_url='https ://www.xxxx.com',mer_key='merchant1')

请求参数

调用参数详见钱包取现

取现查询¶

通过该接口，可以查询已发起的取现交易状态。

调用示例

# -------------取现状态查询-------------
result = adapay.Drawcash.query(order_no='order_no',mer_key='merchant1')

请求参数

调用参数详见取现查询

钱包账户对象¶

创建钱包账户支付对象¶

通过该接口，实现对商户钱包支付功能，下单成功返回支付跳转地址

调用示例

pay_result = adapay.Account.payment(app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
                           order_no=str(int(time.time())),
                           pay_amt='0.01',
                           goods_title='测试商品',
                           goods_desc='测试商品描述',
                           callback_url='https://www.xxxxx.com',mer_key='merchant1')

请求参数

调用参数详见钱包支付

收银台对象¶

创建收银台对象¶

通过该接口，实现对商户钱包收银台支付功能，下单成功返回支付跳转地址

调用示例

# ---------------创建收银台对象-----------------
result = adapay.Checkout.create(order_no='order_no',
                                app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
                                member_id='member_id',
                                pay_amt='0.01',
                                currency='cny',
                                goods_title='测试商品',
                                goods_desc='测试商品描述',
                                callback_url='https://www.xxxxx.com',mer_key='merchant1')

请求参数

调用参数详见钱包收银台支付

查询收银台对象列表¶

通过该接口，实现对商户钱包收银台对象查询功能，支持使用请求订单号、商户下用户id、以及按时间范围分页查询

调用示例

result = adapay.Checkout.list(
        'app_id'= 'app_id',
        'order_no'= 'order_no',
        'page_index'= 'page_index',
        'page_size'='page_size',
        'member_id'= 'member_id',
        'created_gte'= 'created_gte',
        'created_lte'= 'created_lte',
mer_key='merchant1'
)

请求参数

调用参数详见钱包收银台对象列表查询

钱包¶

钱包登录¶

通过该接口，实现对商户登录钱包功能，登录成功返回跳转地址

调用示例

login_result = adapay.Wallet.login(app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
                               member_id='0',
                               ip='127.0.0.1', mer_key='merchant1')

请求参数

调用参数详见钱包登录

转账对象¶

创建账户转账对象¶

创建账户转账对象仅支持同一商户下的用户与用户、用户与商户之间的转账。

调用示例

transfer_result = adapay.Transfer.create(app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
                               order_no='order_no',
                               trans_amt='trans_amt',
                               out_member_id='out_member_id',
                               in_member_id='in_member_id',
                               mer_key='merchant1')

请求参数

调用参数详见创建账户转账对象

查询账户转账对象列表¶

可以基于时间范围进行查询，也可以使用原转账对象的订单号和状态进行查询。

调用示例

transfer_result = adapay.Transfer.list(app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
                               order_no='order_no',
                               status='status',
                               page_index='page_index',
                               page_size='page_size',
                               created_gte='created_gte',
                               created_lte='created_lte',
                               mer_key='merchant1')

请求参数

调用参数详见查询转账对象列表

账户冻结对象¶

创建账户冻结对象¶

调用示例

freeze_result = adapay.FreezeAccount.create(app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
                               order_no='order_no',
                               trans_amt='trans_amt',
                               member_id='member_id',
                               mer_key='merchant1')

请求参数

调用参数详见账户冻结对象

查询账户冻结对象列表¶

调用示例

freeze_result = adapay.FreezeAccount.list(app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
                               order_no='order_no',
                               status='status',
                               page_index='page_index',
                               page_size='page_size',
                               created_gte='created_gte',
                               created_lte='created_lte',
                               mer_key='merchant1')

请求参数

调用参数详见查询账户冻结对象列表

账户解冻对象¶

创建账户解冻对象¶

调用示例

result = adapay.UnFreezeAccount.create(
                            app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',
                            account_freeze_id='s12313',
                            order_no='11212123',
                            mer_key='merchant1'
                            )

请求参数

调用参数详见创建账户解冻对象

查询账户解冻对象列表¶

调用示例

result = adapay.UnFreezeAccount.list(
                            app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',
                            status='s',
                            page_index='1',
                            page_size='10',
                            created_gte='',
                            created_lte='',
                            mer_key='merchant1'
                            )

请求参数

调用参数详见查询账户解冻对象列表

快捷支付¶

创建快捷绑卡¶

个人用户使用快捷支付前，对个人用户的银行卡进行验证。该功能实现对用户银行卡进行四要素验证，验证成功后，会向用户银行卡对应的预留手机号发送短信验证码。

调用示例

result = adapay.FastPay.card_bind(
                            app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',
                            member_id ='member_id',
                            card_id='6323567898765678',
                            tel_no='13111111111',
                            vip_code='321',
                            expiration='0225',
                            mer_key='merchant1'
                            )

参数说明

调用参数详见创建快捷绑卡申请

创建快捷绑卡确认¶

快捷绑卡申请成功后，用户输入收到的短信验证码进行短信验证，若验证成功，Adapay会返回快捷卡唯一标识token_no。若同步返回pending状态时，Adapay会发送异步消息通知告知。

调用示例

result = adapay.FastPay.card_bind_confirm(
                            apply_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',
                            sms_code ='123456',
                            notify_url='https://wwww.xxx.com',
                            mer_key='merchant1'
                            )

参数说明

调用参数详见创建快捷绑卡确认

查询快捷卡对象列表¶

查询已绑定的快捷银行卡列表。

调用示例

result = adapay.FastPay.card_bind_list(
                            app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',
                            member_id ='member_id',
                            token_no='fasdfasdfsd',
                            mer_key='merchant1'
                            )

参数说明

调用参数详见查询快捷卡对象列表

创建快捷支付确认¶

当创建支付对象中 pay_channel 为 fast_pay 时，Adapay 会向用户已绑定快捷卡对应的预留手机号发送短信验证码，需要通过该功能输入用户收到的短信验证码进行验证。验证结果，Adapay 会发送异步消息通知告知。

调用示例

result = adapay.FastPay.confirm(
                            app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',
                            sms_code ='member_id',
                            payment_id='002112020012010545810065165317376983040',
                            mer_key='merchant1'
                            )

参数说明

调用参数详见创建快捷支付确认

创建快捷支付短信重发¶

查询已绑定的快捷银行卡列表。

调用示例

result = adapay.FastPay.sms_code(
                            payment_id ='002112020012010545810065165317376983040',
                            mer_key='merchant1'
                            )

参数说明

调用参数详见创建快捷支付短信重发

服务商分账对象¶

创建服务商分账对象¶

调用示例

result = adapay.SettleAccount.create_commissions_settle(order_no='1579163031383',
                                                    payment_id='002112020111717230410174704123849117696',
                                                    trans_amt='0.01',
                                                    mer_key='merchant1')

参数说明

调用参数详见创建服务商分账对象

查询服务商分账对象列表¶

调用示例

result = adapay.SettleAccount.list_commissions_settle(app_id='app_XXXXXXXX',
                                                  status='succeeded',
                                                  page_index='1',
                                                  page_size='10',
                                                  created_gte='1571466657929',
                                                  created_lte='1571898657929',
                                                  mer_key='merchant1');

参数说明

调用参数详见查询服务商分账对象列表

工具类¶

下载对账单¶

您可通过本接口下载您交易日期的对账单。比如掉单、系统错误等导致商户侧和 Adapay 侧数据不一致，通过对账单核对后可校正支付状态。

调用示例

response = adapay.AdapayTools.download_bill(bill_date='20190905',mer_key='merchant1')

请求参数

参数	类型	描述
bill_date	String(8)	对账单的日期，格式：20180808

返回参数

参数	类型	描述
bill_download_url	String(8)	对账单文件下载 url

获取云闪付用户标识¶

通过本接口获取银联云闪付用户标识

调用示例

user_identity = adapay.AdapayTools.union_user_id(order_no=str(int(time.time())),
                                               app_id='app_7d87c043-aae3-4357-9b2c-269349a980d6',,
                                               user_auth_code='user_auth_code',
                                               app_up_identifier='app_up_identifier',mer_key='merchant1')

请求参数

调用参数详见获取银联云闪付用户标识

验签方法¶

通过此方法，商户可对 HTTP 回调参数进行签名验证。

调用示例

let result = adapay.AdapayTools.verify_sign(data, sign)

通用方法¶

通过此方法，商户可通过此方法调用 Adapay接口服务，省去加签验签逻辑

调用示例

let result = adapay.request_post(url="adapay_url",request_params=params, files='file_path')
let result = adapay.request_get(url="adapay_url",request_params=params)