InitializingPayment

Protocol.InitializingPayment History

Hide minor edits - Show changes to output

November 28, 2006, at 06:32 PM by ryan - rendezvous intermediaries
Changed lines 70-71 from:
If the payer's routing information is omitted, then the recipient may not initiate any path queries.
to:
The payer's routing information may direct the recipient's queries to its own node, or another node that the payer can reach with its queries, called a rendezvous intermediary.  If the payer's routing information is omitted, then the recipient may not initiate any path queries.  If the recipient is unable to recognize or otherwise route a payment to the payer's routing ID, it responds with an error.  The payer may then retry with a different routing ID, either for itself, for a rendezvous intermediary that it can reach, or simply omit its routing ID.
Changed lines 102-103 from:
If the recipient's routing information is omitted, then the payer may not initiate any path queries.  If both payer and recipient omit their routing information, the path discovery phase may not begin, and the payment must be aborted. 
to:
If the recipient's routing information is omitted, then the payer may not initiate any path queries.  If the payer does not recognize or is unable to route to the recipient's routing ID, the recipient may retry with another ID for itself or for a rendezvous intermediary, or omit its ID entirely.  If both payer and recipient omit their routing information, the path discovery phase may not begin, and the payment must be aborted. 
Changed lines 102-103 from:
If the recipient's routing information is omitted, then the payer may not initiate any path queries.  If both payer and recipient omit their routing information, the path discovery phase may not begin, and the payment must be aborted.  As a rule, it is preferable for the recipient to omit routing information than for the payer to do so.  This is because queries originating at the recipient are more precise, and the transaction will proceed faster.  (See [[Path Discovery -> Protocol/PathDiscovery#path-queries-and-responses]].)
to:
If the recipient's routing information is omitted, then the payer may not initiate any path queries.  If both payer and recipient omit their routing information, the path discovery phase may not begin, and the payment must be aborted. 
Changed lines 102-103 from:
If the recipient's routing information is omitted, then the payer may not initiate any path queries.  If both payer and recipient omit their routing information, the path discovery phase may not begin, and the payment must be aborted.  As a convention, the payer should always divulge its routing information, but the recipient may choose to omit it.  This is because queries originating at the recipient are more precise.  (See [[Path Discovery -> Protocol/PathDiscovery#path-queries-and-responses]].)
to:
If the recipient's routing information is omitted, then the payer may not initiate any path queries.  If both payer and recipient omit their routing information, the path discovery phase may not begin, and the payment must be aborted.  As a rule, it is preferable for the recipient to omit routing information than for the payer to do so.  This is because queries originating at the recipient are more precise, and the transaction will proceed faster.  (See [[Path Discovery -> Protocol/PathDiscovery#path-queries-and-responses]].)

