Integration
Última revisión: 23 oct 2026
Esta página aún no está disponible en tu idioma.
- Install the latest version of Docker Compose.
- Set up a Local Playground using Rhyza’s Compose file.
- Review the integration configurations.
- Use the integration checklist.
Rhyza must be configured to support at least one asset. An asset represents an item of value, such as the US dollar, that can be transferred via the Interledger Protocol. Assets are added through the Admin API’s Create Asset endpoint.
Every Interledger payment is preceded by a rate probe to create a quote. The quote estimates the full cost of transferring value.
Rhyza supports two models for obtaining exchange rates.
- Push model - The FSP sets exchanges rates in Rhyza
- Pull model - The FSP hosts an external endpoint for Rhyza to query
Rhyza scopes exchange rates in one of two ways. Both push and pull models support either scope.
- Peer rate scope - Applies only to payments made through a specific peer, identified by
peerId - Intra-FSP rate scope - Applies FSP-wide to any conversion between two given asset codes, independent of peer
Peer and intra-FSP rates for the same asset pair are set, cached, and expired independently of one another. Both can be active for the same pair at the same time.
In this model, the FSP sets exchange rates in Rhyza directly via the Admin API’s Set Exchange Rate endpoint. Including a peerId in the payload sets a peer rate. Omitting it allows the FSP to set an intra-FSP rate for the asset pair instead.
In this model, Rhyza requests exchange rates from the FSP whenever a rate is needed but unavailable in its local cache. To enable the pull model, the FSP must define their exchange rate endpoint in their configuration/manifest file.
The FSP’s endpoint must accept GET requests. Rhyza always includes the base asset code as a query parameter. When Rhyza needs a peer rate, rather than the intra-FSP rate, Rhyza will include a peerId query parameter identifying the peer.
The endpoint must return a JSON response containing the base asset and a mapping of exchange rates for other supported assets.
GET https://cloud-nine-wallet/rates?base=USDGET https://cloud-nine-wallet/rates?base=USD&peerId=480ef339-7842-4501-a905-923fc1339cef{ "base": "USD", "rates": { "EUR": 0.813399, "MXN": 17.05 }}Because peer and intra-FSP rates are cached separately, expiry of one doesn’t affect the other and each is refreshed (via the pull model) or re-pushed independently.
Pulled rates are refreshed proactively in the background shortly before they expire. A payment or quote won’t be delayed waiting on a live pull.
The FSP can specify how long Rhyza caches exchange rates in their configuration/manifest file. Caching improves performance by reducing the number of outgoing requests to the FSP’s rates endpoint.
Pushed rates are not refreshed in the background. The rateTtlSecs provided in the Admin API’s Set Exchange Rate endpoint determines the lifetime of the specific rate. Once a pushed rate’s rateTtlSecs elapses, it’s only replaced the next time that rate is requested, at which point Rhyza falls back to the pull model synchronously.
If the pull model isn’t configured or also fails to provide a rate, Rhyza will fail the payment or quote request with an error.
An IdP integration is required by Rhyza’s Open Payments authorization service and to support Open Payments outgoing payments.
An IdP, or identity provider, is a system or service that stores and manages user identity information, authentication, and consent for an FSP’s customers.
The IdP will call the internal Identity Provider Service API to look up grant details for an in-progress interaction and to record the user’s accept/reject decision.
For two FSPs to exchange Interledger payments with each other, they must be peers.
Peering relationships are created by calling the Admin API’s Create Peer endpoint.
Before becoming peers, both FSPs must:
Run an Interledger connector
Rhyza ILP connectors know how to speak to each other. It’s recommended that
both FSPs use Rhyza.
Agree on an asset
Both FSPs must agree on an asset to use for the
peering relationship. Peers can set up multiple peering relationships with
each another based on different assets. At least one common asset must be
added to both FSPs’ Rhyza instance before setting up the peering relationship.
Exchange static Interledger (ILP) addresses
An FSP’s
is self-assigned during Rhyza setup and stored locally in the FSP’s configuration/manifest file.
Communicate a connection endpoint
The connection endpoint is a URL that the other peer will send Interledger
packets to.
Exchange auth tokens for the connection endpoint
Incoming and outgoing authtokens allow peered FSPs to authenticate packets
to ensure they originated from each peer’s Interledger connector and weren’t
tampered with en route.
Agree on a settlement mechanism
The settlement mechanism that two peers agree to use is what facilitates the
transfer of actual funds between them. Settlement mechanisms are not
provided by Interledger, Open Payments, or Rhyza.
Each payment account belonging to an FSP’s customer must be associated with at least one wallet address for the account to send and receive payments over Interledger and Open Payments.
Wallet addresses are created and hosted in Rhyza. However, the mapping of a wallet address to a customer’s account stays with the FSP and is never stored in Rhyza’s database tables.
The base wallet address is the portion of the address that will be the same
for all customers. For example, https://wallet.example.com.
The base wallet address URL comes from the configured Open Payments resource server base URL. Because wallet addresses are stored and resolved by pathName only, that base URL can be changed after deployment without migrating existing wallet address records.
This step defines the structure of what comes after the base wallet address. Addresses are treated as case-insensitive, meaning that both lowercase and uppercase variations of the same address are recognized as identical. FSPs should consider whether their chosen structure could disclose personal data.
Harder to guess account ownerhttps://wallet.example.com/nickname
Easier to guess account ownerhttps://wallet.example.com/firstname.lastnameCreate wallet addresses with a bare pathName only (for example sarah). The Admin API builds the public wallet address URL from the Open Payments resource server base URL plus that pathName. Values containing / or :// are rejected.
Wallet addresses are created one-by-one by calling the Admin API’s Create Wallet Address endpoint. To bulk-assign wallet addresses to existing customers, the FSP should write a script that calls the Create Wallet Address endpoint and loops through their list of accounts.
The FSP must expose a webhook endpoint that listens for events dispatched by Rhyza.
When an event is received, the FSP can react accordingly. For example, if the FSP receives a payment.created event but the sender has insufficient funds, the FSP can cancel the payment by calling the Admin API’s Cancel Payment endpoint.
If requests to credit or debit user accounts are lengthy processes, we
recommend using a worker to process received events. The worker allows the
server to process events at a rate suitable for the FPS’s system and reduces
the number of failed/retried events since the event listener can immediately
reply with a successful 200 status.
Rhyza retries a webhook request at increasing intervals if the request times
out or if a non-200 status is returned. By default, the first retry occurs
after 10 seconds. Additional retries occur after 20 more seconds, then after
30 more seconds, and so on. Rhyza continues to retry until it receives a
200 status.
| Required? | Action |
|---|---|
| ✅ | Be a licensed financial service provider (FSP) in the jurisdictions in which they operate. |
| ✅ | Integrate with an identity provider (IdP) and define a content security policy (CSP). |
| ✅ | Add at least one asset to Rhyza. Do this before setting up wallet addresses. |
| ✅ | Set up and assign wallet addresses. |
| ✅ | Expose a webhook endpoint and understand how to handle each webhook event. |
| ✅ | Secure their admin services from external access. |
| ⚠️ | Add a peer. |
| ⚠️ | Provide exchange rates. |