RippleNet Home quick start

This quick start is a hands-on tour of RippleNet Home’s most-used features. Its walkthroughs introduce you to the RippleNet Home pages, show you how different features work, and give you an overall feel for how you might work with RippleNet Home.

If you want a conceptual overview of RippleNet Home before you start, read the RippleNet Home Overview.

Setup

You can, if you’d like, just read through this guide and follow the walkthroughs without trying them. To run through the examples, though, you need a RippleNet Home user account and a safe environment for the examples.

User accounts

You need a RippleNet Home user account before you can use RippleNet Home. When a Ripple customer partner engineer first sets up RippleNet Home for an institution, they create a single admin account for an administrator within the institution. The administrator can create additional accounts for other users. If you don’t have an account you’ll need to ask your administrator to create one for you. If you are that administrator, Create a user and set permissions shows how to create a new user.

Sign in

Once you have a RippleNet Home account, you can sign in to RippleNet Home.

Environment

It’s important as you experiment with RippleNet Home that you don’t carry out actions that have unwanted real-world consequences. RippleNet Home provides three environments to support experimentation and testing outside of real-world operation:

• Test provides a version of RippleNet Home and its surrounding elements that your institution’s developers use to integrate RippleNet with your institution. The environment can change regularly as integration proceeds, and has no real-world consequences.
• UAT provides a version of RippleNet Home and its surrounding elements that are as close as possible to the real instance used to carry out real-world actions. User acceptance testing takes place in this environment. It’s typically more stable than the Test environment. You can carry out activities here such as payments. They look like they work, but they don’t actually execute in the real world.
• Production is the real-world implementation of RippleNet Home , executing in the real RippleNet, carrying out actions with real-world consequences such as the transfer of real funds.

Choose a safe environment before experimenting. Test is usually a good choice, Production is not.

Whenever a RippleNet Home page offers activities that can take place in different environments, you’ll see an environment dropdown at the top of the page. Use it to choose the environment in which you want to work.

Some activities, such as managing RippleNet Home users, occur in all environments so there’s no environment choice on a page offering these activities. These activities have real-world consequences, but you can usually undo them (by deleting a test user for example).

Create and manage user accounts

This first walkthrough is for administrators only: you must have a RippleNet Home admin account to have the permissions necessary to create and manage RippleNet Home users.

Create a user and set permissions

To create a user, work with the New Users page:

1. Select Settings in the left nav bar to view the Settings page.
2. Select Users to view the Users page.
3. Select New User in the upper right corner to view the New User page.

4. Fill in basic information for the new user: First Name , Last Name , and Email address.

   Note

   The email address is the permanent username for this account. RippleNet Home uses this address to contact the user and set up a password.

5. Choose a User Type .

   An institution can only have five Organization Administrator accounts with full permissions for RippleNet Home (including user management). All other user accounts are Regular User accounts with permissions set by an administrator.

6. To set common permissions for a regular user account, start by choosing a permission set that most closely describes the type of activities the users will perform: Select one of the four permission set buttons.

   RippleNet Home turns on the permissions granted for that permission set.

7. To modify a set’s permissions, select the checkboxes for permissions you want to turn on or off.

   Note

   If you don’t want to begin with a permission set, you can set permissions from scratch by selecting checkboxes of permissions you want.

8. To create your new user, select Save User at the bottom of the page.

   RippleNet Home displays the Users page and lists your new user.

Whenever you create a new user, your RippleNet instance sends email to the user with both a link for RippleNet Home access and instructions for setting up a password. It’s up to the new user to create their new account using the emailed credentials.

Edit a user account

You can edit an existing user account from the Users page where users are listed:

1. Select Settings in the left nav bar, then the Users option on the Settings page.
2. Find the user you want to modify, select the more options icon on the right of the user account entry, and choose Edit User to open the Edit User page.
3. Set revised account parameters the same way you set them when creating a new user.

   Note

   You can’t change the email address. It must remain the same for authentication purposes.

4. Select Save User to put your account changes into effect.

You can delete a user account by choosing Delete User from the more options menu.

View RippleNet accounts

RippleNet transactions require RippleNet accounts for sending and receiving funds. RippleNet Home provides a view of these accounts: your own RippleNet accounts in your RippleNet ledger, or RippleNet accounts set up for you by connected partners and exchanges in each of their respective RippleNet ledgers.

The Accounts page displays RippleNet accounts associated with your institution. It has three tabs:

• My Ledger displays RippleNet accounts owned by your institution, recorded in your institution’s RippleNet ledger.
• Disabled displays disabled accounts owned by your institution that can no longer carry out transactions.
• Partner Ledger displays RippleNet accounts that you own (they contain your funds) and are maintained by your connection partners and recorded in the partners' own RippleNet ledgers.

To view these accounts:

1. Select Accounts in the left nav bar to view the Accounts page.
2. Select an account type tab to see the type of accounts you want to view: yours ( My Ledger ), your partners' ( Partner Ledger ), or your disabled accounts ( Disabled ).
3. Select an account name to view information for that account.

   

RippleNet Home offers different account information and options depending on where you view the account:

• For an account in your RippleNet ledger, select the account name to display an historical list of transactions for the account.

  The account page also offers buttons (Redeem Funds and Fund Account) that carry out funds transfers between your accounts. The Edit button lets you change account parameters, and the further options menu offers a Disable Account command that disables an account.

• For an account in a partner’s RippleNet ledger, select the account name to display the account’s parameters and a list of transactions with the account.

Get connection information

Ripple customer partner engineers set up connections between your instance and the instances of your institution’s partners and digital asset exchanges. Once those connections are in place, you can view information about your connections through RippleNet Home.

View connection health

The RippleNet Home page displays the health of your connections to partners:

