API

引言

描述

PAYSTO API — 用于管理多渠道交易基础设施的软件套件。

PAYSTO API 与 Authorize.net Secure Hosted Payment Form API 完全兼容，这使得无需大量成本即可在短时间内配置任何Web资源的集成。

目的

PAYSTO API 允许自动化在俄罗斯接受支付和处理在线订单。

术语和概念

术语	描述
收款人	资金存入其账户的客户
付款人	进行支付的个人
商店	收款人的信息系统。例如，收款人网站上的付款人购物车和收款人的计费系统。

简化支付流程

实线 – 必需
虚线 – 可选。

成功支付时的步骤顺序

1. 支付请求；
2. 检查PAYSTO目录中的商品；
3. 将付款人转至支付页面；
4. 支付状态；
5. 生成收银机收据；
6. 支付状态；
7. 将买家返回至供应商网站；
8. 查询支付状态；
9. 支付状态。

传输的数据类型

名称	描述	值范围
整数	整数	从 0 到 2147483647
长整数	长整数	从 0 到 4294967296
货币	实数，整数和小数部分分隔符为 «.»（点），无千位分隔符，小数部分精确到百分位。点和后面的两位数字是必需的。例如，10 必须写为 10.00，10.123 必须写为 11.12 或 11.13	从 0.01 到 1000000.00
字符串	字符串。不能包含字符 «=»（等号）和字符 «&»（与符号）。	每个参数的长度单独确定。
日期时间	协调世界时（UTC）。格式为 yyyymmddhhnn，其中 y – 表示年份的数字，m – 月份，d – 月份中的日期，h – 小时（hh – 从 0 到 23 的数字）n – 分钟。例如，2010年1月15日 17:04 表示为 201001151704	从 201001010000 到 205012312359
MD5	字符串，表示一个32位十六进制数且为小写（总共32个字符 0-9, A-F）。

安全保障

请求

检查请求来源的IP。签名（必需）。

PAYSTO 响应

检查响应服务器的SSL证书。

响应服务器地址

响应服务器的IP地址在 PAYSTO 个人办公室 > 参数 中指定。

执行支付的请求

账单支付请求

此步骤开始支付商店中开具的账单的程序。

地址元素	值
协议	https
方法	Post
路径	信息在 PAYSTO 个人办公室 > 参数 中提供
编码	UTF8

参数

名称	描述	类型	必需
x_description	支付备注	字符串	是
x_login	商店代码	整数	是
x_amount	待支付金额	货币	是
x_currency_code	待支付金额的货币。可以接受 USD 或 RUB 值	字符串	是
x_cart_currency	商店购物车的货币。值：USD、EUR 或其他货币的简称。当购物车货币不同于卢布（RUB）时传递，以便在支付页面上显示（扣款金额和货币取自 x_amount 和 x_currency_code 的值）。	字符串	否
x_line_item	待支付的购物车内容。字段值的详细描述见下表。	字符串	是
x_email	买家电子邮箱	字符串	否
x_fp_sequence	商店分配的交易编号。这可以是账单号或任何其他随机数。	数值	是
x_fp_timestamp	UTC 时间，从 1970年1月1日 开始的秒数	数值	是
x_fp_hash	使用 HMAC-MD5 哈希算法生成的签名，使用字段 x_login, x_fp_sequence, x_fp_timestamp, x_amount 和 x_currency_code，用 ^ 符号分隔 签名示例		是
x_invoice_num	商店中的账单号	数值	是
x_first_name	买家名字	字符串	否
x_last_name	买家姓氏	字符串	否
x_address	买家地址	字符串	否
x_city	买家城市	字符串	否
x_state	买家地区	字符串	否
x_country	买家国家	字符串	否
x_ship_to_first_name	收货联系人名字	字符串	否
x_ship_to_last_name	收货联系人姓氏	字符串	否
x_phone	联系电话	字符串	否
x_fax	联系传真	字符串	否
x_cust_id	商店中的买家标识符	字符串	否
x_ship_to_address	送货地址	字符串	否
x_ship_to_state	送货地区	字符串	否
x_ship_to_zip	送货地址邮编	字符串	否
x_ship_to_country	送货国家	字符串	否
x_relay_response	字符串必须具有值 «TRUE»	字符串	是
x_relay_url	支付通知 URL	字符串	是

