This website is no longer actively supported. Please see the Ripple Developer Center for up-to-date documentation and other resources.

Services API

From Ripple Wiki
Jump to: navigation, search

Overview

The Ripple Services API provides a set of standards to provide programmatic access to Ripple oriented services. On this page, we'll focus on how Ripple clients interact with these services.

Based on the information provided through these APIs, clients can provide users with interfaces allowing them to make informed choices about the financial institutions they interact with.

Concepts

Federation protocol

Ripple uses the Federation protocol to make outbound services addressable from within Ripple. This gives everyone with a unique identifier in any system an equivalent identifier within Ripple. For example, 1BTCorg@bitcoin.mygateway.com might allow you to make a Ripple payment which gets translated to a Bitcoin payment to the Bitcoin Foundation. The payment will be routed via the bitcoin.mygateway.com Bitcoin outbound bridge.

To learn more about how federation integrates with Ripple Services, please see the corresponding sections below.

Bridges

A bridging service converts things between the Ripple network and the rest of the world. Anyone can providing bridging services, although bridges would most typically be operated by a gateway. These services can be used by Ripple clients, or any other program that speaks the Ripple Services API.

Services

Let's look at concrete services and their respective APIs.

Outbound bridges

Outbound bridges are used to transfer funds from inside the Ripple network to an entity outside the network.

A bridge is implemented as a stateful web server process which also monitors a Ripple account.

To make an outbound payment, the client must do the following:

  1. Identify the URL of the outbound bridge’s Federation API.
  2. Use the Federation Protocol to identify the destination Ripple account for the payment.
  3. Ask the bridge to generate a “quote” for the payment.
  4. Send the payment to the destination Ripple account.

When the outbound payment bridge generates a quote, it will calculate a unique "quote ID" which must be included as part of the payment. This quote ID is used to associate the Ripple payment with the earlier payment request. Note that quotes are only valid for a limited period of time.

Bridges are normally implemented by gateways because they already serve as a common point of trust for large communities. The Bitcoin outbound bridge is the only payment bridge currently in operation. Additional bridges are under development.

Making an outbound payment

Before making an outbound payment, the user must enter two pieces of information:

  • Which outbound bridge to send the payment to.
  • The account identifier for the payment destination.

For example, the user might wish to make a payment to an account identified by the ID "1074298-002" on the fictitious "quickpay" network provided by the "mygateway.com" gateway.

Once this information has been entered, the client system will follow the four-step process described above to make the outbound payment. Let’s take a closer look at each of these steps in turn.

1. Identifying the URL for the Outbound Bridge’s Federation API

Based on the combination of the desired network and the gateway to use to access that network, the client will calculate the domain name for the outbound bridge. For example, if the desired network is called "quickpay" and the selected gateway is called "mygateway.com", then the domain name might be something like:

quickpay.mygateway.com

Note that the client will need to know which domain name to use for each combination of network and gateway. This information may be hardwired into the client, or alternatively the client may allow the user to enter the domain name directly.

Using the outbound bridge's domain name, the client will retrieve the bridge’s ripple.txt file at one of the three canonical locations for that bridge, for example:

https://ripple.quickpay.mygateway.com/ripple.txt

See Ripple.txt for details on retrieving this file. This file will contain a [federation_url] section, like this:

[federation_url]
https://quickpay.mygateway.com/bridge

This is the Federation URL to use to access the outbound bridge’s implementation of the federation protocol.

2. Identifying the Destination Ripple Account for the Payment

Once the Federation URL has been obtained, the client system will send a request to this URL to resolve the account identifier entered by the user. For example, if the account identifier is "1074298-002", the following query would be issued:

https://quickpay.mygateway.com/bridge?type=federation&destination=1074298-002&domain=quickpay.mygateway.com

The parameters are as follows:

type
Indicates the type of request. This should always be the value federation.
destination
The unique identifier (account name, address, phone number, bank account number) for the desired account within the destination network.
domain
The domain name for the outbound bridge, as calculated earlier.

The bridge will return information needed to make an outbound payment to this account. This information is in JSON format, and will look something like this:

{
  "federation_json": {
    "type": "federation_record",
    "destination": "1BTCorgHwCg6u2YSAWKgS17qUad6kHmtQW",
    "domain": "quickpay.mygateway.com",

    "quote_url": "https://quickpay.mygateway.com/bridge",
    "currencies": [
      {
        "currency": "USD",
        "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
      }
    ]
  },
  "result": "success"
}

The following fields will be returned:

result
If the request was successful, this field will have the value success. Otherwise, it will have the value error.
error
A string containing the error code if the request failed.
error_message
A string containing a more detailed description of what went wrong if the request failed.
federation_json
If the request was successful, this will be an object containing information about the account and how to make a payment to it. Note that in the future this will be signed.

The federation_json object will have the following fields:

type
The type of response. This will always have the value federation_record.
destination
A copy of the destination request parameter.
domain
A copy of the domain request parameter.
quote_url
The URL to use to request a quote for sending payments to this bridge.
currencies
An optional array of currencies that the bridge will accept payments in. Each item in this array will be an object with currency and issuer fields, where currency is the 3 letter ISO-4217 code for the currency, and issuer is the Ripple address that will accept this currency.

