备注:下文只做简单的翻译,没有做校验
前言
本文档描述简单付款设置协议(SPSP),这是一种用于在发件人和收件人之间交换付款信息以设置Interledger付款的基本协议。SPSP使用预共享密钥(PSK)传输协议进行条件生成和数据编码。
介绍
动机
Interledger协议并未指定应如何在发送方和接收方之间交换支付细节,如ILP数据包或加密条件。SPSP是一个使用HTTPS传递这些细节的最小协议。
范围
SPSP提供交换发件人设置ILP支付所需的基本接收者详细信息。它旨在供最终用户应用程序使用。
接口
最终用户应用程序可能会使用SPSP,例如带有用户界面的数字钱包以便发件人启动付款。SPSP客户端和接收者使用ILP模块发送和接收Interledger付款。
必须通过HTTPS交换SPSP消息。
手术
任何SPSP接收器都将运行SPSP服务器并公开一个称为SPSP端点的HTTPS端点。发件人可以查询此端点以获取有关可以对此接收方进行支付的类型的信息。发件人可以使用接收者提供的详细信息设置和发送多项ILP付款。
定义
- SPSP客户端 - 使用SPSP与SPSP服务器进行交互的发件人应用程序
- SPSP服务器 - 接收方用来处理SPSP请求的服务器
- SPSP端点 - 用于设置付款的SPSP服务器上的特定HTTPS端点
- PSK模块 - 包含在实施预共享密钥协议的SPSP客户端和服务器中的软件
概观
与其他协议的关系
SPSP用于在启动ILP付款之前交换支付信息。发送方和接收方使用预共享密钥(PSK)传输协议来生成条件和履行。接收器生成要在PSK中使用的共享密钥,并通过HTTPS将其发送给发件人。
操作模式
我们假设发送方知道接收方的SPSP端点(请参阅附录A :(可选)Webfinger发现)。
- 发件人的SPSP客户端查询接收者的SPSP端点。
- SPSP端点响应接收方信息,包括接收方的ILP地址和要在PSK中使用的共享密钥。
- 发件人使用收件人的ILP地址构建ILP付款。
- 发件人使用PSK生成付款条件并格式化附加数据,以便将收件人与付款一起发送。
- 发件人准备将本地传输发送至连接了条件和ILP数据包的连接器。
- 接收器的PSK模块注册传入的传输,解析和验证ILP数据包和传入传输。
- 接收者可以将收款付款提交给外部系统进行审查,以确保资金被通缉。
- 如果预期付款,接收方的PSK模块将条件履行提交给分类账以执行转账。否则,PSK模块将拒绝传入的传输。
- 如果接收方执行了转账,发送方的SPSP客户机会从其ILP模块接收到已执行转账的通知,包括接收方的条件履行,并通知发件人付款已完成。如果接收方拒绝转移,发送方的SPSP客户端会收到一封包含接收方指定错误消息的通知,详细说明支付被拒的原因。
规范
SPSP端点是发件人用来查询接收方信息并设置付款的URI。SPSP端点URI可以包含查询字符串参数。发送者应该将URI视为不透明。
SPSP端点必须GET
按以下方式对HTTPS 请求作出响应:
Query(GET <SPSP Endpoint>
)
发件人查询SPSP端点以获取有关可以对此接收方进行的付款类型的信息:
请求
GET /api/spsp/bob HTTP/1.1
Host: red.ilpdemo.org
Accept: application/json
响应
HTTP/1.1 200 OK
Content-Type: application/json
{
"destination_account": "example.ilpdemo.red.bob",
"shared_secret": "6jR5iNIVRvqeasJeCty6C-YB5X9FhSOUPCL_5nha5Vs",
"maximum_destination_amount": "100000",
"minimum_destination_amount": "10",
"ledger_info": {
"currency_code": "USD",
"currency_scale": 2
},
"receiver_info": {
"name": "Bob Dylan",
"image_url": "https://red.ilpdemo.org/api/spsp/bob/profile_pic.jpg"
}
}
响应头
响应必须至少包含以下标题:
头 | 描述 |
---|---|
Content-Type | 必须是application/json 指示响应被编码为JSON。 |
Cache-Control | 指示SPSP客户端应该缓存响应的时间。请参阅下面支持的缓存控制指令。 |
为了尽可能多地处理每秒事务,SPSP客户端缓存来自SPSP服务器的结果。由SPSP服务器返回的信息预计不会迅速改变,因此对相同信息的重复请求通常是多余的。服务器会通过多长时间缓存在RESTful API调用的响应中使用HTTP标准Cache-Control
头的结果。
SPSP客户端了解以下Cache-Control指令:
指示 | 描述 |
---|---|
max-age=<i> | 客户端应该将此响应缓存<i> 数秒。<i> 必须是一个正整数 |
no-cache | 客户端不得缓存此响应 |
响应体
响应正文是一个JSON对象,包含设置付款所需的基本帐户详细信息。
领域 | 类型 | 描述 |
---|---|---|
destination_account | ILP地址 | ILP接收方账户的地址 |
shared_secret | 32个字节,base64-url编码 | 预共享密钥协议中此特定http客户端使用的共享密钥。应该仅由服务器和此特定的http客户端共享,因此应该在每个查询响应中有所不同。 |
maximum_destination_amount | 整数字符串 | 最大金额,以分类账的最小可分割单位表示,接收方将接受。该金额可能由分类账的最大账户余额或转账金额决定。如果接收方希望交付特定金额,则可以将其设置为等于minimum_destination_amount |
minimum_destination_amount | 整数字符串 | 最小金额,以分类账的最小可分割单位表示,接收方将接受。该金额可能由分类账的最低转账金额决定。如果接收方希望交付特定金额,则可以将其设置为等于maximum_destination_amount |
ledger_info | 目的 | 有关目的地账本的详细信息 |
ledger_info.currency_code | 串 | 识别接收者货币的货币代码。具有ISO 4217代码的货币应使用这些代码。发件人UI应该能够呈现非标准代码 |
ledger_info.currency_scale | 整数 | 目的地账本上的金额的"1000" 规模(例如,一定数量的金额2 转换为10.00 目的地账本货币的单位) |
receiver_info | 目的 | 有关接收器的任意附加信息。该字段没有模式,接收者可以包含他们选择的任何字段。下面列出的字段名称仅用于互操作性目的。 |
receiver_info.name | 串 | (可选)接收者所代表的个人,公司或组织的全名 |
receiver_info.image_url | HTTPS网址 | (可选)发件人可以获得接收者图片表示的URL |
注意:货币金额被命名为整数字符串而不是本地JSON号码,以避免在JSON解析期间丢失精确度。应用程序必须以精度等于或大于无符号64位整数的数据类型表示这些数字。
错误
接收器不存在
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"id": "InvalidReceiverError",
"message": "Invalid receiver ID"
}
付款设置
发件人使用接收者详细信息来创建ILP数据包:
- 的
account
在ILP包在destination_account
由接收器提供 在
amount
由发送者确定:- 发送方使用
ledger_info.currency_scale
确定要包含在ILP数据包中的整数量(例如,如果他们希望接收方ledger_info.currency_code
在其分类账上接收10个单位,则ledger_info.currency_scale
值为2表示应将其设置amount
为1000)。在发送者知道接收者应该得到的整数量的情况下,例如如果接收者在带外请求该数量的话,发送者不需要使用ledger_info.currency_code
并且ledger_info.currency_scale
- 发送方不应该设置大于
maximum_destination_amount
或低于的金额minimum_destination_amount
,因为这将被接收方拒绝
- 发送方使用
的
data
是使用编码预共享密钥协议:- 关键是
shared_secret
由接收器提供 - 其他数据可能包含在PSK细节中。SPSP数据必须是JSON。
- 私人PSK头应该包括
Content-Type: application/json
和Content-Length: <byte length of data>
- 关键是
请注意,发件人可以使用相同的收件人信息发送尽可能多的付款。一旦Cache-Control
标题中指示的时间已过,发送方应该再次查询接收方。
附录A :(可选)Webfinger发现
只要有可能,接收方URL应该在带外进行交换,并且应该跳过发现。但是,在某些情况下,使用标准化的用户友好标识符可能很有用。此发现方法描述了如何将此类标识符解析为SPSP端点。
首先,发件人使用Webfinger(RFC 7033)查找标识符(例如` bob@red.ilpdemo.org`):
GET /.well-known/webfinger?resource=acct%3Abob%40red.ilpdemo.org HTTP/1.1
Host: red.ilpdemo.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"subject": "acct:bob@red.ilpdemo.org",
"links": [
{
"rel": "https://interledger.org/rel/spsp/v2",
"href": "https://red.ilpdemo.org/api/spsp/bob"
}
]
}