Skip to content

Commit 98e091e

Browse files
mkurapovmkurapov
authored
feat: simple Rafiki integration guide blog post (#203)
### Context Add simple Rafiki integration guide blog post Fixes ROP-25 ## PR Checklist - [x] Linked issue added (e.g., `Fixes #123`) - [ ] I have run `bun run format` to ensure code is properly formatted - [ ] I have verified that `bun run lint` passes without errors - [x] If blog post was added: - [ ] Ensure images have been optimised - [x] Update dates to reflect the actual publishing date when merged (file names, folder names, and frontmatter) ## Summary <!-- What has been updated and why -->
1 parent 444cc47 commit 98e091e

4 files changed

Lines changed: 148 additions & 4 deletions

File tree

‎public/img/blog/2026-03-26/responsibilites.png‎

476 KB
Loading

‎public/img/blog/2026-03-26/sequence-diagram.png‎

906 KB
Loading

‎src/content/blog/2026-03-26-rafiki-integrator-guide.mdx‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
title: 'Simple Rafiki Integration Guide'
3+
description: 'A short developer guide for integrating an Account Servicing Entity (ASE) with Rafiki.'
4+
date: 2026-03-26
5+
slug: simple-rafiki-integration-guide
6+
authors:
7+
- Max Kurapov
8+
- Timea Nagy
9+
- Dragos Palade
10+
- Tadej Golobic
11+
author_urls: []
12+
tags:
13+
- Rafiki
14+
- Integration
15+
- Updates
16+
---
17+
18+
import LargeImg from '/src/components/blog/LargeImg.astro'
19+
20+
In this guide, we provide you, a developer who's starting to integrate Rafiki with your ASE (Account Servicing Entity), a simple walkthrough for how to make your first payment using Rafiki.
21+
Here, we will introduce simple concepts, and the necessary APIs & webhook events to complete a payment between a sender and receiver at the ASE.
22+
23+
While we have detailed [documentation](https://rafiki.dev), we understand that this may be overwhelming for someone new in the ecosystem, so this guide will be a good starting point in the journey of adapting Interledger technologies.
24+
25+
First of all, let's see what an ASE is responsible for, in comparison to what Rafiki takes care of.
26+
27+
## Comparing responsibilities
28+
29+
<LargeImg
30+
src="/developers/img/blog/2026-03-26/responsibilites.png"
31+
alt="Overview of responsibilities between an ASE and Rafiki"
32+
/>
33+
34+
## Open Payments and ILP
35+
36+
### Open Payments API
37+
38+
[Open Payments](https://interledger.org/open-payments) is an API standard for allowing **third-party clients** to initiate payments between wallet addresses.
39+
40+
#### Use cases
41+
42+
- eCommerce payments
43+
- Peer to peer payments (e.g. remittances)
44+
- Recurring payments (e.g. subscriptions)
45+
46+
### ILP (Interledger Protocol)
47+
48+
[ILP](https://interledger.org/developers/get-started/) is a protocol for transferring payments (through packets).
49+
If the Open Payments API is responsible for payment authorization, then ILP is **how** the payments actually happen.
50+
51+
### Basic concepts
52+
53+
#### Wallet addresses
54+
55+
A wallet address is a sharable identifier (URL) linked to an underlying user account at an ASE, and accessible via the Open Payments API standard.
56+
57+
#### Assets
58+
59+
Assets represent monetary values, for example, country currencies. Each asset is made up of a code, and a scale to represent the decimal units. For example, US dollars can be delineated as code: `USD`, with scale `2`, where value `1000` represents `$10.00`.
60+
61+
### Integrating Rafiki with your system
62+
63+
#### Components
64+
65+
Currently, Rafiki is made up of three software components:
66+
67+
- `backend`: hosts the Open Payments resource server, ILP connector, and the Admin API
68+
- `auth`: hosts the Open Payments auth server
69+
- `frontend`: UI to manage the Rafiki resources (wallet addresses, payments, assets, e.t.c.) through the Admin API.
70+
71+
#### Admin API
72+
73+
The main entrypoint into the Rafiki system will be through the Admin API. This is a GraphQL API.
74+
75+
### Integration steps
76+
77+
#### Creating assets
78+
79+
In order to begin your Rafiki integration, you need to load the assets you will support for your users. For example, if you will be supporting US dollars, you must create an USD asset in Rafiki [through the Admin UI or Admin API](https://rafiki.dev/integration/requirements/assets/).
80+
81+
#### Creating wallet addresses
82+
83+
After creating at least one asset, you can start [creating wallet addresses](https://rafiki.dev/integration/requirements/wallet-addresses/) under that asset. This wallet address must be linked to a user account in your sytem, and will be publicly accessible through the Open Payments API.
84+
85+
#### Making payments
86+
87+
Making payments consists of three parts:
88+
89+
##### 1. Creating an incoming payment
90+
91+
First, you will need to create an incoming payment for a recipient's wallet address using the [Admin API's `createIncomingPayment`](https://rafiki.dev/apis/graphql/backend/#mutation-createIncomingPayment). This will set up a resource to pay into.
92+
93+
##### 2. Creating a quote
94+
95+
Second, you will need to create a quote for a sender's wallet address using the [Admin API's `createQuote`](https://rafiki.dev/apis/graphql/backend/#mutation-createQuote). This will show how much it will cost the sender to deliver an amount to the receiver.
96+
97+
##### 3. Creating an outgoing payment
98+
99+
Third, you will create an outgoing payment for the sender's wallet address using the [Admin API's `createOutgoingPayment`](https://rafiki.dev/apis/graphql/backend/#mutation-createOutgoingPayment). This will be the operation to actually start the payment. At this point, the ASE will need to fund/approve the outgoing payment before it gets sent.
100+
101+
##### Webhook request handling
102+
103+
When operating Rafiki, the ASE will be notified about events that happen in the system, e.g. an incoming payment was created or expired. Some of these events are actionable, for example, the outgoing payment created event. When an outgoing payment is created, the ASE will need to:
104+
105+
1. Check that the user account (for the linked wallet address) is active
106+
2. Check that the user account has enough balance to make the payment
107+
3. Reserve funds on the user account
108+
4. Notify Rafiki to approve the outgoing payment by calling the [`depositOutgoingPaymentLiquidity` API](https://rafiki.dev/apis/graphql/backend/#mutation-depositOutgoingPaymentLiquidity).
109+
110+
Once the outgoing payment has been approved/funded, Rafiki will make the payment between the sender and receiver.
111+
112+
5. If the payment in Rafiki is successful, you will receive an outgoing payment completed webhook. When this is received, you should finalize the debit of the sending user's account.
113+
6. You will also receive an incoming payment completed (or incoming payment expired) webhook. For these webhooks, you should credit the recipient's user account.
114+
115+
<LargeImg
116+
src="/developers/img/blog/2026-03-26/sequence-diagram.png"
117+
alt="Sequence diagram for payment flow"
118+
/>
119+
120+
The [Rafiki documentation](https://rafiki.dev/integration/requirements/webhook-events/) describes all of the webhook events and how they should be handled.
121+
122+
##### Note
123+
124+
When Rafiki sends a webhook to the ASE, it expects a 200 response. Otherwise, it will keep retrying.
125+
126+
<hr />
127+
128+
Hopefully, this provided you a good starting point to complete your first payment!
129+
130+
If you have other questions, we invite you to join our community [Slack channel](https://communityinviter.com/apps/interledger/interledger-working-groups-slack), and attend our [Rafiki community calls](https://github.com/interledger/rafiki?tab=readme-ov-file#community-calls) every third Tuesday of the month at 14:30 UTC.
131+
132+
## FAQ
133+
134+
### Where can I learn more about Open Payments?
135+
136+
Other than the [documentation site](https://openpayments.dev/), we have a [YouTube playlist](https://www.youtube.com/watch?v=HeH1E7mmEh8&list=PLDHju0onYcAJakrsF-I7LK_0phEqurn46) that provides an introduction and walkthrough of the API standard.
137+
138+
### What APIs are exposed publicly?
139+
140+
Open Payments endpoints + ILP connector. The Admin API must not be exposed externally.
141+
142+
### Can you make cross-currency payments?
143+
144+
In order to make cross-currency payments, you will need to create the corresponding assets, and [provide a way for Rafiki to fetch rates](https://rafiki.dev/integration/requirements/exchange-rates/).

‎src/layouts/BlogLayout.astro‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -76,16 +76,16 @@ const rawHTMLString = `This article was originally published at <a href=${frontm
7676
<time datetime={isoDate} itemprop="datePublished">{longDate}</time>
7777
<address>
7878
Written by {
79-
frontmatter.authors.map((author: string, index: number) => (
79+
frontmatter.authors.map((author: string, index: number) =>
80+
/* prettier-ignore */
8081
<span>
8182
{frontmatter.author_urls[index] ? (
8283
<a href={frontmatter.author_urls[index]}>{author}</a>
8384
) : (
8485
author
85-
)}
86-
{index < frontmatter.authors.length - 1 ? ', ' : ''}
86+
)}{index < frontmatter.authors.length - 1 ? ', ' : ''}
8787
</span>
88-
))
88+
)
8989
}
9090
</address>
9191
{

0 commit comments

Comments
 (0)