We offer a standalone service for on-ramp/off-ramp or every web3 features called OwlPay Harbor, designed for easy integration into your existing systems.

OwlPay Harbor requires businesses to go through an onboarding process in order to get access to their testing and production environments. To get started with this process, reach out to [email protected]

Key Features of OwlPay Harbor

• Bank Wire Deposits: OwlPay Harbor currently supports Bank Wire services for seamless fiat deposits.
• Stellar Network Support: Our service exclusively supports the Stellar Network, providing fast and secure transactions.
• Stellar Anchor Implementation: We have implemented the Stellar Anchor specifications, including SEP-10 and SEP-24.

👍

Easy Integration

If you have already integrated with other SEP-24 Anchors, you can easily integrate OwlPay Harbor into your system.

For those who are new to SEP-24 integration, this article will guide you through the entire integration process.

Resources

• Stellar Wallet SDK Documentation : Leverage the Stellar Wallet SDK to simplify building your custom integration. Many of the code examples in this document are sourced directly from the Stellar Wallet SDK repository.
• Stellar Test Anchor TOML file : Before gaining access to OwlPay Harbor's test environment, you can utilize the SDF's test anchor while working on your integration development.
• Stellar Demo Wallet : This application provides a visual representation of the API calls required to integrate with a Stellar Anchor. (If your wallet service is not yet complete, you can use this tool to experience the interaction with OwlPay Harbor.)
• Stellar Ecosystem Proposal 24 (SEP-24) : A standardized API protocol for Stellar on- and off-ramps, implemented by OwlPay Harbor.
• Stellar Ecosystem Proposal 10 (SEP-10) : A standardized API protocol for Stellar authentication, implemented by OwlPay Harbor.

Assets

Before you get access to OwlPay Harbor, you should test your implementation with the SDF's Stellar Test Anchor. It implements the same APIs as OwlPay Harbor service but uses a different asset. The information for each asset is below.

Stellar Reference Token

This token is only on testnet.

Issuing Account: GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B
Asset Code: SRT

USD Coin

Testnet network (Test mode):
Issuing Account: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
Asset Code: USDC

Public network (Live Mode):
Issuing Account: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
Asset Code: USDC

Introduction

Applications seeking to integrate OwlPay Harbor must implement the client side of Stellar Ecosystem Proposal 24 (SEP-24), a standardized protocol defined for applications to connect to businesses such as OwlPay Harbor, more generally called anchors, that offer Stellar deposit & withdrawal services utilizing local payment rails.

This document will walk you through the necessary steps to develop a functional implementation of this standard.

Application Flow

The integration process between a Wallet Server, a Mobile Application, and OwlPay Harbor using Stellar SEP-10 for authentication and SEP-24 for handling on/off-ramp transactions.

Flow explanation

1. Wallet App:

   • The user interacts with the mobile app to initiate a transaction (e.g., deposit or withdrawal).

2. Wallet Server:

   • The app communicates with the Wallet Server, which acts as a backend service to handle authentication and transaction logic.
   • The Wallet Server performs SEP-10 authentication by connecting to OwlPay Harbor, ensuring secure identification of the user.

3. OwlPay Harbor:

   • After successful authentication, the Wallet Server requests the necessary SEP-24 transaction URLs from OwlPay Harbor. These URLs include endpoints for deposit and withdrawal transactions.

4. Transaction Flow:

   • Once the SEP-24 URL is obtained, the Wallet Server provides it to the Mobile Application.
   • The Mobile Application opens the SEP-24 URL in a browser or web view, allowing the user to complete the deposit/withdrawal process directly with OwlPay Harbor.
   • After completing step 4, through this link, users can obtain a Bank Wire Funding Account after successfully completing KYC verification in case of deposit. If you want to withdraw money, you need to take the following additional steps.

   

   
   

5. Execute an On-Chain Transfer:

   • The Wallet App initiates an on-chain transfer to the address and memo obtained in Step 4.
   • This ensures the funds are sent to the appropriate destination for processing.

6. Confirm the On-Chain Transaction:

   • The Wallet Server verifies that the on-chain transaction has been successfully processed by OwlPay Harbor.
   • This step ensures the transfer is complete and acknowledged.

7. Notify the User:

   • Once the transaction is confirmed, the Wallet App notifies the user that the funds are on their way.
     This process ensures a secure, reliable, and transparent withdrawal experience by leveraging on-chain transactions and real-time communication between the Wallet Server, Wallet App, and OwlPay Harbor.

8. This provides the user with confirmation and updates them on the progress of their withdrawal.

Summary

For withdrawals, users need to provide the bank account where they wish to receive funds. Once this information is submitted, they will receive the off-ramp withdrawal address and memo. After the funds are sent to the provided withdrawal address, the user will receive the equivalent amount in fiat currency deposited into their bank account within a few days.

SEP explanation

• SEP-10: Secure authentication protocol to verify user identity.
• SEP-24: Standardized API for handling on- and off-ramp transactions.

This process ensures that transactions are secure and follow the standardized Stellar protocols. It simplifies integration while maintaining a seamless user experience.

Let’s get started

Installing the Wallet SDK

