Skip to content

Commit de79bc8

Browse files
koekieboxkoekiebox
authored
feat: (eng-607) rafiki cards blog (#185)
## PR Checklist - [x] Linked issue added (e.g., `Fixes #eng-607`). See: https://linear.app/interledger/issue/ENG-607/technical-blog-on-rafiki-and-cards - [x] I have run `bun run format` to ensure code is properly formatted - [x] I have verified that `bun run lint` passes without errors - [x] If blog post was added: - [x] Ensure images have been optimised - [x] Update dates to reflect the actual publishing date when merged (file names, folder names, and frontmatter) ## Summary Please see the preview: https://deploy-preview-185--developers-preview.netlify.app/developers/blog/rafiki-card-integration/ > Card payments are the backbone of global commerce… trusted, regulated, and deeply entrenched. Our latest exploration asks a pivotal question: how can we bring the ubiquity of card payments into the Interledger ecosystem without compromising the security and standards of the EMV model?
1 parent c793f6b commit de79bc8

4 files changed

Lines changed: 331 additions & 0 deletions

File tree

‎public/img/blog/2025-12-31/card.png‎

218 KB
Loading

‎public/img/blog/2025-12-31/onboarding.png‎

363 KB
Loading

‎public/img/blog/2025-12-31/rotation.png‎

275 KB
Loading

‎src/content/blog/2024-12-31-rafiki-card-integration.mdx‎

Lines changed: 331 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,331 @@
1+
---
2+
title: 'From Tap to Packet: Exploring Card Payments on Interledger'
3+
description: 'A Journey from POS Onboarding to Transaction Processing.'
4+
date: 2025-12-31
5+
slug: rafiki-card-integration
6+
authors:
7+
- Jason Bruwer
8+
author_urls:
9+
- https://github.com/koekiebox
10+
- https://www.linkedin.com/in/jason-bruwer-8110766/
11+
tags:
12+
- Interledger Protocol
13+
- Card Payments
14+
- Rafiki
15+
- Updates
16+
---
17+
18+
Card payments are the backbone of global commerce-trusted, regulated, and deeply entrenched. Our latest exploration asks a pivotal question: how can we bring the ubiquity of card payments into the Interledger ecosystem without compromising the security and standards of the EMV model (standard EMV flow/state machine for an ICC/contactless transaction)?
19+
20+
![ILF + Cards](/developers/img/blog/2025-12-31/card.png)
21+
22+
[Rafiki](https://rafiki.dev/) is an open-source platform that enables Account Servicing Entities (ASEs) like banks and digital wallet providers to integrate [Interledger Protocol](/developers/get-started) (ILP) functionality into their systems.
23+
24+
## Table of Contents
25+
26+
1. [Card Payments Using Rafiki and ILP](#card-payments-using-rafiki-and-ilp)
27+
2. [Exploring a Path from EMV Cards to Interledger](#exploring-a-path-from-emv-cards-to-interledger)
28+
3. [Starting Point: Should you build a Kernel](#starting-point-should-you-build-a-kernel)
29+
4. ['Hello World' for POS (Point of Sale): How Does a POS device become "Known"?](#hello-world-for-pos-point-of-sale-how-does-a-pos-device-become-known)
30+
5. [The Transaction Moment](#the-transaction-moment)
31+
6. [Conclusion, Where This Leaves Us](#conclusion-where-this-leaves-us)
32+
7. [What is next for ILF and Cards?](#what-is-next-for-ilf-and-cards)
33+
8. [References](#references)
34+
9. [Glossary of Terms](#glossary-of-terms)
35+
36+
## Card Payments Using Rafiki and ILP
37+
38+
At a high level, an ILP card transaction involves:
39+
40+
1. Card (ICC) - EMV-compliant card with an [Open Payments](https://openpayments.dev/) enabled wallet address
41+
2. POS Device - EMV kernel + ILP extensions
42+
3. Merchant ASE - Runs Rafiki and manages POS trust (RKI, IPEK lifecycle, compliance)
43+
4. Customer ASE - Runs Rafiki and manages the cardholder account
44+
5. Interledger Network - Routes value between ASEs
45+
46+
## Exploring a Path from EMV Cards to Interledger
47+
48+
Card payments are everywhere. They are trusted, heavily regulated, and backed by decades of operational experience. At the same time, they are often locked into closed networks and bespoke integrations.
49+
50+
What we have been exploring is a simple question:
51+
_What if card payments could naturally flow into Interledger without breaking EMV_, without replacing kernels, and without weakening the security model everyone already relies on?
52+
This post is a walkthrough of that exploration - not a final specification, but a journey through the design decisions, trade-offs, and the emerging shape of an ILP-enabled card flow built around Rafiki, existing EMV kernels, and a small set of new supporting services.
53+
54+
## Starting Point: Should you build a Kernel?
55+
56+
In the world of card payments, a **kernel** is the core software component within a POS terminal that manages the complex interaction between the payment card (the chip) and the terminal. It handles the EMV protocol logic, data-exchange, and cryptographic processing required to authorize a transaction.
57+
Essentially, it is the "brain" that knows how to speak "chip card" securely and according to global standards.
58+
59+
With the kernel being the “brain” of the POS, it quickly became clear that our first major design decision would revolve around which kernel approach to build on.
60+
The earliest and most important decisions came out of conversations with our first POS (Point of Sale) manufacturing partner, who provides both the EMV kernel and a significant portion of the overall payment software stack running on the device.
61+
Because ILF's first objective is to enable SoftPOS, we needed to choose between two approaches:
62+
63+
- developing a completely new EMV kernel based on the latest EMVCo C8 specifications,
64+
- or leveraging the existing certified kernel already embedded in the payment stack (C2).
65+
66+
After evaluating the options, it became clear that reusing the existing kernel was the most practical and lowest-risk path to delivering SoftPOS quickly and reliably.
67+
68+
#### The C8 certification path would have meant
69+
70+
- Brand new certification cycles
71+
- Repeated scheme testing (Visa/Mastercard/etc.)
72+
- Long iteration loops with labs
73+
- Reviewing of the hardware and software stack
74+
75+
#### The C2 path means
76+
77+
- Existing correct EMV processing
78+
- Secure PIN entry / PAN handling out-of-the box
79+
- Already scheme compliant
80+
81+
Exploring was very clear:
82+
83+
- Use the C2 kernel
84+
- Stay as close as possible to EMVCo documentation
85+
- Avoid clever reinterpretations of kernel behavior
86+
87+
C2, while perhaps less feature-rich than newer kernels, is predictable, explicit, and specification-aligned. That predictability turned out to be far more valuable than flexibility.
88+
89+
The immediate consequence of this choice was important: ILF does not need to develop an EMV kernel.
90+
91+
Instead of re-implementing deeply complex, certification-heavy logic, we could focus on:
92+
93+
- APIs
94+
- Cryptographic boundaries
95+
- ILP and Open Payments integration
96+
- Device onboarding
97+
- Merchant management
98+
- Remote key injection (RKI) and key rotation
99+
100+
That framing shaped everything that followed.
101+
102+
## 'Hello World' for POS (Point of Sale): How Does a POS device become "Known"?
103+
104+
Before a POS can send payments into Interledger, it needs an identity. Not only a "vague" merchant identity, but a cryptographically verifiable device identity.
105+
This led us to the first building block: POS onboarding.
106+
107+
### POS Onboarding as a Trust Ceremony
108+
109+
Rather than treating onboarding as a provisioning script, we started thinking of it as a ceremony:
110+
111+
- The POS proves who it is (serial number, model)
112+
- The ASE decides whether to trust it
113+
- Cryptographic material is issued with clear ownership
114+
115+
#### Onboarding
116+
117+
The rough onboarding flow regarding keys looks like this:
118+
119+
1. The POS generates a key pair locally and sends a CSR, along with device metadata, to the ASE
120+
2. The ASE signs the CSR via its CA
121+
3. The ASE generates the IPEK (Initial PIN Encryption Key) for SRED/PIN (Secure Reading and Exchange of Data / Personal Identification Number)
122+
4. The ASE updates the terminal information to its database
123+
5. The ASE returns the signed certificate and IPEKs (TR-34) to the POS
124+
6. All keys are returned securely to the POS for storage
125+
126+
![ILP Cards, POS Key Onboarding](/developers/img/blog/2025-12-31/onboarding.png)
127+
128+
##### From this point on:
129+
130+
- The POS can authenticate itself
131+
- The ASE can verify which device is speaking
132+
- Every future request can be cryptographically tied back to onboarding
133+
134+
This turned out to be a crucial foundation, not just for transactions, but for everything else.
135+
136+
### Then Reality Kicks In: Keys Don't Live Forever
137+
138+
Once we started thinking seriously about certification (for example, MPOC), a practical requirement surfaced very quickly: _Encryption keys must be rotated regularly (at least monthly)!_ This is where things get interesting.
139+
140+
The POS is already running:
141+
142+
- POS Manufacturer bespoke software (Android / Symbian / iOS / Windows Phone)
143+
- POS kernel
144+
- POS WhiteBox (secure software-based storage and execution environment for a POS device)
145+
146+
And the POS Manufacturer already has strong opinions (for good reasons) about:
147+
148+
- Where transaction keys live
149+
- How PIN and PAN encryption happens
150+
- What software is allowed to see those keys
151+
152+
So rather than fighting that model, we leaned into it. A Crucial Piece Emerges: _Remote Key Injection (RKI) and Key Rotation!_ Instead of pushing key management into the kernel or POS logic, we introduced a new ASE-side service whose sole responsibility is key lifecycle management.
153+
Not payment processing. Not EMV logic. Just keys.
154+
155+
#### Key Rotation as a First-Class Flow
156+
157+
The key rotation (IPEK) flow looks like this:
158+
159+
1. The POS requests a new set of IPEK keys from the ASE (via the POS API)
160+
2. The POS is cryptographically verified to ensure the request can be trusted
161+
3. A new IPEK is generated and stored at the ASE
162+
4. The new keys are securely returned to the POS (TR-34)
163+
5. The POS replaces the old keys in its secure storage with the new ones
164+
165+
![ILP Cards, POS Key Rotation](/developers/img/blog/2025-12-31/rotation.png)
166+
167+
##### In this model:
168+
169+
- The POS periodically asks the ASE for a new key
170+
- The request is authenticated using the POS identity established during onboarding
171+
- The ASE derives a new IPEK inside an HSM
172+
- The key is wrapped (TR-34) and sent back
173+
- POS Manufacturer stores it inside the POS secure WhiteBox
174+
175+
A subtle but important decision here:
176+
177+
- POS TMK (Terminal Master Key) is generated and injected during POS manufacturing
178+
- Transaction keys live inside the WhiteBox
179+
- Network / ILP keys live outside the POS SDK, in the device keystore
180+
181+
This clean separation keeps:
182+
183+
- Payment cryptography in the kernels domain
184+
- ILP signing firmly under ASE control
185+
186+
At this point, the architecture started to feel "right".
187+
188+
## Cards Enter the Picture
189+
190+
With POS EMV kernel, onboarding and key rotation in place, cards themselves become almost... boring. And that is a good thing!
191+
192+
Card personalization follows standard EMV practice:
193+
194+
- Card keys are generated by the issuer (Customer ASE)
195+
- A wallet address is bound to the card
196+
- The private key lives securely on the chip
197+
198+
From an ILP perspective, the card is simply:
199+
200+
- A secure signing device
201+
- A holder of a wallet address
202+
- A producer of cryptographic proof during transactions
203+
204+
No special casing. No new assumptions.
205+
206+
## The Transaction Moment
207+
208+
When a card is presented, everything up to this point has been preparation.
209+
210+
Now the familiar EMV flow kicks in:
211+
212+
```
213+
SELECT AID
214+
GET PROCESSING OPTIONS
215+
READ RECORD
216+
GENERATE AC
217+
Optional PIN verification (Online)
218+
```
219+
220+
All sensitive operations happen:
221+
222+
- Inside the kernel
223+
- Using session keys derived from the current IPEK
224+
- With data protected by the WhiteBox
225+
226+
NB: Nothing ILP-specific leaks into this phase, by design.
227+
228+
### Crossing the Boundary: From EMV to ILP
229+
230+
Once the kernel has done its job, the POS shifts context. Now it is no longer "doing EMV", it is requesting a payment.
231+
This is where the ILP terminal key issued during onboarding finally comes into play.
232+
233+
The POS:
234+
235+
1. Assembles transaction data
236+
2. References the cards wallet address (Customer ASE)
237+
3. Signs the request with its ILP key (Merchant ASE)
238+
4. Sends it to the Customer and Merchant ASE
239+
240+
Importantly, we don't have the POS talk to Rafiki directly to authorize the transaction. Instead, we route everything through an ASE POS API:
241+
242+
Why?
243+
244+
- Authentication
245+
- Policy enforcement
246+
- Request normalization
247+
- Future flexibility
248+
- Certifications
249+
- Key management
250+
251+
The ASE remains firmly in control. Rafiki does what it already does well. From here on, Rafiki is on familiar ground.
252+
253+
It:
254+
255+
- Creates incoming and outgoing payments (as well as processing the ILP payments)
256+
- Applies Open Payments semantics
257+
- Tracks lifecycle state
258+
- Emits events
259+
The POS eventually gets a simple answer: `Approved`, `Declined` or `Failed`.
260+
261+
All the complexity stays on the backend, where it belongs.
262+
263+
### What We Learned Along the Way
264+
265+
A few themes kept repeating during this exploration:
266+
267+
- Do not fight EMV, work with it
268+
- Do not overload the kernel, extend around it
269+
- Keys define trust boundaries more than APIs do
270+
- Small, focused services are easier to reason about than monoliths
271+
- Interledger fits best when it is complementary, not dominant
272+
273+
## Conclusion, Where This Leaves Us
274+
275+
What is emerging is not a replacement for card payments, but an extension of them.
276+
277+
- Cards remain cards.
278+
- Kernels remain kernels.
279+
- ASEs remain accountable entities.
280+
281+
Interledger simply becomes the connective tissue that lets value move beyond traditional rails, securely, incrementally, and without forcing the ecosystem to start over.
282+
283+
## What is next for ILF and Cards?
284+
285+
- Further development of the Card applet for `C2` kernel support
286+
- Further development of the Rafiki APIs to support the new POS/Card services
287+
- New Merchant-API service to support ASEs with regards to:
288+
- Merchant onboarding
289+
- Terminal configuration and onboarding
290+
- Merchant management
291+
- Remote key injection (RKI)
292+
293+
## References
294+
295+
- _ADPU:_ https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit
296+
- _EMV C2 Specification:_ https://www.emvco.com/specifications/?search_bar_keywords=c-2
297+
- _EMV C8 Specification:_ https://www.emvco.com/specifications/?search_bar_keywords=c-8
298+
- _EMV C8 Specification:_ https://www.emvco.com/specifications/?search_bar_keywords=c-8
299+
300+
## Glossary of Terms
301+
302+
| Term | Description |
303+
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
304+
| `AC` | Application Cryptogram (generated during EMV processing, e.g., via "GENERATE AC") |
305+
| `ADPU / APDU` | Application Protocol Data Unit (smart card command/response format; commonly spelled APDU) |
306+
| `AID` | Application Identifier (identifies an EMV application on a card; used in "SELECT AID") |
307+
| `API` | Application Programming Interface |
308+
| `ASE` | Account Servicing Entity (e.g., a bank or wallet provider running/operating accounts and services) |
309+
| `CA` | Certificate Authority (signs certificates/CSRs) |
310+
| `CI` | Continuous Integration (automated build/test pipeline) |
311+
| `CSR` | Certificate Signing Request |
312+
| `C2 / C8` | EMVCo kernel/specification “level” referenced in the article (e.g., choosing an existing certified kernel vs. a newer certification path). These refer specifically to EMV Contactless Kernel specifications. |
313+
| `EMV` | Card payment standard originally from Europay, Mastercard, Visa |
314+
| `EMVCo` | The organization that maintains and publishes EMV specifications (EMV Cooperation) |
315+
| `HMAC` | Hash-based Message Authentication Code |
316+
| `HSM` | Hardware Security Module (secure key generation/storage/crypto operations) |
317+
| `ICC` | Integrated Circuit Card (chip card; in EMV contexts, the card itself) |
318+
| `ILP` | Interledger Protocol |
319+
| `IPEK` | Initial PIN Encryption Key |
320+
| `JSON` | JavaScript Object Notation |
321+
| `MPOC` | Mobile Payments on COTS (COTS = Commercial Off-The-Shelf; a payments/security certification context) |
322+
| `PAN` | Primary Account Number (card number) |
323+
| `PIN` | Personal Identification Number |
324+
| `POS` | Point of Sale |
325+
| `RKI` | Remote Key Injection |
326+
| `SDK` | Software Development Kit |
327+
| `SoftPOS` | Software Point of Sale (POS implemented primarily in software) |
328+
| `SRED` | Secure Reading and Exchange of Data |
329+
| `TMK` | Terminal Master Key |
330+
| `TR-34` | ANSI TR-34 key exchange / key block standard used for secure key distribution (often referenced in payments key injection) |
331+
| `URL` | Uniform Resource Locator |

0 commit comments

Comments
 (0)