原文链接:简单付款设置协议(SPSP)
目录
前言
本文档描述了简单支付设置协议(SPSP),这是一种在付款人和收款人之间交换支付信息的基本协议,以便于通过Interledger进行支付.SPSP使用STREAM传输协议进行生成条件和数据编码。
介绍
动机
STREAM没有规定如何在付款人和收款人之间交换支付细节,例如ILP地址或共享密钥.SPSP是一种使用HTTPS传递这些详细信息的最小协议。
范围
SPSP提供交换发件人设置STREAM付款所需的基本接收者详细信息。它旨在供最终用户应用程序使用。
接口
SPSP可以由终端用户的应用程序使用,例如具有用户接口的数字钱包,以便发送者发起支付.SPSP客户端和接收者使用ILP模块发送和接收Interledger支付.SPSP 支付指针可用作Interledger上的持久标识符.SPSP支付指针也可以用作要支付的发票的唯一标识符。
SPSP消息必须通过HTTPS进行交换。
操作
任何SPSP接收者都将运行SPSP服务器,并公开HTTPS端点作为SPSP端点。发件人可以查询此端点,获取此接收者的付款类型信息。发件人可以使用接收者提供的详细信息设置和发送多个ILP付款。
定义
- SPSP客户端 - 使用SPSP与SPSP服务器交互的发件人应用程序
- SPSP服务器 - 接收方用于处理SPSP请求的服务器
- SPSP端点 - SPSP服务器上用于设置付款的特定HTTPS端点
- STREAM模块 - 实现STREAM协议的SPSP客户端和服务器中包含的软件。
综述
与其他协议的关系
SPSP用于在启动ILP付款之前,先进行交的换付款信息。发送方和接收方使用STREAM传输协议生成ILP数据包。接收方生成要在STREAM中使用的共享密钥和ILP地址,并通过HTTPS将其传递给发送方。
运作模式
我们假设发送方知道接收方的SPSP端点(请参阅支付指针)。
- 发送方的SPSP客户端查询接收方的SPSP端点。
- SPSP端点响应接收者信息,包括接收者的ILP地址和STREAM中使用的共享密钥。它可以使用与此SPSP接收者相关的余额信息进行响应,比如包含发票信息。
- 发件人使用接收者的ILP地址组建ILP付款信息。
- 发件人开始发送付款。
- 发送方使用STREAM建立到接收方的ILP / STREAM连接。
- 发送方将在ILP / STREAM连接上构造到接收方的流。
- 发件人将调整他们
sendMax
以反映他们愿意发送的金额。 - 接收者将调整他们
receiveMax
以反映他们愿意接受的金额。 - 发送方和接收方的STREAM模块将尽可能多地移动,同时保持在这些边界内。
- 如果发件人到达他们
sendMax
,他们将结束流和连接。如果接收器到达它们receiveMax
,它们将结束STREAM和连接。
规格
SPSP端点是发件人用于查询有关接收方(可能是发票)的信息并设置付款的URI。SPSP端点URI绝不能包含查询字符串参数。发件人应该将URI视为不透明。有几种支持的方法可以引用SPSP端点:
- 付款指针(推荐)
$alice.example.com
或$example.com/bob
。这应该是向用户公开的唯一一种SPSP标识符。 - 原始端点URI(不推荐)
https://example.com/spsp/alice
。这不应该向用户公开,但应该得到SPSP客户的支持。
SPSP端点必须以GET
下列方式响应HTTPS 请求:
查询(GET <SPSP Endpoint>
)
发件人查询SPSP端点以获取有关可以对此接收者进行的付款类型的信息:
请求
(带标识符$example.com
)
GET /.well-known/pay HTTP/1.1
Host: example.com
Accept: application/spsp4+json, application/spsp+json
响应
HTTP/1.1 200 OK
Content-Type: application/spsp4+json
{
"destination_account": "example.ilpdemo.red.bob",
"shared_secret": "6jR5iNIVRvqeasJeCty6C+YB5X9FhSOUPCL/5nha5Vs=",
"balance": {
"maximum": "100000",
"current": "5360"
},
"asset_info": {
"code": "USD",
"scale": 2
},
"receiver_info": {
"name": "Bob Dylan",
"image_url": "https://red.ilpdemo.org/api/spsp/bob/profile_pic.jpg"
}
}
balance,asset_info和receiver_info对象都是可选的,因此最小SPSP响应的样子:
HTTP/1.1 200 OK
Content-Type: application/spsp4+json
{
"destination_account": "example.ilpdemo.red.bob",
"shared_secret": "6jR5iNIVRvqeasJeCty6C+YB5X9FhSOUPCL/5nha5Vs="
}
响应标题
响应必须至少包含以下标题:
头 | 描述 |
---|---|
Content-Type | 必须application/spsp4+json 指示响应被编码为JSON并且ILP支付应该通过STREAM发送。 |
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编码(包括填充) | STREAM中此特定http客户端使用的共享密钥。应仅由服务器和此特定http客户端共享,因此每个查询响应应该不同。 |
balance | 对象 | (可选)此接收器余额的详细信息。用于发票和类似的临时账户。 |
balance.maximum | 整数字符串 | 最大数量,以接收方帐户的最小可分割单位表示,接收方将接受。这表示允许传入的块达到的最高总和,而不是单个块的最大大小(由路径MTU确定)。如果这是发票,balance.maximum 则是发票被视为已支付的金额。 |
balance.current | 整数字符串 | 所有传入块的当前总和。 |
asset_info | 对象 | (可选)有关目标资产的详细信息,用于发件人的显示目的。 |
asset_info.code | 字符串 | 用于识别接收方货币的资产代码。具有ISO 4217代码的货币应使用这些货币。发件人UI应该能够呈现非标准代码 |
asset_info.scale | 整数 | 接收方账户金额的"1000" 规模(例如,金额2 转换为10.00 接收方资产/货币单位的金额) |
receiver_info | 对象 | (可选)有关接收器的任意附加信息。该字段没有架构,接收器可以包括它们选择的任何字段。建议仅出于互操作目的,列出下面列出的字段名称。 |
receiver_info.name | 字符串 | (可选)接收方代表的个人,公司或组织的全名 |
receiver_info.image_url | HTTPS URL | (可选)发件人可以获取接收者图片表示的URL |
注意:货币金额被称为整数字符串而不是本机JSON数字,以避免在JSON解析期间丢失精度。应用程序必须将这些数字表示为精度等于或大于无符号64位整数的数据类型。
错误
接收器不存在
HTTP/1.1 404 Not Found
Content-Type: application/spsp4+json
{
"id": "InvalidReceiverError",
"message": "Invalid receiver ID"
}
付款设置
发件人使用接收者详细信息来创建STREAM连接:
- 本
destination_account
应作为STREAM destinationAccount。 - 该
shared_secret
应的base64进行解码,并作为STREAM sharedSecret。 - 如果存在,
balance.maximum - balance.current
应该用作STREAMreceiveMax
。
在UI中,asset_info
状语从句:receiver_info
对象(如果存在)可用于显示目的。接收器可以以任何方式操纵这些对象,因此在可能的情况下,应该以源为单位显示数量。
请注意,发件人可以使用相同的收件人信息发送任意数量的STREAM付款。一旦Cache-Control
标题中指示的时间过去,发送方应该再次查询接收方。
备注:翻译校对的不好,请海涵〜