We highly recommend using the wallet SDK to facilitate building your integration.
Find more info on the Stellar Wallet SDK Docs.

You can use yarn to install it:

$ yarn add @stellar/typescript-wallet-sdk

Authenticate

import { Wallet, SigningKeypair } from "@stellar/typescript-wallet-sdk";

const wallet = Wallet.TestNet();

// Testnet
const WP_ACCESS_HOST = "sandbox-anchor.owlpay.com";
// Pubnet
// const WP_ACCESS_HOST = "anchor.owlpay.com";

// First we create an anchor object with OwlPay Harbor home domain.
const anchor = wallet.anchor({ homeDomain: WP_ACCESS_HOST });

// Then we create the sep10 object which handles all the athentication steps.
const sep10 = await anchor.sep10();

// Finally, we authenticate using the wallet's SIGNING_KEY secret.
const authKey = SigningKeypair.fromSecret(AUTH_SECRET_KEY);
const authToken = await sep10.authenticate({ accountKp: authKey });

Initiate a Transaction

const assetCode = "USDC";
const info = await anchor.getInfo();
const currency = info.currencies.find(({ code }) => code === assetCode);
if (!currency?.code || !currency?.issuer) {
  throw new Error(
    `Anchor does not support ${assetCode} asset or is not correctly configured on TOML file`,
  );
}

// withdraw case
// Use same "anchor" object from previous step.
const { url, id } = await anchor.sep24().withdraw({
  assetCode: assetCode,
  authToken: authToken, // Use same "authToken" string from previous step
  lang: "en", // "lang" is optional, we currently only support en
  withdrawalAccount: FUNDS_STELLAR_KEYPAIR.public_key,
  extraFields: {
    // "amount" is optional for non-custodial wallets and mandatory for custodial wallets
    amount: "<amount to withdraw / cash-out>",
  },
});

// deposit case
// Use same "anchor" object from previous step.
const { url, id } = await anchor.sep24().deposit({
  assetCode: assetCode,
  authToken: authToken, // Use same "authToken" string from previous step
  lang: "en", // "lang" is optional, we currently only support en
  destinationAccount: FUNDS_STELLAR_KEYPAIR.public_key,
  extraFields: {
    // "amount" is optional for non-custodial wallets and mandatory for custodial wallets
    amount: "<amount to withdraw / cash-out>",
  },
});

After successfully getting the URL, the webpage content will probably look like this:

Binding transaction status has changed

When a user completes a transaction on the interface provided by OwlPay Harbor, the transaction status is updated by OwlPay Harbor. To retrieve the latest status, the application must perform polling to check for updates.

// While the Watcher class offers powerful tracking capabilities, sometimes
// it's required to just fetch a transaction (or transactions) once. The Anchor
// class allows you to fetch a transaction by ID, Stellar transaction ID, or
// external transaction ID like illustrated below.

// "id" is the actual Anchor transaction id, all transactions should have it.
const transaction = await anchor.sep24().getTransactionBy({
  authToken,
  id: transactionId,
});

// "stellarTransactionId" (aka "stellar_transaction_id" on the SEP spec)
// is the hash of the Stellar network transaction payment related to this
// Anchor transaction.
// The "stellarTransactionId" has a SHA256 hash format like the below:
// - "a35135d8ed4b29b66d821444f6760f8ca1e77bea1fb49541bebeb2c3d844364a"
// E.g. we'll only have this transaction id field AFTER the wallet sends funds
// to Anchor on the withdrawal flow or receives funds from Anchor on the
// deposit flow.
const transaction = await anchor.sep24().getTransactionBy({
  authToken,
  stellarTransactionId,
});

// "externalTransactionId" (aka "external_transaction_id" on the SEP spec)
// could refer to some ID of transaction on external network.
// E.g. for MoneyGram this is the "reference number" displayed to the user on
// the last step of MoneyGram's UI which the user should then use on a physical
// MoneyGram location to complete the cash out operation and pick-up the money.
const transaction = await anchor.sep24().getTransactionBy({
  authToken,
  externalTransactionId,

Here are the possible states and transitions for an order:

The status changes are as follows:

Monitor on-chain addresses receiving assets

The application side should handle deposit(on-ramp) and withdrawal(off-ramp) status updates.

📘

OwlPay Stellar Monitor API

If you don't have any idea on monitor on-chain transaction? OwlPay Stellar Monitor can help wallet services more easily monitor on-chain addresses receiving assets, you can contact your customer support team to get this API information.

Important Notes for Withdraw (Off-Ramp):

1. Provide On-Chain Transfer Information

   • When the status changes to pending_user_transfer_start, you need to provide the user with the necessary on-chain transfer information.
   • Ensure the user does not incorrectly input the address and memo.
   • The most robust approach is for the application to pre-fill the relevant parameters, requiring the user to simply review, sign, and confirm the transaction.

2. Temporary pending_anchor State

   • There may be a brief period where the transaction remains in the pending_anchor state.
   • During this phase, OwlPay Harbor performs customer due diligence (KYC/AML checks) for each transaction.

By following these guidelines, you can ensure a seamless and secure experience for your customers during the deposit and withdrawal processes.