A non-technical guide to integrate with Stellar and ClickPesa’s assets
Integration with assets on the Stellar network is open to any party due to Stellar’s open network. There is detailed documentation and sets of standards defined by the Stellar Development Foundation (SDF) and Stellar Community to make integration easier. Below is a summary given to give interested parties an overview from a non-technical perspective on how to integrate our assets within your application. In this overview we assume that you have your own application.
Having your application interacting with assets on the Stellar network requires a couple of steps, find here the breakdown:
1. Stellar Integration
Having our assets within your application requires integration with the Stellar network. Integration with the Stellar network requires first a general understanding how the network works and how it can fit into your overal business (and further down application). We recommend every party to commit time to have good understand about Stellar prior doing integrating.
Below is an outline of the Stellar network definitions and setup:
Stellar Core
The Stellar Core tracks and adds transaction sets to the Stellar ledger. The Stellar Core is the basically the backbone of the Stellar network and does the hard work of validating and agreeing on the status of every transaction with other instances.
Horizon
Horizon is an API layer on top of the Stellar Core that allows access to submit transactions and query network data.
Testnet and public
There are two different versions of the Stellar network: one for testing (testnet) and one for real-world deployments (public). SDF provides a free public Horizon instance for each, which developers can use to submit transactions or query network data.
Assets
Assets on the Stellar can be issued by any party. Assets often represent a value in the world (currency, metal, bonds, cryptocurrencies issued on another blockchains, stocks, etc). Once you have found an asset to work with within your application, it is important to understand if it fits your use case. Also important to understand is that not every asset has an on/off ramp or has the defined setup in place.
Wallets / Accounts
Stellar wallets / accounts are there to hold the assets on the Stellar Network. To work with assets in your application, you need to setup one or multiple wallets / accounts depending on your use case. A wallet can do certain operations, think of a payment, buy/sell offer etc.
Anchor
An anchor acts as a “bridge” between the real world and Stellar world for a particular asset. An anchor offers the capability to purchase and sell an asset on the Stellar network for an equivalent value in the real world. An anchor is often the issuing party of the asset, however this is not always the case.
Trustlines
Trustlines are added to a Stellar wallet / account to hold an asset as well as specify the maximum amount of that asset willing to hold. Trustlines also avoids receiving unwanted assets.
DEX
The Stellar network has an in-built exchange that allows a wallet/account to trade assets on the network. This is done via the operation buy/sell offer, which basically let a wallet/account place an order to sell or buy an asset. Important to understand is that the exchange has middle party in between, which makes it a decentralized exchange. Trading on the Stellar can be done almost without any cost.
2. Integrating an asset
By now you and your technical team understand how the Stellar network works, how it fits in your business and how to integrate it within your application. In this chapter we look closer on how to interact with an asset.
Interaction with an asset happens always through a wallet / account on the Stellar network, this can be your company’s wallet or a user’s wallet (custodial or non-custodial). You have to decide whether you want the wallet customer facing, for example by providing an actual wallet within your application. Or if it sits within the backend of your application, for example a remittance use case. Secondly also think if you want to store the wallet secret key within your application (custodial) or directly in the hands of your user (non-custodial).
A wallet can receive an asset in a couple of ways, apart from receiving an asset from another wallet or using the DEX, you can use on/off ramp offered by anchors to obtain an asset. This on/off ramp functionality you, as a third party, can embed within your application and let it interact with wallet(s)/account(s) implemented within your application. This means that your wallet or user’s wallet can use the on/off ramp functionality to obtain assets.
There are three options in how your customers interact with anchors to on/off ramp assets. Each option caters towards a certain use case. These three options are each separately defined by SDF in a SEP (Stellar Ecosystem Proposal). A SEP defines a standard way for anchors and wallets to interact on behalf of users. Apart from these three SEPs, there is a set of basic SEPs. We will first have a look at these basic SEPs;
SEP-10 Authentication
This SEP defines the standard way to create authenticated web sessions on behalf of a user who holds a Stellar wallet/account.
This link gives more explanation SEP-10, the second half existing out technical things, share that technical part with your developer.
SEP-9 KYC Fields
This SEP defines a list of standard KYC and AML fields for usage by other SEPs.
This link gives more explanation SEP-9, the second half existing out technical things, share that technical part with your developer.
SEP-12 Customer/KYC Registration
This SEP defines a standard way for third party applications to upload KYC (or other) information to anchors and other services. Basically, SEP-12 is used to communicate customer information whereby SEP-9 is used to define the fields in a standard and uniform way.
This link gives more explanation SEP-12, the second half existing out technical things, share that technical part with your developer.
Having understood SEP-10, SEP-9 and SEP-12 we can now have a look at the three SEP options in how your customers interact with anchors to on/off ramp assets. The basic SEPs are utilized by the three SEPs listed below;
SEP-24 Interactive Anchor / Wallet Asset Transfer Server
In short with SEP-24, users interact with the interface of an anchor when obtaining / purchasing an asset. Think of a popup screen to obtain an asset, analogous to a Paypal Checkout Popup.
An anchor collects KYC information from the user. Your app does not have to collect KYC information required. This saves you implementation of SEP-12 as that is the standard that communicates the KYC. However, a reason not to implement SEP-24 is that your app allows an anchor to temporarily control the UX with the popup..
This link gives more explanation SEP-24, the second half existing out technical things, share that technical part with your developer.
Required SEP: SEP-10
SEP-6 Anchor Client Interoperability
In short with SEP-6, users only interact with the UI of your application. You transfer the information to the anchor via the backend only. The UI/UX is analogous to a Stripe API Integration.
Your app collects KYC information from the user. Beforehand you need to know what KYC information to collect. Once you collect this KYC information you need to send it over through the KYC communication format SEP-12. How each KYC field needs to be defined can be found in SEP-9. Important to understand is that KYC information of customers needs to be sent and approved prior to any transaction being made. Sometimes the KYC checks anchors want to run takes a while, especially for b2b payments, and they want to be able to onboard users ahead of a transaction.
This link gives more explanation SEP-6, the second half existing out technical things, share the technical part with your developer.
Required SEP: SEP-10, SEP-9, SEP-12
SEP-31: Cross-Border Payments API
In short, SEP-31 is a standard for enabling payments between two financial accounts that exist outside the Stellar network. This is analogous to a remittance use case where the user does not hold the funds. Usually your own wallet is used instead of your users holding a wallet.
Unlike SEP-24, which allows any compliant wallet to discover and interact with any compliant anchor, SEP-31 requires anchors to create bilateral agreements in advance to interoperate with one another: when you build an SEP-31 integration, you identify the counter parties with whom you will transact, and log the addresses of their Stellar wallets. There will need to be am agreement between sender and receiver anchors of how the transaction takes place.
This link gives more explanation SEP-31, the second half existing out technical things, share that technical part with your developer.
Required SEP: SEP-10, SEP-9, SEP-12
Depending on your use case, pick the right standards to integrate with. We highly recommend reviewing all documentation out there to have a good understanding of how and what you need for your use case before starting with any integration.
Ready? Let’s go to the next step.
3. Testing with assets
Once your technical team has integrated these standards, you are ready to test on the testnet environment. Assuming that you have chosen to integrate with one or more of ClickPesa’s assets, you can reach out to service@clickpesa.com with explanation of your app, your testnet wallet/account address and the amount you want to receive. Whereby we make sure you receive the amount of assets to test with. Make sure this account/wallet has setup a trustline prior.
4. Going live with assets
Once successfully passed testnet (and live testing), congratulations you are ready to launch. Now your users can interact with real assets, in this case there are 3 ways you or users can buy our assets on mainnet:
- DEX (use any app that interact with the DEX)
- SEP-6 / SEP-12 used on another third party application such as (Lobstr.co).
- OTC purchase (above $5000) by reaching out to service@clickpesa.com
Integration Assistance Program
For parties interested in extra assistance with scoping the integration or actual integration, we have an integration assistance program. You can reach out to info@clickpesa.com with the following information:
1. KYC
2. Use case description
3. Provide which standard you would like to use
We will do an in-take once receiving the information. After this, in-take a folder and communication channel will be set up and help will be provided.