As described in [[Rendezvous Intermediaries -> Protocol/PathDiscovery#rendezvous-intermediaries]], it is possible for either payer or recipient to have the other party target their queries to a routing entity other than their own, and arrange for that entity to receive a query so it knows where to route the queries it receives from the opposite direction.

Changed lines 49-51 from:
* transaction units (optional)
* payment amount in transaction units
* payer's routing information
to:
* path units (optional)
* payment amount in path units
* payer's routing information (optional)
Changed lines 60-61 from:
   "transaction_units": "urn:ripple:units:USD",
    "transaction_amount": 89.9326,
to:
   "path_units": "urn:ripple:units:USD",
    "path_amount": 89.9326,
Changed lines 68-69 from:
Transaction units allow the payer to mask the true units of the payment by hiding the true units from the intermediaries.  What the transaction units are is not important to the payer and recipient, as the precise conversion to payment units is established by the @@payment_init@ message.  The transaction units need not even be specified, and an arbitrary figure such as 1.00 can always be used as the transaction amount.  However, this will hinder intermediaries' ability to properly conduct zero-fee path searches.  To guarantee overall fee limits on paths, transaction units must be recognizable to the intermediaries.  See [[Path Queries -> #path-queries]].
to:
"Path units" allow the payer to mask the true units of the payment by hiding the true units from the intermediaries.  What the path units are is not important to the payer and recipient, as the precise conversion to actual payment units is established by the @@payment_init@ message.  The path units need not even be specified, and an arbitrary figure such as 1.00 can always be used as the path amount.  However, this will hinder intermediaries' ability to properly conduct fee-limited path searches.  To guarantee overall fee limits on paths, path units must be recognizable to the intermediaries.  See [[Protocol/PathDiscovery]].

If the payer's routing information is omitted, then the recipient may not initiate any
path queries.
Changed lines 77-78 from:
* transaction units
* payment amount in transaction units
to:
* path units
* payment amount in path units
Changed line 80 from:
* recipient's routing information
to:
* recipient's routing information (optional)
Changed lines 90-91 from:
   "transaction_units": "urn:ripple:units:USD",
    "transaction_amount": 89.9326,
to:
   "path_units": "urn:ripple:units:USD",
    "path_amount": 89.9326,
Changed lines 100-103 from:
This must be signed by the recipient's identifying certificate key, whose certificate identifies the recipient in a way acceptable to the payer, such as being issued (i.e., signed) by an authority recognized by the payer.  This message serves as evidence that the recipient participated in the transaction.  Thus the signature of the recipient's receipt key on the payment receipts can be irrevocably connected the recipient, proving that the payment was indeed received (see [[Finalizing Payment -> #finalizing-payment]].  The explanatory text can contain text linking the payment to a real-world exchange of goods or services.

Otherwise the recipient rejects the @@payment_init@@ with an error code.
to:
This must be signed by the recipient's identifying certificate key, whose certificate identifies the recipient in a way acceptable to the payer, such as being issued (i.e., signed) by an authority recognized by the payer.  This message serves as evidence that the recipient participated in the transaction.  Thus the signature of the recipient's receipt key on the payment receipts can be irrevocably connected the recipient, proving that the payment was indeed received (see [[Protocol/PaymentTransaction]].  The explanatory text can contain text linking the payment to a real-world exchange of goods or services.

If the recipient's routing information is omitted, then the payer may not initiate any path queries.  If both payer and recipient omit their routing information, the path discovery phase may not begin, and the payment must be aborted.  As a convention, the payer should always divulge its routing information, but the recipient may choose to omit it.  This is because queries originating at the recipient are more precise.  (See [[Path Discovery -> Protocol/PathDiscovery#path-queries-and-responses]].)

The recipient may reject
the @@payment_init@@ with an error code.
November 15, 2006, at 06:03 AM by ryan - JSON messages
Added line 14:
[[#requesting-payment]]
Changed lines 17-18 from:
A node wishing to receive a payment from another node may initiate contact with the potential payer node by sending a @@payment-request@@ message to his node's network ID:
to:
A node wishing to receive a payment from another node may initiate contact with the potential payer node by sending a @@payment_request@@ message to his node's network ID:
Deleted line 22:
* authorization number (optional)
Changed lines 25-28 from:
The payment request may be followed by an @@payment-init@@ message from the potential payer, or ignored.

The authorization number field may be used to contain a single-use password to pre-authorize payments, so the node can automatically make payments when it receives a
request containing a password from a pre-determined list that it holds.  The payment-request message may also be authorized by signing it with a certain key, contained in the node owner's smart card, for example, for point-of-sale scenarios.
to:
[@
{
  "payment_
request": {
    "
payment_id": "393ff635-de8b-486f-b650-c4f1b151172c",
    "amount": 100.00
,
   "units": "urn:ripple:units:CAD",
    "recipient_node_id": "rfugger@ripplepay.com",
    "note": "For auction item 1234.  Please pay by Dec. 31."
  }
}
@]

The @@payment_
request@@ may be followed by an @@payment_init@@ message from the potential payer, or ignored.

The @@payment_request@@
message may be authorized by signing it with a certain key, contained in the node owner's smart card, for example, for point-of-sale scenarios.

[[#initializing-payment]]
Changed lines 44-45 from:
The payer node contacts recipient node and communicates the following in a @@payment-init@@ message:
to:
The payer node contacts recipient node and communicates the following in a @@payment_init@@ message:
Changed line 49 from:
* transaction units
to:
* transaction units (optional)
Changed lines 54-57 from:
Transaction units allow the payer to mask the true units of the payment by inventing custom units.  However, this will hinder intermediaries' ability to properly conduct zero-fee path searches.  To guarantee overall fee limits on paths, transaction units must be recognizable to the intermediariesSee [[Path Queries -> #path-queries]].

The recipient may accept
the payment initiation with an @@payment-accept@@:
to:
[@
{
  "payment_init": {
    "payment_id": "393ff635-de8b-486f-b650-c4f1b151172c",
    "amount": 100.00,
    "
units": "urn:ripple:units:CAD",
   "transaction_units": "urn:ripple:units:USD",
    "transaction_amount": 89
.9326,
    "payer_routing_id": "9a62c494-2fbb-4421-9da2-93dd93ea72b4",
    "note": "Payment for auction item 1234
."
  }
}
@]

Transaction units allow the payer to mask
the true units of the payment by hiding the true units from the intermediaries.  What the transaction units are is not important to the payer and recipient, as the precise conversion to payment units is established by the @@payment_init@ message.  The transaction units need not even be specified, and an arbitrary figure such as 1.00 can always be used as the transaction amount.  However, this will hinder intermediaries' ability to properly conduct zero-fee path searches.  To guarantee overall fee limits on paths, transaction units must be recognizable to the intermediaries.  See [[Path Queries -> #path-queries]].

The recipient may accept the @@payment_init@@ with a @@payment_
accept@@:
Changed lines 82-85 from:
This must be signed by the recipient's identifying certificate key, whose certificate may be authorized by an authority recognized by the payer and which identifies the recipient in a way acceptable to the payer.  This message serves as evidence that the recipient participated in the transaction.  The explanatory text can contain the reason for the payment.  It can be used to connect the recipient's signature on receipts to the recipient (see [[Finalizing Payment -> #finalizing-payment]].)

Otherwise the recipient rejects
the payment initiation with an error code.
to:
[@
{
  "payment_accept": {
    "payment_id": "393ff635-de8b-486f-b650-c4f1b151172c"
,
   "amount": 100.00,
    "units": "urn:ripple:units:CAD",
    "transaction_units": "urn:ripple:units:USD",
    "transaction_amount": 89.9326,
    "note": "Payment for auction item 1234.",
    "
recipient_routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
    "recipient_receipt_key": [public key info here],
    "recipient_certificate": [certificate info here]
  }
}
@]

This must
be signed by the recipient's identifying certificate key, whose certificate identifies the recipient in a way acceptable to the payer, such as being issued (i.e., signed) by an authority recognized by the payer.  This message serves as evidence that the recipient participated in the transaction.  Thus the signature of the recipient's receipt key on the payment receipts can be irrevocably connected the recipient, proving that the payment was indeed received (see [[Finalizing Payment -> #finalizing-payment]].  The explanatory text can contain text linking the payment to a real-world exchange of goods or services.

Otherwise the recipient rejects the @@payment_init@@
with an error code.
Added lines 1-59:
!! Payments

[[Protocol/Initializing Payment Work Page]]

To allow payments between two nodes that don't share an account, Ripple finds a path of account-connected intermediaries between the payer and recipient, and propagates IOUs along the path.

There are four stages to the payment process:

* Initializing payment between the payer and recipient nodes
* Path discovery, consisting of query messages sent out by the payer, and path-available message sent out by the recipient
* Making promises, where the payer propagates promises to redeem the payment receipt for IOUs forward down each payment path
* Finalizing the payment, where a receipt created by the payer is propagated back down the path by the recipient, and is redeemed for IOUs at each step.

'''Requesting Payment'''

A node wishing to receive a payment from another node may initiate contact with the potential payer node by sending a @@payment-request@@ message to his node's network ID:

* unique ID for the payment
* amount
* units
* payment recipient's node's network address
* authorization number (optional)
* an explanatory note

The payment request may be followed by an @@payment-init@@ message from the potential payer, or ignored.

The authorization number field may be used to contain a single-use password to pre-authorize payments, so the node can automatically make payments when it receives a request containing a password from a pre-determined list that it holds.  The payment-request message may also be authorized by signing it with a certain key, contained in the node owner's smart card, for example, for point-of-sale scenarios.

'''Initializing Payment'''

The payer node contacts recipient node and communicates the following in a @@payment-init@@ message:

* unique ID for the payment
* amount to be paid to recipient
* units of payment
* transaction units
* payment amount in transaction units
* payer's routing information
* some explanatory text to the recipient

Transaction units allow the payer to mask the true units of the payment by inventing custom units.  However, this will hinder intermediaries' ability to properly conduct zero-fee path searches.  To guarantee overall fee limits on paths, transaction units must be recognizable to the intermediaries.  See [[Path Queries -> #path-queries]].

The recipient may accept the payment initiation with an @@payment-accept@@:

* payment ID
* amount to be paid to recipient
* units of payment
* transaction units
* payment amount in transaction units
* payer's explanatory text echoed back
* recipient's routing information
* recipient's authentication key for payment (used to sign receipts)
* public-key certificate establishing recipient's identity to the payer

This must be signed by the recipient's identifying certificate key, whose certificate may be authorized by an authority recognized by the payer and which identifies the recipient in a way acceptable to the payer.  This message serves as evidence that the recipient participated in the transaction.  The explanatory text can contain the reason for the payment.  It can be used to connect the recipient's signature on receipts to the recipient (see [[Finalizing Payment -> #finalizing-payment]].)

Otherwise the recipient rejects the payment initiation with an error code.

[[Protocol/Initializing Payment Work Page]]