Payssion介绍

Payssion使用流程

1. 注册开通账户

单击注册开通账户 验证邮箱

2. 登陆后添加应用

登录后单击左边应用，然后添加应用。应用创建成功后后我们会安排审核并在1-3个工作日通知你。如果收到通知应用已经激活，打开应用后即可看到接入所需的参数，包括api_key和secret_key.

3. 技术接入

技术接入分三种形式：

1) FORM表单

网站接入可以采用此种方式，接入形式比WEB API简单，容易上手。

2) WEB API

网站以及手机app可以使用此种方式。

3) Plugins插件

目前支持opencart, Prestashop, WooCommerce, zencart, magento, ECSHOP插件。

4) Mobile SDK

目前支持android平台。

4. 调试上线

调试主要分两个步骤：

1) 创建订单测试

编码接入完成后即可自行测试创建交易，如果创建失败可以看到相应的错误提示。

2) 支付通知测试

订单的最终支付状态以Payssion的后台通知为准。当订单支付状态发生变化时，Payssion后台会自动通知商户提供的Notify Url(具体见应用设置)。 在测试后台通知前，商户需要提前完成支付通知的处理（包括签名验证），之后可联系Payssion技术进行支付通知测试。

支付集成

Form表单集成

线上环境请将网址改为 https://www.payssion.com/payment/create.html。其中api_sig的生成规则请参考签名规则中的Direct Api创建交易签名。

测试环境Form代码示例：

<form name="payssion_payment" action="http://sandbox.payssion.com/payment/create.html" method="post">
    <input type="hidden" name="api_key" value="5963a4c1c35c2a8e">
    <input type="hidden" name="api_sig" value="d6229c11afb870e5e1551d6c45f5c2ab">
    <input type="hidden" name="pm_id" value="alipay_cn">
    <input type="hidden" name="order_id" value="123">
    <input type="hidden" name="description" value="Charge for test">
    <input type="hidden" name="amount" value="1.00">
    <input type="hidden" name="currency" value="USD">
    <input type="hidden" name="return_url" value="http://sandbox.payssion.com/demo/afterpayment">
    <input type ="submit" value ="Submit">
</form>

FORM支付流程如下：

1、构造请求数据

商户根据Payssion提供的接口规则，准备需要传输的数据以及通过程序生成的签名。

2、提交form表单

将1中构造的数据通过http form表单提交方式传递给Payssion。

3、校验数据，创建交易

Payssion根据商户传来的数据校验商户的信息以及签名。

4、跳转到支付页面

Payssion根据商户传来的支付方式信息跳转到相应的支付页面。

5、用户完成支付

用户输入相关支付信息完成支付。

6、通知支付状态信息

第三方支付将该笔订单的支付状态信息通知Payssion。

7、异步通知支付状态信息

Payssion回调商户的notify_url，并通过post方式将订单信息（包含支付状态）传递给商户。

8、更新订单状态

商户根据Payssion传来的订单状态信息更新本地的订单状态。

9、同步跳转到Payssion页面

用户完成支付后页面发生跳转到Payssion页面。

10、同步跳转到商户页面

在9后会跳转到商户指定的return_url页面。

API Libraries

PHP

下载链接：PHP Library

在PHP Library的samples目录下包含了创建交易以及支付异步通知的代码示例。

Shopping Cart购物车系统

Payssion目前已针对主流开源shopping cart开发了相应的插件：

opencart

下载链接：

opencart 3.x plugin

opencart 2.3 plugin

opencart 2.0-2.2 plugin

opencart 1.5.x plugin

opencart 1.4.8-1.4.9 plugin

Prestashop

下载链接：Prestashop plugin

WooCommerce

请打开需要使用的支付方式即可，不要尝试打开payssion这个支付方式（仅用于设置接入参数）

下载链接：WooCommerce plugin

Zencart

下载链接：Zencart plugin

Magento

下载链接： Magento plugin

Magento2.0.x plugin

Magento2.3-2.4 plugin

shoplazza

shoplazza接入指导

WHMCS

下载链接：WHMCS gateway

ECSHOP