• Select Home in the left nav bar to view the RippleNet Home page.

The health card in the middle shows the heartbeat status of each of your partners' RippleNet instances displayed below the heartbeat of your own instance.

View connection information

The Connections page displays connection information for both partners and exchanges:

1. To view the Connections page (which is first set to the Partners tab), select Connections in the left nav bar.

   

2. To view details about a partner connection, select the partner link in the Company Name column.

   RippleNet Home displays the partner institution's details including country of operation, supported currencies, available RippleNet features, contacts, and more.

   

3. To view the partner’s RippleNet payment object (RPO) schemas, select the RPO Schemas tab.

   RippleNet Home displays the receiving partner’s available RPO schemas, and a Request Access button for schemas in which you’re interested. Receiving institutions publish RPO schemas that specify payment information required whenever a sending institution sends a payment.

   

4. To view details about an exchange, return to the Connections page and select the Exchanges tab.

   RippleNet Home displays your connected digital asset exchanges.

5. Select Details in an exchange card.

   RippleNet Home displays the exchange’s details.

   

View payments

Some institutions set up middleware that uses the RippleNet API to make and receive payments through their RippleNet instance. Automation through the API can handle hundreds or many thousands of payments a day. Other institutions make a few manual payments each day through RippleNet Home. Automatic activity through the API sometimes needs human supervision to ensure that nothing goes wrong with payments and, if something does go wrong, to track down and troubleshoot payment problems. Troubleshooting tools also help with manual payments made through RippleNet Home.

The Payments page displays all payments sent and received through your RippleNet instance, one payment per line. You can look at the details of any one of those payments, a useful aid for checking status or troubleshooting.

Filter payments

Because there can be many, many thousands of payments recorded for your RippleNet instance, RippleNet Home lets you filter to a manageable subset of payments.

1. Select Payments in the left nav bar to view the Payments page.
2. Select the filter button (the funnel icon in the upper right of the page) to open the Filters form where you can specify payment filters.

   

   The filter fields are:

   • Sender End-to-End ID : an ID value created in a payment’s RPO as part of contract values. This value is created and found within a payment’s RPO. You can view an RPO to get this value as described below.
   • Internal ID : not currently used.
   • Payment ID : the unique ID for a single payment.
   • Payments Created After : a date that specifies payments to filter out. All payments before this date are filtered out.
   • Sending Host : the payment sender’s RippleNet address.
   • Sending Account : the name of the account sending the payment.
   • Receiving Host : the payment receiver’s RippleNet address.
   • Receiving Account : the name of the account receiving the payment.
   • Currency : the currency sent or received, an international currency code specified in the ISO specification for currency codes .
   • Minimum Amount : the minimum amount of payment. All payments below this amount are filtered out.
   • Maximum Amount : the maximum amount of payment. All payments above this amount are filtered out.
   • Currency/Amount Type : Whether the specified currency is for payment received or payment sent.
   • Payment State : the current status of the payment, a set of values that includes Quoted, Executed, Failed, Returned and others.
   • Payment Type : Regular (an initial payment) or Returned (a payment created to return an initial payment).
3. Once filters are set, select Apply Filters to filter down to a smaller set of payments.

View payment details

RippleNet Home can present the details of any single payment. To view a payment’s details:

1. Select the payment ID. It appears in the payment listing on the Payments page.

   RippleNet Home displays the flow of funds, status, and a graphic representation of the transition of payment states.

   

2. Select the Payment Object JSON tab to see a JSON file containing the payment’s RippleNet payment object (RPO).

   

   The RPO contains full details about how the payment was defined, handled, and its status.

3. Select the Event Trail JSON tab to see a JSON file describing the series of events created as RippleNet handled the payment.

   

Set up RippleNet integration

RippleNet Home offers critical tools for integrating your core banking system with RippleNet through middleware that uses the RippleNet API. These tools define an API allowlist and create and manage API credentials.

Define an IP allowlist

Your institution’s middleware connects to your RippleNet instance to carry out activities through the RippleNet API. For security purposes, the RippleNet instance maintains an allowlist of IP addresses that may connect to the instance.

To define the IP addresses in an allowlist:

1. Select Settings in the left nav bar to open the Settings page.
2. Select RippleNet Cloud IP Allowlist to open the RippleNet Cloud IP Allowlist page.

   

3. Select New IP Allowlist Address in the upper right to open the New RippleNet Cloud IP Address page.
4. Enter an IP address in the dialog box and select Save . The address should be in dotted quad format.
5. Select Save .

   RippleNet Home adds the address to the allowlist and displays the current allowlist.

To edit or delete an existing IP address, select the more options icon in the address listing.

Manage API credentials

RippleNet API calls require Bearer authentication tokens that you retrieve from the authentication operation using API credentials. You can create and rotate these credentials up to a maximum of three credentials per environment:

1. Select the environment for which you want credentials by using the environment dropdown at the top of the page.
2. To open the Settings page, select Settings in the left nav bar.
3. To open the API Credentials page, select API Credentials .

   

4. To open the New RippleNet Cloud API Credential page, select New Credential in the upper right.
5. Enter a name for your new credential.
6. To create your new credential, select Save & Generate Key .

   RippleNet Home presents a dialog box with the client ID and audience that you’ll use with the credential along with the credential.

   

7. Copy the credential and store it in a secure location (typically a vault) to use with API calls. You won’t be able to view it again.
8. To finish credential creation, select Close .

   The new credential appears on the API Credentials page.

9. To rotate a credential—that is, to delete the old credential value and generate a new one—choose Rotate Credential from the dropdown menu in the credential card and confirm your choice.

   RippleNet Home presents a dialog box with the client ID and audience that you use with the credential along with the credential.

10. Once again, copy the credential and store it in a secure location because you won’t be able to view it later.