Skip to main content

Off-Ramp Native Flow Integration

Web with SDK

To enable native flow, configure the widget with a useSendCryptoCallback parameter set to true.

You can subscribe to the SEND_CRYPTO event as mentioned here.

To submit the SEND_CRYPTO_RESULT event back to the widget you should use onSendCrypto method provided by the SDK.

iOS with SDK

To enable native flow, configure the widget with a useSendCryptoCallback parameter set to true.

Use delegate method to be notified about offramp sale:

public protocol RampDelegate {
// ...
func ramp(_ rampViewController: RampViewController, didCreateOfframpPurchase purchase: OfframpPurchase, _ purchaseViewToken: String, _ apiUrl: URL)
}

public struct OfframpPurchase: Decodable {
public let id: String
public let createdAt: String // ISO date-time string
public let crypto: Crypto
public let fiat: Fiat

public struct Crypto: Decodable {
public let amount: String
public let assetInfo: AssetInfo

public struct AssetInfo: Decodable {
public let address: String? // 0x-prefixed address for ERC-20 tokens, `null` for ETH
public let symbol: String // asset symbol, for example `ETH`, `DAI`, `USDC`
public let chain: String
public let type: String // asset type & network, e.g. `ETH`, `ERC20`, `MATIC_ERC20`
public let name: String
public let decimals: Int // token decimals, e.g. 18 for ETH/DAI, 6 for USDC
}
}

public struct Fiat: Decodable {
public let amount: Double
public let currencySymbol: String // description of the purchased asset (address, symbol, name, decimals)
}
}

Use delegate method to inform widget about the submitted crypto:

public protocol RampDelegate {
func ramp(_ rampViewController: RampViewController, didRequestOfframp payload: SendCryptoPayload, responseHandler: @escaping (SendCryptoResultPayload) -> Void)
}

public struct SendCryptoPayload: Decodable {
public let assetInfo: AssetInfo
public let amount: String
public let address: String
}

public struct SendCryptoResultPayload: Encodable {
let txHash: String?

public init(txHash: String? = nil) {
self.txHash = txHash
}
}

txHash: String - transaction hash (nullable)

Android with SDK

To enable native flow, configure the widget with a useSendCryptoCallback parameter set to true.

Implement onOfframpSaleCreated method in the RampCallback object, to be notified about the offramp transaction:

val callback = object : RampCallback {
...

fun onOfframpSaleCreated(
sale: OfframpSale,
saleViewToken: String,
apiUrl: String
){
...
}
}

Parameters:

data class OfframpPurchase(
val id: String,
val createdAt: String, // ISO date-time string
val crypto: Crypto,
val fiat: Fiat
)

data class Crypto(
val amount: String,
val assetInfo: Asset, // description of the purchased asset (address, symbol, name, decimals)
)

data class Fiat(
val amount: Double,
val currencySymbol: String, // description of the purchased asset (address, symbol, name, decimals)
)

data class Asset(
val address: String? = null, // 0x-prefixed address for ERC-20 tokens, `null` for ETH
val symbol: String, // asset symbol, for example `ETH`, `DAI`, `USDC`
val name: String,
val decimals: Long, // token decimals, e.g. 18 for ETH/DAI, 6 for USDC
val type: String // asset type & network, e.g. `ETH`, `ERC20`, `MATIC_ERC20`
)

Use onOfframpCryptoSent method to inform widget about the submitted crypto:

onOfframpCryptoSent(txHash: String? = null, error: String? = null)

txHash: String - transaction hash (nullable) error: String - error message (nullable)

Example:

 rampSDK.onOfframpCryptoSent(txHash)

Non-SDK

It is possible to integrate native flow without the SDK. In order to do that:

  • make sure to use the webview (webview-desktop or webview-mobile) variant
  • specify the query param useSendCryptoCallbackVersion as 1 in the widget URL
  • handle window post-messages on your own

You can find our recommendations on the implementation and links to examples from our SDK below.

iOS without SDK

Recommended webview component:

WKWebView

Subscribing to events:

post-message events are sent by the widget to RampInstantMobile object. Example from the SDK.

Sending events to the widget:

could be done by invoking evaluateJavaScript method on webview instance and passing window.postMessage(STRINGIFIED_EVENT) script. Example from the SDK.

Android without SDK

Recommended webview component:

android.webkit.WebView

Subscribing to events:

post-message events are sent by the widget to RampInstantMobile object which could be configured by setupWebView function like in ramp-sdk-android.

Sending events to the widget:

could be done by calling post method on webview bindings. Example from the SDK

Native flow should be implemented on top of regular (off-ramp) integration.

Native Flow Details

The flow should progress as described:

  1. User: creates an off-ramp transaction as usual in the widget
    1. Widget: “send crypto” screen is presented with the dedicated Send with your wallet button
  2. User: clicks Send with your wallet button
  3. Widget: sends post-message event:
{
eventVersion: 1;
type: 'SEND_CRYPTO';
payload: {
assetInfo: AssetInfo;
amount: string; // in wei
address: string; // receiver crypto wallet address
}
}
  1. Integrator: After receiving this event, integrator should present the user with an UI overlaid on top of the widget for sending the crypto. Alternatively, the widget could be temporarily hidden by the integrator.
  2. User: confirms the transaction in the integrator UI and the crypto is sent to the address provided in the event payload.
  3. Integrator: The widget should be presented again to the user (integrator UI should disappear or widget should be unhidden)
  4. Integrator: SEND_CRYPTO_RESULT event should be sent by the integrator to resume flow:
{
eventVersion: 1;
type: "SEND_CRYPTO_RESULT";
payload:
| { txHash: string; }
| { error: string | undefined; };
}
  1. Widget: user is presented with the transaction summary