下载链接：ECSHOP plugin

HostBill

下载链接：HostBill plugin

Shopify

shoppify一共分三个步骤：1.创建app，2.添加Payssion支付方式，3.脚本配置。需要注意每个步骤都不能少。

另外需要注意用户下单选择payssion的支付方式后该交易就会记录在shopify后台orders中并显示为pending状态（未付款），等客户付款后order的状态会更新为paid。

1. 创建app

在你的shopify后台找到Settings » Apps and sales channels。 1) 依次单击Develop apps，Create app，输入app名称Paysion，选择你的邮箱；

2）单击Configure Admin API scopes，勾选Orders的write_orders和read_orders权限，单击install app；

3）单击Reveal token once，拷贝复制Admin API access token（注意该页面只有第一次打开可以复制）

4）打开https://shopify.payssion.com/install，填写如下参数后单击Submit。

• shopify店铺域名shopify domain
• 上面第三步shopify app的Admin API access token
• Payssion账户里app的API Key和Secret Key（注意这里不是shopify app的）
• pending订单关闭选项（用户下单选择payssion的支付方式后该交易就会记录在shopify后台orders中并显示为pending状态（未付款），如果你选择自动关闭pending订单，系统会自动cancel超过时间限制未付款的pending订单）

2. 添加Payssion支付方式

在你的shopify后台找到Settings » Payments，在Manual payment methods区域选择Create custom payment method，然后在Name of the custom payment method中输入支付方式名称＋ via Payssion（例如Alipay via Payssion），注意必须以via Payssion结尾。

如果你需要添加klarna支付方式，需要找到Settings » Checkout的Form options，然后勾选Full name的Require first and last name和Shipping address phone number的Require。

3.脚本配置

在shopify后台的左下角菜单中，找到Settings » Checkout » Order status page（订单状态页面）

在Order status page中追加（不要覆盖原有代码）以下代码：

邮件通知配置（可选）

当用户下单后shopify会自动发送邮件提醒给客户邮箱（即使客户没有付款），建议修改邮件通知模板以避免误解。在你的shopify后台找到Settings » Notifications » Order confirmation，在底部找到以下代码（店铺语言不同看到的文字会不同。下面以英文为例，其他语言可以自行调整）

{% capture email_title %}Thank you for your purchase! {% endcapture %}
  {% capture email_body %}
  //这里省略部分原有代码
  {% endif %}
{% endcapture %}

替换为下面：

{% if financial_status == "pending" %}
  {% capture email_title %}Pending order reminder {% endcapture %}
  {% capture email_body %}
    {% if requires_shipping %}
      Hi {{ customer.first_name }}, we have not yet received payment for the order 
{{ order_name }} and wanted to check you have all information about the product to complete the order. You can ignore this email if you have already paid. 
    {% endif %}
  {% endcapture %}
{% else %}
  {% capture email_title %}Thank you for your purchase! {% endcapture %}
  {% capture email_body %}
    //这里省略部分原有代码
  {% endcapture %}
{% endif %}

注意上面的替换只是替换通知内容的顶部一小部分，并非全部替换。另外替换后你可能需要根据店铺的语言将其中的文字调整成对应的文字。

purchase事件跟踪（可选）

如果需要对shopify交易添加purchase事件跟踪，请在上面第三步的脚本中添加以下脚本。需要注意只能跟踪到用户付款成功并返回的情况，如果用户付款成功但没有返回则无法跟踪到。另外非即时确认的支付方式（比如巴西现金支付boleto）需要在线下或其他应用中完成付款不存在返回的情况，也无法跟踪。由此可能导致Facebook Pixel的数据和实际付款成功的数据有差别。

Facebook Pixel可以参考如下（需将下面脚本中的fb_pixel_id=XXX中的XXX替换为你的pixel id）：

<!-- Facebook Pixel Code -->
<script>
            !function(f,b,e,v,n,t,s)
            {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
                    n.callMethod.apply(n,arguments):n.queue.push(arguments)};
                if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
                n.queue=[];t=b.createElement(e);t.async=!0;
                t.src=v;s=b.getElementsByTagName(e)[0];
                s.parentNode.insertBefore(t,s)}(window, document,'script',
                    'https://connect.facebook.net/en_US/fbevents.js');

