InitializingPayment

Payments

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
an explanatory note

{
  "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

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
path units (optional)
payment amount in path units
payer's routing information (optional)
some explanatory text to the recipient

{
  "payment_init": {
    "payment_id": "393ff635-de8b-486f-b650-c4f1b151172c",
    "amount": 100.00,
    "units": "urn:ripple:units:CAD",
    "path_units": "urn:ripple:units:USD",
    "path_amount": 89.9326,
    "payer_routing_id": "9a62c494-2fbb-4421-9da2-93dd93ea72b4",
    "note": "Payment for auction item 1234."
  }
}

"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 PathDiscovery.

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.

The recipient may accept the payment_init with a payment_accept:

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

{
  "payment_accept": {
    "payment_id": "393ff635-de8b-486f-b650-c4f1b151172c",
    "amount": 100.00,
    "units": "urn:ripple:units:CAD",
    "path_units": "urn:ripple:units:USD",
    "path_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 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 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.

As described in 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.

The recipient may reject the payment_init with an error code.

Initializing Payment Work Page