示例字符串: "11111^789^67897654^10.50^USD"
签名生成示例:
Fingerprint = HMAC-MD5 ("11111^789^67897654^10.50^USD", "secret*key")

字段 x_line_item 应包含用户待支付购物车中的一行，由多个元素组成，元素间用分隔符 | 分隔。传递的字段数量必须与购物车中的项目数量一致。

字段 x_line_item 的格式

名称	描述	必需
Item ID	商品标识符。最长31个字符的字符串。	是
item name	商品名称。最长31个字符的字符串。	是
item description	商品描述。最长255个字符的字符串。	是
item quantity	数量。必须为正数。	是
item price (unit cost)	商品单价。实数，整数和小数部分分隔符为 «.»（点），无千位分隔符，小数部分精确到百分位。点和后面的两位数字是必需的。例如，10 必须写为 10.00，10.123 必须写为 11.12 或 11.13	是
item taxable	商品是否需缴纳增值税。可能的值：TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0	否

传递的购物车示例:

x_line_item=item1<|>golf balls<|><|>2<|>18.95<|>Y&
x_line_item=item2<|>golf bag<|>Wilson golf carry bag, red<|>1<|>39.99<|>Y&
x_line_item=item3<|>book<|>Golf for Dummies<|>1<|>21.99<|>Y&

支付详情

此步骤通知商店账单支付结果。

对于此请求，商店应检查：

• 请求来源的IP地址；
• 账单号；
• 支付金额；
• 签名。

放弃这些检查可能会严重削弱对欺诈的防护。

地址元素	值
协议	https
方法	Post
路径	在传递支付请求时在 x_relay_url 中指定
编码	UTF8

参数

名称	描述	类型
x_response_code	支付结果 1 – 已支付 2 – 已拒绝 3 – 错误	整数
x_trans_id	PAYSTO 中的支付编号	长整数
x_invoice_num	商店中的支付编号	整数
x_MD5_Hash	使用 MD5 哈希算法生成的签名，使用密钥和字段 x_login, x_trans_id, x_amount 示例字符串 «secret*key111119876543211.00»	MD5
x_amount	支付金额	货币
x_cust_id	值等于支付请求中的相应参数	字符串
x_first_name	值等于支付请求中的相应参数	字符串
x_last_name	值等于支付请求中的相应参数	字符串
x_address	值等于支付请求中的相应参数	字符串
x_city	值等于支付请求中的相应参数	字符串
x_state	值等于支付请求中的相应参数	字符串
x_zip	值等于支付请求中的相应参数	字符串
x_country	值等于支付请求中的相应参数	字符串
x_phone	值等于支付请求中的相应参数	字符串
x_fax	值等于支付请求中的相应参数	字符串
x_cust_id	值等于支付请求中的相应参数	字符串
x_email	值等于支付请求中的相应参数	字符串
x_ship_to_first_name	值等于支付请求中的相应参数	字符串
x_ship_to_last_name	值等于支付请求中的相应参数	字符串
x_ship_to_address	值等于支付请求中的相应参数	字符串
x_ship_to_city	值等于支付请求中的相应参数	字符串
x_ship_to_state	值等于支付请求中的相应参数	字符串
x_ship_to_zip	值等于支付请求中的相应参数	字符串
x_ship_to_country	值等于支付请求中的相应参数	字符串

HTTP CODE 200 响应的解释	无响应或其他 HTTP CODE、超时的解释
认为商店服务已收到通知。	认为商店服务不可用且无法向买家履行其义务。从买家处收到的资金将被冻结。

买家返回商店

在此步骤中，买家返回商店。

此请求的数据经过买家的计算机，可能被不诚实的买家伪造。因此，不建议在 Success url 和 Fail Url 页面上设置已开具账单的状态。请使用 Result Url 来实现此目的。

我们建议将 Success url 和 Fail Url 指定为同一页面的地址，在该页面上基于处理 Result url 时保存的数据（或通过向 PAYSTO 重新查询账单状态）将用户重定向到最终的成功（失败）支付页面。

重要的是要理解，此步骤是在买家从商店跳转到 PAYSTO 后一段时间从其计算机执行的，因此商店可能需要授权买家才能显示私有数据。