if ('paid' == '{{ order.financial_status }}') {
    fbq('init', 'your_fb_pixel_id');
    fbq('track', 'Purchase', {
        value: {{ checkout.subtotal_price | divided_by: 100.0 }},
        currency: '{{ currency }}'
         }, {eventID: '{{ order_number }}'});
}
</script>

GA可以参考如下（需要另外初始化Google tag）:

<script>
if ('paid' == '{{ order.financial_status }}') {
    gtag("event", "purchase", {
        transaction_id: "{{ order_number }}",
        value: {{ checkout.subtotal_price | divided_by: 100.0 }},
        currency: "{{ currency }}"
    });
}
</script>

Mobile SDK

Android SDK

下载链接：Android SDK

将libs下的PayssionSDK.jar拷贝到项目libs下，同时在AndroidManifest.xml文件中增加以下permission：

<uses-permission android:name="android.permission.INTERNET" />

下面以MainActivity为例，对创建支付请求以及支付结果返回的处理做说明：

创建支付请求

Intent intent = new Intent(MainActivity.this, PayssionActivity.class);
intent.putExtra(PayssionActivity.ACTION_REQUEST, 
        new PayRequest()
        .setAPIKey("5963a4c1c35c2a8e") //Payssion帐户API Key
        .setAmount(amount) //订单金额
        .setCurrency(currency) //货币
        .setPMId(pm_id) //支付方式id
        .setDescription("test") //订单说明
        .setPayerEmail(payer_email) //付款人人邮箱
        .setPayerName(payer_name)); //付款人姓名
MainActivity.this.startActivityForResult(intent, 0);

支付结果返回

订单支付结果以Payssion服务器通知为准，当订单支付状态发生变化时Payssion服务器会自动通知到notify_url (应用设置时需要填写)。

重写MainActivity的onActivityResult方法：

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        Log.v(this.getClass().getSimpleName(), "onActivityResult");
        switch (resultCode) {
        case RESULT_OK:
        case PayssionActivity.RESULT_PENDING:
            if (null != data) {
                PayResponse response = (PayResponse)data.getSerializableExtra(PayssionActivity.RESULT_DATA);
                if (null != response) {
                    //去服务端查询该笔订单状态，注意订单状态以服务端为准
                } else {
                    //should never go here
                }
            }
            break;
        case PayssionActivity.RESULT_CANCELED:
            //用户取消支付
            break;
        case PayssionActivity.RESULT_ERROR:
            //支付发生错误
            if (null != data) {
                //获取错误信息描述
                String des = data.getStringExtra(PayssionActivity.RESULT_DESCRIPTION);
                Log.v(this.getClass().getSimpleName(), "RESULT_ERROR" + des);   
            }
            break;
        }
        super.onActivityResult(requestCode, resultCode, data);
    }

Hosted Payment Page收款单页

线上环境请将网址改为 https://www.payssion.com/checkout/your_api_key，注意需将your_api_key替换成你应用的api_key。 api_sig的生成规则请参考签名规则中的Hosted Payment Page创建交易签名。

Code example in sandbox environment:

<form name="payssion_payment" action="http://sandbox.payssion.com/checkout/5f522cee9d2e995e" method="post">
    <input type="hidden" name="api_sig" value="27a0309a01ed380e2c7fb9c6d383ff0a">
    <input type="hidden" name="order_id" value="123">
    <input type="hidden" name="description" value="Charge for test">
    <input type="hidden" name="amount" value="1.00">
    <input type="hidden" name="currency" value="USD">
    <input type="hidden" name="return_url" value="http://sandbox.payssion.com/demo/afterpayment">
    <input type="submit" class="button" value="click here to try this hosted page demo">
</form>

Sandbox Testing测试环境测试

测试环境仅支持使用payssion_test作为pm_id的测试。在测试之前，需要在测试环境sandbox另外注册进行测试.

支付测试

1. 使用payssion_test作为pm_id创建支付。

