iFrame Integration

Introduction

About Simplex

Simplex offers online merchants multiple payment methods for buying crypto. This document describes the iFrame integration requirements for credit card payments as well as Simplex’s account (banking) service

Goal of the document

This document is meant to enable Simplexs’ Turnkey Partners to integrate quickly with Simplex. Taking into account our Turnkey integration doesn’t require any back-end development, all the partner needs to do is to design a page and implement a few code snippets in the buy page . Please note that although this buy page will be an integral part of the partner’s site and fully controlled by them, the quote form is controlled by Simplex due to security reasons.

Terminology Used in this document

  • Risk Assessment: The proprietary process undertaken by Simplex to identify the level of risk of the transaction.
  • Partner: The online merchant/marketplace that is using the API.
  • End-User: The user of the partner’s website.
  • Application (or “app”): wallet software installed on the end-user’s mobile device OR any web application.
  • Application Provider (or “app provider”): the software company which owns/manages the application.
  • Quote Form (IFrame): The code we have created form elements using .createElement function and appended the elements to HTML <div>.
  • Fiat Money: Conventional government backed currencies, such as USD, EUR, etc. (as opposed to decentralized digital currencies).
  • Buy page: The designated page where the end-users can get quotes and purchase the desired crypto/fiat currencies processed by Simplex
  • Liquidity Provider: A liquidity provider connects many brokers and traders together, increasing the liquidity of the joint market.

User Flow

  1. User requests to purchase cryptocurrency using a credit card and approves Simplex TOS in the buy page.
  2. The end-user is redirected to a set of the mutually branded checkout page.
  3. The end-user is required to enter the billing details and to accept Simplex Terms of Use.
  4. The end-user is asked to provide their payment details, after which she/he might be required to provide additional verification details.
  5. After viewing the Thank You page, the end-user will be redirected back to the partner’s site according to the given Return URL.
  6. The end-user receives an email confirming his payment submission
  7. Future communication from Simplex about the status of the transaction (approved, declined, pending verification etc) will take place via email
  8. If the transaction is approved, the Liquidity Provider will provide the purchased quantity of crypto directly to the user.
Integration

Staging/Development Environment

  1. Insert the below base requirement code snippet (Staging/Development) into your local environment
  2. Design the Quote form (and the entire buy page if necessary) in order to fit to your desired Look and Feel
  3. While designing your buy page, please send us all the necessary action items. Having all the action items will allow us to make this integration available on our end rapidly
  4. Once the design is ready on your end, please also send us the CSS for the Simplex Quote form (IFrame).

Production Environment

  1. The moment Simplex has all the necessary details (Action Items+IFrame CSS), we will enable things on our end and give you an ETA for going live
  2. As soon as Simplex will finish implementing things on its end, please Implement the code snippets into your production environment on the designated page on your site
  3. Integration goes live
iFrame Code Snippets

Placing the snippets below in your web page, will load the iFrame so users will be able to enter the desired crypto and fiat information, along with their own wallet address. After clicking “continue”, the users will reach the checkout page that can be opened in one of two ways:

  • New window - users will be redirected to a seperate page to complete the transaction
  • Widget - users will stay on your page and will see the checkout as a widget to complete the transaction (if you choose this option, Simplex will provide a public key for you to use in the snippet)

Please choose the option that suits the user-experience you prefer.

Code Snippets - Staging / Development

Code Sample

Place this snippet to load the iFrame as part of your HTML. Plesae make sure you use the snippet that is relevant for the UX option you wish to implement (new window or widget). (for an easy copy & paste, please see example on the right panel)

Live Example




iFrame Sandbox Snippet Example (New Window)
iFrame Sandbox Snippet Example (Widget)
<head>
    <style id="simplex-css">
        .simplex-continue-button {background-color: green !important;}
    </style>
</head>

<body>
    <div id="simplex-form"></div>
        <script src='https://iframe.sandbox.test-simplexcc.com/form.js'type="text/javascript">
        </script>
        <script>
            window.simplex.createForm();
        </script>
</body>
<head>
    <script>
        window.simplexAsyncFunction = function () {
            Simplex.init({public_key: '<partner_public_key>'})
        };
    </script>
    <script src="https://cdn.test-simplexcc.com/sdk/v1/js/sdk.js" async></script>
</head>

<body>
    <form id="simplex-form">
        <div id="checkout-element">
        </div>
    </form>
    <script src='https://iframe.sandbox.test-simplexcc.com/form-sdk.js' type="text/javascript"></script>
    <script>
        window.simplex.createForm();
    </script>
</body>
Code Snippets - Production

iFrame Snippet

Place this snippet to load the iFrame as part of your HTML. Plesae make sure you use the snippet that is relevant for the UX option you wish to implement (new window or widget). (for an easy copy & paste, please see example on the right panel)

Tracking Snippet

Place this script on all pages on your site that link to the page with the Simplex iFrame. This will allow Simplex to see the source URL from where the user arrived at your site. Please note that this information will only be used by Simplex to monitor traffic sources and ensure compliance with Visa and Mastercard guidelines. (for an easy copy & paste, please see example on the right panel)



Please note - embedding both snippets is a must before going live