3. Generating a Quote for the Payment

The user is then prompted to enter the desired payment amount, and optionally which currency the payment should be made in. The client will then request a quote from the outbound payment bridge, by making the following API call to the quote_url returned by the federation request:

https://quickpay.mygateway.com/bridge?type=quote&destination=1074298-002&domain=quickpay.mygateway.com&amount=1%2FUSD&source=rBWay8KRdmroZra4DTXi6h5cLtPhs5mH7v

The following parameters should be included in the request:

type
The type of request being made. This should always be the value quote.
destination
The unique identifier (account name, address, phone number, bank account number) for the desired account within the destination network.
domain
The domain name for the outbound bridge, as calculated earlier.
amount
The amount that the user wishes to send, including the desired destination currency. For example:
100/USD
Note that the "/" should be URL encoded as %2F.
source
The Ripple address of the sending user.

The bridge will return information about the requested quote. This information is in JSON format, and will look something like this:

{
  "quote": {
    "type": "quote",
    "destination": "1074298-002",
    "domain": "quickpay.mygateway.com",
    "amount": { 
       "value": "1.0", 
       "currency":"USD"
     },
    "source": "rBWay8KRdmroZra4DTXi6h5cLtPhs5mH7v",

    "destination_address": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
    "destination_tag": 2147483647,
    "invoice_id": "53b9d13866be28519870e699177080f614ded7f124c2662304e4054c2cbc90a9",
    "send": [
      {
        "currency": "USD"
        "value": "1.0",
        "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
      }
    ],
    "expires": 1383853988
  },
  "result": "success"
}

The following fields will be returned:

result
If the request was successful, this field will have the value success. Otherwise, it will have the value error.
error
A string containing the error code if the request failed.
error_message
A string containing a more detailed description of what went wrong if the request failed.
quote
If the request was successful, this will be an object containing the details of the returned quote. Note that in the future this will be signed.

The quote object will have the following fields:

type
The type of response. This will always have the value quote.
destination
A copy of the destination request parameter.
domain
A copy of the domain request parameter.
amount
A copy of the amount request parameter.
source
A copy of the source request parameter.


destination_address
Which Ripple address to send the payment to.
destination_tag
A tag value to include with the payment. We generally recommend using a fixed destination tag for each bridge operating on the same destination Ripple account; individual payments can be distinguished using the invoice_id.
invoice_id
A unique identifier for this payment. This MUST be a 256-bit value encoded as a 64-character hexadecimal string.
Examples:
invoice_id: "7b29911bf68ae3da44c38f30f06a68c732e87d0b95ecf1a5eef0b94baf904bd4"
invoice_id: "502d054c57ca2f28c9856aebce7aa090d6502bfd830bb4a4e7dbbe1f8fe19e96"
invoice_id: "fdd9293a7a82aeec0220c293f0d44c633db5f862905d7850b521c2a87ae16761"
send
The amount to send to complete this payment, in the form of an object with the following fields:
currency
The ISO-4217 currency code identifying the currency in which to send this payment.
value
The amount to send, formatted as a string.
issuer
The Ripple account ID of the issuer (optional).
expires
The date and time at which this quote will expire, as a number of seconds since the 1st of January, 1970 (Unix time).
[Question: what time zone is this in? The server’s time zone, UTC, or some other time zone?].

4. Sending the Payment

Once the quote has been generated and the user has confirmed that they accept the calculated payment amount, the client will make a Ripple payment using the process described on the Sending outgoing payments page.

The payment should be made to the Ripple address specified by the address field in the returned quote, and be for the amount (and in the currency) listed in the send field. The payment must include the destination_tag and invoice_id values associated with the quote, and the payment must be made before the given expiry time.

Pickups

For an outbound bridge payment to settle immediately, the destination has to be inside of a push-capable payment system. Some destinations may be pull-only payment systems or no payment systems at all. In that case, the bridge provider may hold the fund temporarily while they wait for the recipient to react.

An example of a pull-only payment system could be a prepaid voucher or gift card system, where the bridge provider issues a secure code that the recipient can use to claim their funds for example with a merchant.

Inbound bridges

This section is unfinished.

Gateway definition

This section is unfinished.

Use cases

Provider installation

  1. A user uses a web browser to visit the their chosen gateway.
  2. The gateway provides a link to enable bridging services.
    • Click this link to configure AcmeGateway in your Ripple wallet. This will allow you to make payments to Bitcoin addresses and send payments to anyone with an e-mail account.
  3. The user clicks the link.
  4. The Ripple wallet launches and give the user the option to configure services provided by the gateway.

Provider configuration

The user can enable and disable services at anytime.

  1. The user selects from installed providers.
  2. The wallet provides a list of available services and their status:
    • Status may be avail, not available.
    • Services may be enabled or disabled.

Provider selection

Multiple providers can be enabled for a service. The client will automatically select the best choice or provide a list of eligible providers for the user to select from.

For example, various bridge may provide outbound Bitcoin service, but the payment interface will chose the configured provider with liquidity for the currencies in the user's wallet.