2. 选择 Mark as Completed(支付成功)，或者其他支付状态.

3. 检查你的return_url和notify_url收到的参数，并检验签名以及金额是否正确，订单状态是否更新为对应的状态.

API Reference

API请求可以通过Postman来模拟

Payment Request 创建交易

线上环境地址：

FORM表单地址为：https://www.payssion.com/payment/create.html

WEB服务API地址为：https://www.payssion.com/api/v1/payment/create

测试环境地址：

FORM表单地址为：http://sandbox.payssion.com/payment/create.html

WEB服务API地址为：http://sandbox.payssion.com/api/v1/payment/create

FORM表单或者WEB服务API创建交易时所有参数通过key-value POST形式提交。

{
    "api_key": "5963a4c1c35c2a8e",
    "pm_id": "alipay_cn",
    "amount": "1.00",
    "currency": "USD",
    "order_id": "123",
    "description": "test charge",
    "api_sig":"d6229c11afb870e5e1551d6c45f5c2ab"
}

创建交易响应

当数据请求到WEB服务API地址时，响应为json格式。当数据以FORM表单形式提交到FORM表单地址时，payssion会自动跳转到付款链接redirect_url。 以下以WEB服务API响应参数说明(json格式)

{
    "redirect_url": "http:\/\/sandbox.payssion.com\/pay\/H427753617644653",
    "transaction": {
        "transaction_id": "H427753617644653",
        "state": "pending",
        "amount": "1.00",
        "currency": "USD",
        "pm_id": "alipay_cn",
        "pm_name": "Alipay",
        "order_id": "123"
    },
    "result_code": 200
}

transaction

交易信息，主要字段有： transaction_id：Payssion平台交易号
State：交易状态
amount：交易金额
currency：交易币种
amount_local：用户需支付的本地货币金额
currency_local：用户需支付的本地货币
order_id：商家订单号
注意：amount_local和currency_local为可选字段，只有在创建交易时的币种和用户实际支付的币种不一致时才会返回

Payment Details 交易查询

线上环境地址：

交易查询API地址为：https://www.payssion.com/api/v1/payment/getDetail

测试环境地址：

交易查询API地址为：http://sandbox.payssion.com/api/v1/payment/getDetail

所有参数通过key-value POST形式提交：

交易查询API响应参数说明(json格式)

响应示例：

{
    "transaction":
    {
        "transaction_id":"F203853752614827",
        "app_name":"demo",
        "pm_id":"openbucks",
        "currency":"USD",
        "order_id":"",
        "amount":"1.00",
        "paid":"0.00",
        "net":"0.00",
        "state":"pending",
        "fee":"0.00",
        "refund":"0.00",
        "refund_fee":"0.00",
        "created":1422985375,
        "updated":1422985375
    },
    "result_code":200
}

transaction

交易信息，主要字段有： transaction_id：Payssion平台交易号
app_name：应用名称
pm_id：支付方式id，请联系Payssion技术索取pm_id
currency：交易币种
order_id：商家订单号
amount：订单金额
paid：已支付金额
net：扣除手续费后的净额
state：支付状态。详细支付状态请参考
fee：费用
refund：已退款金额
refund_fee：退款费用
created：交易创建时间
updated：交易更新时间

Refund Request 退款请求

You must submit the data to the following URLs:

线上环境地址：

退款API地址为： https://www.payssion.com/api/v1/refunds

测试环境地址：

退款API地址为： http://sandbox.payssion.com/api/v1/refunds

所有参数通过key-value POST形式提交：

$ curl http://sandbox.payssion.com/api/v1/refunds \
   -d api_key=5f522cee9d2e995e \
   -d api_sig=193b1f3586f0b705820eae9a787ea2ec \
   -d transaction_id=I821474164059947 \
   -d amount=0.01 \
   -d currency=USD

退款API响应参数说明(json格式)

响应示例：

{
    "refund": {
        "transaction_id": "H427753617644653",
        "original_transaction_id": "I821474164059947",
        "state": "refund_pending",
        "amount": "0.01",
        "currency": "USD",
        "created": 1534905882,
        "updated": "1534905882"
    },
    "result_code": 200
}

