Payment
Paymentトランザクションは、アカウント間での価値の移動を表現するものです（通過するパスによっては、非可分的に発生する追加的な価値交換を伴うことがあります）。
Paymentは、アカウントを作成する唯一の手段でもあります。
PaymentのJSONの例
{
"TransactionType" : "Payment",
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Amount" : {
"currency" : "USD",
"value" : "1",
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
},
"Fee": "12",
"Flags": 2147483648,
"Sequence": 2,
}
Payment Fields
In addition to the common fields, a Payment transaction uses the following fields:
| フィールド | JSONの型 | 内部の型 | 説明 |
|---|---|---|---|
| Amount | 通貨額 | Amount | 送金する通貨額。XRP以外の金額の場合、入れ子フィールドの名前では、アルファベットの小文字のみ使用してください。tfPartialPaymentフラグが設定されている場合は、この金額を 上限 とする金額を送金します。 |
| Destination | 文字列 | AccountID | 支払いを受取るアカウントの一意アドレス。 |
| DestinationTag | 数値 | UInt32 | （省略可） 宛先（支払先となる、ホスティングされている受取人）への支払い理由を明確にするための任意のタグ。 |
| InvoiceID | 文字列 | Hash256 | （省略可） この支払いの具体的な理由または識別子を表現する任意の256ビットハッシュ。 |
| Paths | パス配列の配列 | PathSet | （省略可。自動入力可能）このトランザクションに使用される支払いパスの配列。XRP間のトランザクションでは省略する必要があります。 |
| SendMax | 通貨額 | Amount | （省略可） 送金手数料、為替レート、スリッページ を含め、このトランザクションに関して支払い元通貨での負担を許容する上限額。トランザクションの送信コストとして消却されるXRPは含めないでください。XRP以外の金額の場合、入れ子フィールドの名前では、アルファベットの小文字のみ使用してください。複数通貨間の支払いまたは複数の発行を伴う支払いについては、このフィールドを入力する必要があります。XRP間の支払いでは省略する必要があります。 |
| DeliverMin | 通貨額 | Amount | （省略可） このトランザクションで送金する、宛先通貨での最少金額。Partial Paymentsの場合のみ有効になります。XRP以外の金額の場合、入れ子フィールドの名前では、アルファベットの小文字のみ使用してください。 |
SendMaxおよびAmountで使用する特殊なイシュアーの値
ほとんどの場合、XRP以外の通貨額のissuerフィールドは、金融機関の発行アドレスを示しています。ただし、支払いを記述するにあたって、支払いのAmountフィールドとSendMaxフィールドにあるissuerフィールドについては、特殊なルールが存在します。
- 2つのアドレス間で、同一の通貨に関して存在する残高は常に1つです。つまり、金額の
issuerフィールドが実際に表しているのは、イシュアンスを作成したアドレスではなく、イシュアンスを換金する相手方であることがあります。 - 宛先
AmountフィールドのissuerフィールドがDestinationアドレスと一致している場合、「宛先が受け入れるあらゆるイシュアー」を意味する特殊なケースとして取り扱われます。これには、他のトラストラインで保持されている宛先によって作成されたイシュアンスに加え、宛先が当該アドレスまでトラストラインを延長しているすべてのアドレスが含まれます。 SendMaxフィールドのissuerフィールドが送信元アカウントのアドレスと一致している場合、「送信元が使用できるあらゆるイシュアー」を意味する特殊なケースとして取り扱われます。これには、他のアカウントが送信元アカウントまで延長しているトラストラインで新しいイシュアンスを作成すること、送信元アカウントが保持しているイシュアンスを他のイシュアーから送信することが含まれます。
アカウントの作成
Payment型のトランザクションでは、資金供給のないアドレスに対して十分なXRPを送金することで、XRP Ledgerに新規のアカウントを作成できます。資金供給のないアドレスに対するその他のトランザクションは、常に失敗します。
詳細は、アカウントを参照してください。
パス
Pathsフィールドが存在する場合、Pathフィールドには、 パスセット （パス配列の配列）が記述されていなければなりません。個々のパスは、さまざまな仲介アカウントやオーダーブックを経由して、送信者から受信者へと価値が1つの方向へ流れることを表します。単一のトランザクションで、複数のパスを使用する可能性もあります。例えば、トランザクションで複数のオーダーブックを使用して、最も有利なレートで通貨を交換する場合です。
以下の場合を含め、直接の支払いではPathsフィールドを省略する必要があります。
- XRP間の送金。
- 送信者と受信者を接続するトラストライン上での直接送金。
Pathsフィールドを指定すると、サーバーは、提供されたセットと デフォルトパス の中から、使用するパス（指定されたアカウントに接続する上で、最も直行となる経路）をトランザクション処理時に判別します。このように決定された判別は、コストを最小化しようとするものですが、完璧であることは保証されません。
Pathsフィールドを、空の配列としたり、メンバーがすべて空の配列あるような配列としたりすることはできません。
詳細は、Pathsを参照してください。
Paymentのフラグ
Payment型のトランザクションについては、Flagsフィールドで以下の値が追加でサポートされます。
| フラグの名前 | 16進値 | 10進値 | 説明 |
|---|---|---|---|
| tfNoDirectRipple | 0x00010000 | 65536 | デフォルトパスを使用せず、Pathsフィールドに含まれているパスのみ使用します。これによりトランザクションは強制的に裁定機会を活用することになります。ほとんどのクライアントでは、これは必要ありません。 |
| tfPartialPayment | 0x00020000 | 131072 | SendMaxを超えていないのに指定されたAmountを送金できない場合、即座に失敗とするのではなく、受取られる額を減額します。詳細は、Partial Paymentsを参照してください。 |
| tfLimitQuality | 0x00040000 | 262144 | すべての変換で、入力と出力との比率がAmountとSendMaxとの比率と同一であるか、さらに有利となるパスのみを採用します。詳細は、クオリティの制限を参照してください。 |
Partial Payments
Partial Paymentsを利用すると、受取られる金額を減額することによって、支払いを成功させることができます。Partial Paymentsが有用なのは、追加的なコストを発生させずに支払いを返金する場合です。その一方で、成功したトランザクションのAmountフィールドに、送金された金額が常に正しく記述されていることを前提としている環境において、悪用されるおそれもあります。
Partial Paymentsとは、tfPartialPaymentフラグが有効になっているPaymentトランザクションです。Partial Paymentsは、SendMax値を超える金額を送金することなく、DeliverMinフィールド以上の正の金額（DeliverMinが指定されていない場合、任意の正の金額）を送金する場合に成功します。
支払いのメタデータにあるdelivered_amountフィールドは、宛先アカウントが実際に受け取る通貨の金額を示しています。
詳細は、Partial Paymentsの全文を参照してください。
クオリティの制限
XRP Ledgerでは、ある通貨での入金額と別の通貨での出金額の比率として、通貨取引の「クオリティ」を定義します。例えば、2米ドルと引き換えに1イギリスポンドを受け取る場合、その交換の「クオリティ」は0.5です。
tfLimitQualityフラグを使用すると、実行する変換のクオリティについて下限を設定できます。このクオリティの制限は、宛先のAmountをSendMaxの金額（通貨にかかわらず金額のみ）で除算することによって定義します。設定した場合、支払い処理エンジンは、クオリティの制限よりもクオリティ（為替レート）が低い（数値が小さい）パスの使用を回避します。
tfLimitQualityフラグは、それ自体、トランザクションが成功する状況を減少させるものになります。具体的には、好ましくない変換が支払いの一部で使用されている場合、支払いにおける変換の平均的なクオリティが全体としてクオリティの制限と同一か、それ以上であっても、支払いが拒否されます。支払いがこの形で拒否される場合、トランザクションの結果はtecPATH_DRYです。
次の例を考えてみます。100人民元（Amount = 100人民元）を最大20米ドル（SendMax = 20米ドル）と引き換えに相手方に送金しようとする場合、クオリティの制限は5です。あるトレーダーが15米ドルと引き換えに95人民元をオファーしているものの（米ドルあたり約6.3人民元の比率）、市場の次善のオファーが2ドルに対して5人民元であるとします（米ドルあたり2.5人民元の比率）。両方のオファーを受諾して相手方に100人民元を送金する場合、送信元が負担するコストは17米ドルであり、平均のクオリティは約5.9です。
tfLimitQualityフラグが設定されていない場合、17米ドルというコストは指定されたSendMaxに収まっているため、このトランザクションは成功します。一方、tfLimitQualityフラグが有効になっている場合は失敗します。2番目のオファーを受諾するためのパスのクオリティは2.5であり、5というクオリティの制限よりも低いためです。
tfLimitQualityフラグが最も有用となるのは、Partial Paymentsと組み合わせる場合です。tfPartialPaymentとtfLimitQualityの両方がトランザクションに対して設定されている場合、トランザクションでは、クオリティの制限よりも低い変換を使用することなく、送金可能な最大限の宛先Amountが送金されます。
95人民元/15米ドルのオファーと5人民元/2米ドルのオファーがある上の例で、トランザクションに関してtfPartialPaymentとtfLimitQualityの両方が有効になっている場合、状況は異なります。20米ドルのSendMaxおよび100人民元の宛先Amountを維持する場合も、クオリティの制限は5です。ただし、実行しようとするのはPartial Paymentsであるため、宛先に対する送金の全額を一度で送金できない場合、トランザクションを失敗とするのではなく、送金可能な最大限の金額が送金されます。つまり、トランザクションでは、クオリティが約6.3である95人民元/15米ドルのオファーは受け入れますが、5人民元/2米ドルのオファーはクオリティが2.5であり、クオリティの制限の5より低いため、拒否します。最終的に、トランザクションで送金されるのは満額の100人民元ではなく95人民元になりますが、不利な為替レートで資金を浪費することを避けられます。