iFrame Production Snippet Example (New Window)
iFrame Production Snippet Example (Widget)
Tracking Script Production Example
<div id="simplex-form"></div>
<script src='https://iframe.simplex-affiliates.com/form.js' type="text/javascript"></script>
<script>
    window.simplex.createForm();
</script>
<head>
    <script>
        window.simplexAsyncFunction = function () {
            Simplex.init({public_key: '<partner_public_key>'})
        };
    </script>
    <script src="https://cdn.simplex.com/sdk/v1/js/sdk.js" async></script>
</head>

<body>
    <form id="simplex-form">
        <div id="checkout-element">
        </div>
    </form>
    <script src='https://iframe.simplex-affiliates.com/form-sdk.js' type="text/javascript"></script>
    <script>
        window.simplex.createForm();
    </script>
</body>
<script src="https://checkout.simplexcc.com/splx.js"></script>
Code Snippets - Advanced
Functionallity Syntax
Event that will get the selected cryptocurrency from the Quote form (IFrame) window.simplex.on(‘crypto-changed’, function(crypto){ //dostuff })
Update the cryptocurrency of the Quote form (IFrame) -verify that the crypto is available using the supported CryptoCurrencies: BTC, BCH, ETH, LTC, etc. var crypto = “BCH” window.simplex.updateCryptoCurrency(crypto);
The supported currencies will be returned in the createForm promise var promise = window.simplex.createForm(); promise.then(function (data) {var currencies = data.supportedCryptoCurrencies})
CSS Classes (Overrides)
Element Description
Crypto input - Wrapper: .crypto
- Input: #crypto_amount
- DropDown: .crypto-dd
- Error: .error-tooltip
Fiat input - Wrapper: .fiat
- Input: #fiat_amount
- DropDown: .fiat-dd
- Error: .error-tooltip
Crypto address - Wrapper: .crypto-address
- Input: #cryptoAddress
- Don’t have one: .wallet-url
- Error: .error-message
Submit button .simplex-continue-button
Form body .simplex-form
URL Parameters

Simplex supports inserting URL parameters into your URLs made of a key and a value separated by an equals sign (=) and joined by an ampersand (&). The first parameter always comes after a question mark in a URL. For example: http://example.com/?crypto=ETH&fiat=EUR

There are two types of objects that you can use on the buy page URL:

  • Content-modifying parameters Simplex allow you to control the reflected information in the buy page regarding the content parameters. For example, the following URL will send the end-user directly to buy BTC with USD on a buy page for the amount of 1000 units:
    http://example.com/?crypto=BTC&fiat=USD&amount=1000.
    The following Content-modifying parameters are available, currently:

  • crypto - The cryptocurrency option from the dropdown we will present to the end-user (the end-user can choose a different cryptocurrency afterward)

  • fiat - The fiat money option from the dropdown we will present to the end-user (theend-user can choose a different fiat money afterward)

    • *if using the ‘fiat’ parameter, you must use alongside the ‘amount’ parameter.
  • amount - The amount of fiat money that will be presented to the end-users once they land on the buy page

  • Tracking parameter (except from the GA or GTM) Pass information about your affiliate, campaign, or ad group associated to the buy page (This information will be provided by our CS team via weekly report if requested). For example: https://example.com/?crypto=ETH&ref_id=simplex would send the end-user directly to buy ETH and register Simplex as the referral affiliate once the end-user will be redirected to the Simplex’s checkout.

  • ref_id - The reference ID (also known as a publisher transaction ID, click ID, ad ID, or tracking ID) is a parameter reserved for the specific reference ID from the related affiliate, campaign, ad group, etc. This reference ID allows to get more elaborated tracking information and optimize your campaigns or business profitability accordingly. The reference ID can be either a number, integer or a mix of both and it is limited for 100 characters.

Action Items

Sending the full list of action items is a prerequisites for going live.

# Action Item Description
#1. Subdomain URL Please provide us the subdomain URL where the Simplex’s Quote form (IFrame) will be implemented on your site (Implementing the Quote form is available on multiple subdomains)
#2. Quote form (IFrame) CSS Code Snippet Please provide us the CSS code snippet of the Quote form (IFrame), so we will be able to reflect it accordingly in the production environment
#3. Fee Please provide the desired fee you wish to charge the end users. There is no limit here (for your reference our partners typically charge between 0%-5%). Please note this fee is above the 5% fee charged by Simplex
#4. Logo (Transparent background) Your company logo over a transparent background (250X150 Preferably). This will be placed on the checkout pages (please send in either JPG, PNG or GIF format)
#5. “Don’t have one” link Link to a wallet addresses site that can be used by the end-user to create a new wallet address in case they don’t already have one set up already (e.g. electrum.org/#download ). We will implement only one link in the buy page regardless of the number of supported cryptocurrencies. Therefore, we recommend sending a link that will allow creating multiple cryptocurrencies wallet addresses
#6. Return URL Please provide a URL which will redirect the end-user back to your site after completing the Simplex checkout process
#7. Crypto Currency Addresses Your public crypto addresses to which we will send your fee. This is required only if your fee is bigger than 0%. Please make sure to provide an address for every crypto currency you wish to offer on your platform
Supported Currencies

Please visit our Supported Currencies page to checkout the most recent list of supported fiat and crypto: https://integrations.simplex.com/supported_currencies