Notifications 支付结果通知

页面跳转同步通知

Return URL仅作返回跳转使用，仅回传transaction_id和order_id。具体支付状态更新请依赖 Notify URL的异步回调，我们会在支付状态发生变化后第一时间通过Notify URL回调通知商户（正常情况下Notify URL的回调回发生在Return URL之前）。

1、买家在付款后（可能付款失败）跳转回商户指定的同步通知页面(参数return_url)，Payssion会在商户的同步通知页面后面添加如下参数：

transaction_id
order_id

2、该页面中获得参数的方式，需要使用GET方式获取，如request.QueryString(“order_id”)。

服务器异步通知

1、交易创建后的默认状态pending，正常情况下只有当支付状态发生变化时（也就说状态变成非pending时），Payssion会主动回调商户的通知页面Notify URL。 主要参数如下：

{
   "app_name":"your app name",
   "pm_id":"alipay_cn",
   "transaction_id":"P205928236362773",
   "order_id":"123",
   "amount":"1.00",
   "paid":"1.00",
   "net":0.93,
   "fee":"0.07",
   "currency":"CNY",
   "description":"order description",
   "state":"completed",
   "notify_sig":"ccfdbe3c75f7f79c3f3695c39f034442"
}

2、 Payssion主动发起通知，该方式才会被启用。

3、 只有在Payssion的交易管理中存在该笔交易，且发生了交易状态的改变,Payssion才会通过该方式发起服务器通知。

4、服务器间的交互,不像页面跳转同步通知，可以在页面上显示出来,这种交互方式是不可见的。

5、 第一次交易状态改变时,不仅页面跳转同步通知页面会启用，而且服务器异步通知页面也会收到Payssion发来的处理结果通知。

6、程序执行完后只要http status code为200即认为通知成功。如果http status code不是200，Payssion会在接下来的48小时尝试多次通知，如果所有尝试都失败会邮件通知商家。

7、异步通知每笔交易最多尝试7次，第一次失败后间隔600秒再试尝试通知，之后依次间隔3600秒，3600秒，7200秒，7200秒，14400秒。7次都失败会发送通知失败的邮件到你的注册邮箱。

API Signature 签名

Direct Api创建交易签名

创建交易签名api_sig生成分两步骤：

1、将api_key, pm_id, amount, currency, order_id以及应用的secret_key字符串，以 “|”为分隔符串联成一个字符串 api_key|pm_id|amount|currency|order_id|secret_key

2、将第一步骤串联起来的的字符串经md5加密生成最终的api_sig（小写） 具体代码示例：

$msg = implode("|", array($api_key, $pm_id, $amount, $currency,$order_id, $secret_key));
$api_sig = md5($msg);

Hosted Payment Page创建交易签名

Hosted Payment Page创建交易签名api_sig生成分两步骤： 1、将api_key, amount, currency, order_id以及应用的secret_key以 “|”为分隔符串联成一个字符串 api_key|amount|currency|order_id|secret_key

2、将第一步骤串联起来的的字符串经md5加密生成最终的api_sig（小写） 具体代码示例：

$msg = implode('|', array($api_key, $amount, $currency, $order_id, $secret_key));
$api_sig = md5($msg);

refund退款请求签名

退款请求签名api_sig生成分两步骤： 1、将api_key, transaction_id, amount, currency以及应用的secret_key，以 “|”为分隔符串联成一个字符串 api_key|transaction_id|amount|currency|secret_key

2、将第一步骤串联起来的的字符串经md5加密生成最终的api_sig（小写） 具体代码示例：

$msg = implode('|', array($api_key, $transacion_id, $amount, $currency, $secret_key));
$api_sig = md5($msg);

异步通知签名

异步通知签名notify_sig生成分两步骤：

1、将api_key, pm_id, amount, currency, order_id, state以及应用的sercret_key字符串，以 “|”为分隔符串联成一个字符串api_key|pm_id|amount|currency|order_id|state|secret_key