地址元素	值
协议	https
方法	Post
路径	在注册商店时指定
编码	UTF8

参数与 支付详情 点中描述的相同。

支付信息

对于这些请求，建议检查响应服务器的 SSL 证书以防止 DNS 欺骗。

期间对账单

地址元素	值
协议	https
方法	Get
路径	https://paysto.com/api/Payment/GetList

参数

名称	描述	类型	必需
FROM	期间开始（默认 – 当前天的开始）。	日期时间	是
TO	期间结束（默认 – 当前时刻）。	日期时间	是
PAYSTO_SHOP_ID	商店 ID	整数	是
PAYSTO_REQUEST_NO	贯穿所有类型请求的计数器，每个后续值必须大于前一个值。	长整数	否
PAYSTO_MD5	传输数据的签名。MD5 校验和。	MD5	是

响应值

HTTP CODE	注释
200	CSV 文件，格式为 Datetime,PAYSTO_PAYMENT_ID,PAYSTO_INVOICE_ID,PAYSTO_SUM,accountSum,status, statusNote 如果指定期间内没有支付 – 空文件

列描述

名称	描述	类型
Datetime	申请注册的日期和时间。	日期时间
PAYSTO_PAYMENT_ID	PAYSTO 中的交易编号	长整数
PAYSTO_INVOICE_ID	传递的商店账单号。	最长50个字符的字符串
PAYSTO_SUM	申请金额（实际打算支付/已支付的金额）	货币
accountSum	客户账户变动。正数 – 余额增加，负数 – 余额减少。	货币
status	申请状态代码。	申请状态
statusNote	状态注释。例如，如果状态是 RES_ERROR – 则描述错误。	字符串

响应值

HTTP CODE	注释
403	违反安全条件。请检查传递的参数和设置。
404	未找到商店

支付详情

地址元素	值
协议	https
方法	Get
路径	https://paysto.com/api/Payment/GetByInvoiceId

参数

名称	描述	类型	必需
PAYSTO_INVOICE_ID	传递的商店账单号。	最长50个字符的字符串	是
PAYSTO_SHOP_ID	商店 Id	整数	是
PAYSTO_REQUEST_NO	贯穿所有类型请求的计数器，每个后续值必须大于前一个值。	长整数	否
PAYSTO_MD5	传输数据的签名。MD5 校验和。	MD5	是

响应值

HTTP CODE	注释
200	CSV 文件，格式为 Datetime,PAYSTO_PAYMENT_ID,PAYSTO_INVOICE_ID,PAYSTO_SUM,accountSum,status, statusNote

列描述

名称	描述	类型
Datetime	申请注册的日期和时间。	日期时间
PAYSTO_PAYMENT_ID	PAYSTO 中的交易编号	长整数
PAYSTO_INVOICE_ID	传递的商店账单号。	最长50个字符的字符串
PAYSTO_SUM	申请金额（实际打算支付/已支付的金额）	货币
accountSum	客户账户变动。正数 – 余额增加，负数 – 余额减少。	货币
status	申请状态代码。	申请状态
statusNote	状态注释。例如，如果状态是 RES_ERROR – 则描述错误。	字符串

响应值

HTTP CODE	注释
403	违反安全条件。请检查传递的参数和设置。
404	未找到该商店的具有此编号的账单

账户状态

对于这些请求，建议检查响应服务器的 SSL 证书以防止 DNS 欺骗。

余额查询

地址元素	值
协议	https
方法	Get / Post (推荐)
路径	https://paysto.com/api/Common/Balance

参数

名称	描述	类型	必需
PAYSTO_SHOP_ID	商店 Id，注册时发放。	整数	是
PAYSTO_REQUEST_NO	贯穿所有类型请求的顺序号，每个后续值必须大于前一个值。	长整数	否
PAYSTO_MD5	传输数据的签名。MD5 校验和。	MD5	是

响应	描述	类型
HTTP CODE 200	标量值。可用余额。	货币
HTTP CODE 403	违反安全条件。请检查传递的参数和设置。
HTTP CODE 404	未找到商店

附录。连接参数

从个人办公室界面获取的数据（需要注册）：

1. 商店 ID；
2. API 请求地址；
3. 响应服务器地址；
4. 密钥（连接时由用户设置）；