2、将第一步骤串联起来的的字符串经md5加密生成最终的notify_sig（小写） 具体代码示例：

$msg = implode("|", array($api_key, $pm_id, $amount, $currency,$order_id, $state, $secret_key));
$notify_sig = md5($msg);

交易查询签名

交易查询签名api_sig生成分两步骤：

1、将api_key, transaction_id, order_id以及应用的sercret_key字符串，以 “|”为分隔符串联成一个字符串 api_key|transaction_id|order_id|secret_key

2、将第一步骤串联起来的的字符串经md5加密生成最终的notify_sig（小写） 具体代码示例：

$msg = implode("|", array($api_key, $transaction_id, $order_id, $secret_key));
$api_sig = md5($msg);

付款单页创建交易签名

创建交易签名api_sig生成分两步骤：

1、将api_key, amount, currency, order_id以及应用的secret_key字符串，以 “|”为分隔符串联成一个字符串 api_key|amount|currency|order_id|secret_key

2、将第一步骤串联起来的的字符串经md5加密生成最终的api_sig（小写） 具体代码示例：

$msg = implode("|", array($api_key, $amount, $currency,$order_id, $secret_key));
$api_sig = md5($msg);

Order ID

order_id是订单的ID，用来识别具体是哪个订单的付款。需要注意 order_id默认不做唯一性限制，也就是说你可以用相同的order_id创建多个payments。如果你需要对order_id做唯一性限制请邮件联系我们技术团队设置。

Payment State

Result Code

Payssion的result_code参考了HTTP状态码规范。总的来说，如果result_code是2xx范围的，则表示成功，4xx范围表示失败，5xx范围表示有错误.

PM ID

如果你没有在下面找到你需要的pm_id请联系你的客户经理。支付方式的logo请到Payment logos下载。

Currency

下面是创建payments支持的货币列表

Payment Logos

支付方式logo下载链接

Payment Method特殊支付接入说明

klarna需要传入以下参数billing_address和order_items。需要注意如果是FORM创建交易，请将billing_address和order_items的json数据用base64编码。

1. billing_address json object类型

{
   "city":"Butzbach",
   "country":"DE",
   "email":"test@email.com",
   "family_name":"lastname",
   "given_name":"firstname",
   "phone":"123123",
   "postal_code":"35510",
   "region":"Hessen",
   "line1":"Schorbachstrasse 9",
   "line2":"address 2"
}

2. order_items json数组类型

需要注意order_items中各项加总后的总金额要和订单金额一致。 订单的总金额等于每个item（不包括shipping item和discount item）的amount之和 + shipping item的amount - discount item的amount

[
   {
      "type":"digital",
      "name":"software",
      "quantity":1,
      "amount":1.00,
      "unit_price":1,
      "tax_amount":0,
      "tax_rate":0,
      "discount_amount":0.00
   },
   {
      "type":"physical",
      "name":"clothes",
      "quantity":1,
      "amount":10.00,
      "unit_price":10,
      "tax_amount":0,
      "tax_rate":0,
      "discount_amount":0.00
   },
   {
      "type":"shipping",
      "name":"Standard",
      "quantity":1,
      "amount":1.54,
      "unit_price":1.54,
      "tax_amount":"0.26",
      "tax_rate":20,
      "discount_amount":0
   },
   {
      "type":"discount",
      "name":"Discount",
      "quantity":1,
      "unit_price":1.10,
      "amount":1.10
   }
]

Credited In Settlement Currency

部分支付方式支持以实时以结算入账，这类交易的回调通知notification比标准的异步通知增加三个参数currency_settle, amount_local, currency_local格式如下：

{
    "app_name": "demo",
    "pm_id": "qiwi",
    "transaction_id": "Q622932517067708",
    "order_id": "123",
    "amount": "1.71",
    "paid": "1.71",
    "net": "1.26",
    "fee": "0.45",
    "currency": "USD",
    "description": "test",
    "currency_settle": "USD",
    "amount_local": "100.00",
    "currency_local": "RUB",
    "state": "completed",
    "notify_sig": "529b744c56ebddf8ec14ec08f36a5f9f"
}