Wallet API Integration

Introduction

About Simplex

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

Goal of the document

This document is intended to enable new partners of Simplex to integrate quickly and easily with Simplex’s payment and fraud detection system.

Terminology Used in this document

  • Payment Request: A request from the partner’s website to begin the process of processing a payment.
  • Risk Assessment: The proprietary process undertaken by Simplex to identify the level of risk of the transaction.
  • Validation: A secondary level of assessment required by Simplex to assess the risk of the transaction.
  • Billing Info: Information provided by the end-user required to process the payment.
  • 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.
  • Fiat: Conventional government backed currencies, such as USD, EUR, etc. (as opposed to decentralized digital currencies).
  • Exchange: A company which offers digital currencies for paying with fiat money.
  • Liquidity Provider: A liquidity provider connects many brokers and traders together, increasing the liquidity of the joint market.

User Flow

  1. The end-user chooses the “Buy with Credit Card” \ “Buy with Simplex Account” option in the main menu
  2. In the designated page, the end-user chooses the desired amount of the fiat money or the crypto currency.
  3. The end-user is getting a quote for his request
  4. On click, data is shared with Simplex and the user is directed to the Simplex’s checkout pages.
  5. The end-user is asked to provide the payment details and might be required to provide additional verification details.
  6. At the end of the payment process (the Thank You page), the end-user is being redirected back to the partner’s site (by clicking on a button).
  7. The user is notified whether the purchase was approved or declined.

Detailed Technical Flow

  1. The end-user browses to the partner’s website and chooses the desired crypto-currency he/she wishes to purchase
  2. The end-user chooses the “Buy with Credit Card” \ “Buy with Simplex Account” option from the main menu
  3. The end-user types the desired fiat or crypto amount and gets a quote in return (utilizing the GetQuote end-point)
  4. The End-user chooses to continue and click on the designated button
  5. The partner generates payment ID
  6. The partner’s client calls Partner’s server API, which then: a. The partner’s backend calls Simplex’s Payment Request endpoint b. The partner’s HTTP form sends an HTTPS POST, submitted to Simplex and end-user sees payment details form, co-branded Simplex & partner.
  7. The end-user completes the payment form and submits to Simplex. The end-user is notified on the web page that their payment is being processed.
  8. The end-user is redirected to the partner’s specified return URL by clicking a button
  9. A new event is published to the events API - “payment_request_submitted”
  10. Simplex starts the payment risk assessment process.
  11. Partner calls Simplex Events API (as part of a polling process).
  12. Payment is approved (or declined) by Simplex and credit card is charged \ credit is taken off the Simplex Account.
  13. A new event is published - “payment_simplexcc_approved” (or “payment_simplexcc_declined”)
  14. Partner calls events endpoint(as part of a polling process). An event is returned - “payment_simplexcc_approved” (or “payment_simplexcc_declined”).
  15. If the payment is approved, the partner processes the payment, and may send the items to the end-user as soon as required, as Simplex guarantees the funds from that point onward.
  16. The partner deletes the event after polling the events
The Sandbox Environment
  • Simplex provides a sandbox environment for our partners to use for testing the APIs quickly and easily. The Sandbox environment includes a few differences from the production environment making it suitable for testing.
  • Please use sandbox API key which is different from the production API key.
  • URI: The sandbox is available via https://sandbox.test-simplexcc.com. For every endpoint you want to test, please change “backend-wallet-api.simplexcc.com” to “sandbox.test-simplexcc.com”.
  • IP limitations are not enforced in Sandbox, in contrary to Production.
  • Test net wallet addresses are not supported. Please make sure to only use main net format.
  • To make Sandbox testing easier, Simplex has a test credit card available:
    • Credit card number: 4711 1000 0000 0000
    • Expiration date: any future date
    • Security Code: 123
    • Verification page (this is the Sandbox version of 3DS): click on “Y - AUTHENTICATION SUCCESSFUL”
  • In Sandbox, the part of the flow where Simplex checks eligibility and approves / declines the payment is automated, thus allowing the partner to test the whole end-to-end flow. The process response is automated and is determined according to the value of the field “Address” under “Billing address”: If the value is “approved” - payment will be approved. If the value is “declined” - payment will be declined.
Operations
Quote Request

The initial step is having the app presenting the digital currency price. A POST request is sent by the app asking for a price. Simplex REST API will receive the details listed below and respond, with an estimated price and a unique ID to mark the specific quote. In addition, specifying the payment methods in this step, will determine what payment options will be shown to the user upon the checkout.

Sandbox URL: https://sandbox.test-simplexcc.com/wallet/merchant/v2/quote
Production URL: https://backend-wallet-api.simplexcc.com/wallet/merchant/v2/quote

POST /quote
GetQuote
POST /quote

Request body

application/json
Object
end_user_id
string

Unique identifier for a user on the partner’s system. Same as app_end_user_id in the ‘Payment Request’

digital_currency
string
fiat_currency
string
requested_currency
string

The currency the user is asking a quote for

requested_amount
number
wallet_id
string

Partner name, as provided by Simplex

client_ip
string

The end user’s client IP address

payment_methods
Array of string

Can be “simplex_account”, “credit_card” or both. The first item in the array determines the default for the quote. Specifying both options will show the user 2 payments options on the checkout and the quote will be returned for the first item only. In order to only show one option in the checkout, specify it as the only item in the array

Example:
["simplex_account","credit_card"] 

Responses

200 OK
Body
Object
user_id
string

The unique identifier for a user on the partner’s system, as sent in the quote request

quote_id
string

Unique quote identifier in a UUID format

wallet_id
string

Partner name provided by Simplex, as sent in the quote request

digital_money
Object
currency
string
amount
number
fiat_money
Object
currency
string
base_amount
number
total_amount
number
valid_until
string
supported_digital_currencies
Array of string
'Request in Fiat' Example
Response Example (Fiat)
'Request in Crypto' Example
Response Example (Crypto)

When a user enters fiat and asks to see how much crypto it can buy

POST /wallet/merchant/v2/quote HTTP/1.1
Host: sandbox.test-simplexcc.com
Content-Type: application/json
Authorization: ApiKey XXXXXXXX

{
    "end_user_id": "11b111d1-161e-32d9-6bda-8dd2b5c8af17",
    "digital_currency": "BTC",
    "fiat_currency": "USD",
    "requested_currency": "USD",
    "requested_amount": 100,
    "wallet_id": "partner_name",
    "client_ip": "1.2.3.4",
    "payment_methods" : ["simplex_account","credit_card"] 
}

After the User Asked in Fiat

{
    "user_id": "11b111d1-161e-32d9-6bda-8dd2b5c8af17",
    "quote_id": "bc341244-3108-4f00-836a-97afdb786971",
    "wallet_id": "partner_name",
    "digital_money": {
        "currency": "BTC",
        "amount": 0.00927528
    },
    "fiat_money": {
        "currency": "USD",
        "base_amount": 90,
        "total_amount": 100
    },
    "valid_until": "2019-09-24T14:13:19.940Z",
    "supported_digital_currencies": [
        "BTC",
        "BCH",
        "LTC",
        "XRP",
        "ETH"
    ]
}

When a user enters crypto and asks to see how much it will cost

POST /wallet/merchant/v2/quote HTTP/1.1
Host: sandbox.test-simplexcc.com
Content-Type: application/json
Authorization: ApiKey XXXXXXXX

{
    "end_user_id": "11b111d1-161e-32d9-6bda-8dd2b5c8af17",
    "digital_currency": "BTC",
    "fiat_currency": "USD",
    "requested_currency": "BTC",
    "requested_amount": 1,
    "wallet_id": "partner_name",
    "client_ip": "1.2.3.4",
    "payment_methods" : ["simplex_account","credit_card"]
}

After the User Asked in Fiat

{
    "user_id": "11b111d1-161e-32d9-6bda-8dd2b5c8af17",
    "quote_id": "a5bfead2-2730-4024-8b69-7e44c41a1961",
    "wallet_id": "partner_name",
    "digital_money": {
        "currency": "BTC",
        "amount": 1
    },
    "fiat_money": {
        "currency": "USD",
        "base_amount": 9703.21,
        "total_amount": 10213.9
    },
    "valid_until": "2019-09-24T14:14:03.362Z",
    "supported_digital_currencies": [
        "BTC",
        "BCH",
        "LTC",
        "XRP",
        "ETH"
    ]
}
Payment Request

When an end-user agrees to a specific quote (price and amounts of fiat and crypto), the app will send a REST API Payment Request.
The Payment Request will include the quote ID received in the previous step, in addition to a new and unique payment ID that will be used to identify this payment by the partner and by Simplex.

Sandbox: https://sandbox.test-simplexcc.com/wallet/merchant/v2/payments/partner/data Production: https://backend-wallet-api.simplexcc.com/wallet/merchant/v2/payments/partner/data

POST /partner/data
PaymentRequest
POST /partner/data

Request body

Object
account_details
Object

PartnerEndUserAccount - User’s account details on the partner’s service

app_provider_id
string

Your partner name (e.g. Wallex)

app_version_id
string

The unique ID for a specific app version

app_end_user_id
string

The end-user ID originated from the partner’s end. Same as end_user_id in the ‘GetQuote’ call

app_install_date
string

The day the App was installed by the end-user for the first time

email
string

The end-user’s email address, as it registered on the partner’s platform

phone
string

The end-user’s phone number, in e164 format, as it registered on the partner’s platform

Example:
+972509123456
signup_login
Object

Information about the user’s session when first signed up with the partner’s service

ip
string

IP of end-user when end-user signed up with with the partner

location
string

A geodetic point with latitude and longitude that should be in degrees and may be in decimal form (location.latitude,location.longitude, e.g. - 36.848460,-174.763332)

uaid
string

Value of UAID web cookie when end-user signed up with the partner (not related to mobile apps)

accept_language
string
http_accept_language
string
user_agent
string
cookie_session_id
string
timestamp
string

The timestamp of when end-user signed up with partner

transaction_details
Object

PaymentDetails - Details related to this payment only - such as payment_id, requested amount of money, etc.

payment_details
Object
quote_id
string

Unique value will be provided by Simplex in the GetQuote response (UUID format)

payment_id
string

This value will be generated by the partner and needs to be unique (UUID) and to match the payment_id in the payment form HTTP post. As an example: d37ca9f4-4469-4968-ba40-749103ef3499. (8-4-4-4-12 characters)

order_id
string

UUID generated by the app and will be utilized by the app when presenting order details to the end-user (e.g. 987e1597-e89b-12d3-a456-426655449555)

destination_wallet
Object
currency
string
address
string

Represents the end user’s wallet address. Must match the requested crypto currency (for example: BTC address for BTC purchase)

tag
string

For currencies that require a destination tag\memo\label (BNB, XLM, XRP, ATOM, etc.)

original_http_ref_url
string

URL of the site that referred the end-user to partner’s site/app

Examples

Responses

200 OK
Body
Object
is_kyc_update_required
boolean

This response (“is_kyc_required”) means the API call (POST to partner/data) was valid. Some partners might require to upload KYC and they use this response as an indication. In this flow, end users will be uploading the KYC on Simplex checkout pages, so the value (true\false) can be ignored and just know that if this response comes back, the call was valid.

Payment Request Example
Payment Response Example
POST /wallet/merchant/v2/payments/partner/data HTTP/1.1
Host: sandbox.test-simplexcc.com
Content-Type: application/json
Authorization: ApiKey XXXXXXXX

{
	"account_details": {
		"app_provider_id": "partner_name",
		"app_version_id": "1.3.1",
		"app_end_user_id": "11b111d1-161e-32d9-6bda-8dd2b5c8af17",
		"app_install_date": "2018-01-03T15:23:12Z",
        "email": "example.cohen@simplex.com",
        "phone":"+972509123456",
		"signup_login": {
			"ip": "212.179.111.110",
			"location": "36.848460,-174.763332",
			"uaid": "IBAnKPg1bdxRiT6EDkIgo24Ri8akYQpsITRKIueg+3XjxWqZlmXin7YJtQzuY4K73PWTZOvmuhIHu + ee8m4Cs4WLEqd2SvQS9jW59pMDcYu + Tpl16U / Ss3SrcFKnriEn4VUVKG9QnpAJGYB3JUAPx1y7PbAugNoC8LX0Daqg66E = ",
			"accept_language": "de,en-US;q=0.7,en;q=0.3",
			"http_accept_language": "de,en-US;q=0.7,en;q=0.3",
			"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:67.0) Gecko/20100101 Firefox/67.0",
			"cookie_session_id": "7r7rz_VfGC_viXTp5XPh5Bm--rWM6RyU",
			"timestamp": "2018-01-15T09:27:34.431Z"
		}
	},
	"transaction_details": {
		"payment_details": {
            "quote_id": "1111cb8e-98fe-4808-b275-ade81ff95d08",
            "payment_id": "2222cb8e-98fe-4808-b275-ade81ff95d08",
            "order_id": "609b9976-5617-4513-9560-dcfe68b2330b",
            "destination_wallet": {
                "currency": "BTC",
                "address": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
                "tag": ""
            },
            "original_http_ref_url": "https://www.partner.com/"
        }
	}
}
{
    "is_kyc_update_required": true
}
Checkout Initializing

The Simplex checkout pages 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
New Window - Payment Form Submission
POST /payments/new

This is a HTTP endpoint that the app refers to when creating the web view – transferring the user to Simplex. The redirect will be done by form submission. The Simplex payment form will show after the app will open a new page and use HTTP POST with certain parameters:

  1. Version: Version of Simplex’s form to work with. Currently is “1”.
  2. Partner: partner name, as supplied by Simplex (e.g. wallex)
  3. Payment flow type: should be “wallet”
  4. Return URL - Success: URL to redirect the user to, in case of successful checkout completion
  5. Return URL - Fail: URL to redirect the user to, in case of failure during checkout process
  6. Payment ID - must match the ID from the previous API call



Production form URL: https://checkout.simplexcc.com/payments/new
Sandbox form URL: https://sandbox.test-simplexcc.com/payments/new

Generic Example
Example with Values
<form id='payment_form' action='#{payment_post_url}' method='POST' target='_self'>
<input type='hidden' name='version' value='#{api_version}'>
<input type='hidden' name='partner' value='#{partner_name}'>
<input type='hidden' name='payment_flow_type' value='wallet'>
<input type='hidden' name='return_url_success' value='#{return_url}'>
<input type='hidden' name='return_url_fail' value='#{return_url}'>
<input type='hidden' name='payment_id' value='#{data.transaction_details.payment_details.payment_id}'>
</form>
<html>
<body>
<form id="payment_form" action="https://sandbox.test-simplexcc.com/payments/new" method="post">
<input type="hidden" name="version" value="1">
<input type="hidden" name="partner" value="partner_name">
<input type="hidden" name="payment_flow_type" value="wallet">
<input type="hidden" name="return_url_success" value="https://www.partner.com">
<input type="hidden" name="return_url_fail" value="https://www.partner.com/support">
<input type="hidden" name="payment_id" value="2222cb8e-98fe-4808-b275-ade81ff95d08">
</form>

<script type="text/javascript">
document.forms["payment_form"].submit();
</script>

</body>
</html>
Widget - Loading Simplex SDK

In this option, you will be able to run the Simplex checkout pages as part of your platform (as a widget) by loading the Simplex SDK to your page, in 3 simple steps.

Important to note - the Simplex checkout pages must run on a web page, so either open it on a browser, or on a WebView in your mobile application.


Step #1 - add the Simplex JavaScript SDK by including the attached script in the head section of your page. (Simplex will provide a public_key to insert in the described <partner_public_key>)

Step #2 - place the Simplex Checkout widget on your page according to the User Experience you wish to achieve. This is done by adding the attached HTML elements into the page to surround and mark the place in the DOM where the checkout will be rendered.

Please note that the minimum width requirement is 320px and make sure the container does not restrict this. The checkout should be allowed to grow in height and is bounded internally to max-height of 600px

Step #3 - open the Simplex Checkout widget by using the load call. In order to load the checkout you need to have the following mandatory information available on the client side:

We offer an option to add a callback to the “load” call which will give you a response if it was successful or not. The following event types are available:

  1. checkoutLoadSucceeded
  2. checkoutLoadFailed

After a successful loading, the customer can interact with the Simplex Checkout widget

Step #4 (OPTIONAL) - you can subscribe to the following client side events:

  1. onlineFlowFinished - This event will be sent when the customer reaches a point in the checkout flow where he finished interacting with the Checkout UI, and you can safely close the checkout and continue interaction with the customer.

For example:

  1. Customer provided her card details and is waiting for the crypto
  2. Customer provided KYC details and the payment is pending until the offline KYC process finishes
  3. Customer was declined due to internal policies, was shown an error message, and the user acknowledged the error message

For UX purposes only, the event will include additional information as an indication separating between two cases:

  1. The customer online flow ended successfully. In this case the payment may result in success, depending on the final result of optional offline process
  2. The customer online flow ended unsuccessfully. In this case the payment will result in failure

Important note - The outcome is returned for UX purposes only in the client side. You MUST not trust the outcome and release any assets based on it. The payment outcome will be shared via the Events API

Step #1
Step #2
Step #3
Step #4 (OPTIONAL)
<!-- Sandbox Example -->
------------------------
<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>
======================================================================================
<!-- Production Example -->
---------------------------
<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>
<form id="simplex-form">
    <div id="checkout-element">
        <!-- checkout will be rendered here -->
    </div>
</form>
const params = {
    payment_id: '55d5241a-6354-445a-92f0-898c1b96f985'
}
Simplex.load(params, function (event) {
    console.log(event.type) // => 'checkoutLoadSucceeded'
});
Simplex.subscribe('onlineFlowFinished', function (event) {
    console.log(e.payload.result) // => "success" or "failure"
});
Events API

This is intended only for server-originated calls. When certain changes are made to a payment, the event for that change is generated on the event queue: whether the payment is submitted, approved or declined. The app provider must read these events by polling this API and act accordingly. This API endpoint may be optional, as the app provider can follow the Blockchain in order to update the end-user’s balance.

Sandbox URL: https://sandbox.test-simplexcc.com/wallet/merchant/v2/events Production URL: https://backend-wallet-api.simplexcc.com/wallet/merchant/v2/events

GET /events
DELETE /events/{event_id}
GetEvents
GET /events
Get All Events Example
Events Response Example
GET /wallet/merchant/v2/events HTTP/1.1
Host: sandbox.test-simplexcc.com
Content-Type: application/json
Authorization: ApiKey XXXXXXXX
{
	"events": [{
		"event_id": "11111df5-10ca-46c5-a410-29702bd701ff",
		"name": "payment_simplexcc_approved",
		"payment": {
			"id": "2222cb8e-98fe-4808-b275-ade81ff95d08",
			"status": "pending_simplexcc_payment_to_partner",
			"created_at": "2019-09-18T12:22:52.884Z",
			"updated_at": "2019-09-18T18:23:02.119Z",
			"fiat_total_amount": {
				"amount": 100,
				"currency": "USD"
			},
			"crypto_total_amount": {
                "amount": 0.00417257,
                "currency": "BTC"
            },
			"partner_end_user_id": "11b111d1-161e-32d9-6bda-8dd2b5c8af17"
		},
		"timestamp": "2019-09-18T18:23:02.119Z"
	}]
}
DeleteEvent
DELETE /events/{event_id}

The events should be removed from partner’s event queue. Should be called after partner has handled the event. No error is reported if event is not found on queue.

Path variables

event_id
string required

Responses

200 OK
Body
Object
status
string
Delete Event Example
Delete Event Response Example
DELETE /wallet/merchant/v2/events/11111df5-10ca-46c5-a410-29702bd701ff HTTP/1.1
Host: sandbox.test-simplexcc.com
Authorization: ApiKey XXXXXXXX
{
    "status": "OK"
}
Security

The API is deliberately designed uni-directionally, so that all the calls are from the partner to Simplex API, and not the other way around. This approach was chosen for the sake of integration simplicity, and to conform with our partners’ security scheme. See the authentication paragraph for more security information.

Authentication
  • Simplex will issue a REST API key for each partner. Each API key can be used only from a defined IP list and up to a defined expiration date. The partner will need to use the correct API key on each location.
  • API keys will be delivered to partner upon request from Simplex’s support. There is currently no web front-end for self-service.
  • The authentication mechanism is based on API key, which means simple comparison of the API key in the HTTP header to the list of partners’ API keys that Simplex holds. In addition - Simplex verifies that the expiration date and IP match for the API key.
  • New tokens will be issued by Simplex before the expiration date. The partner should take great care to ensure their credentials are not compromised.
  • It is obligatory not to store these credentials in the code base (which gets added to version control). These credentials must not be stored on the client side.
  • All requests must be authenticated, and all API requests must be made over HTTPS - calls over plain HTTP will fail.
Errors

Upon errors, both HTTP status code and JSON response (where possible) will be used to elaborate the partner on the error.

  • JSON Response on errors: Upon an error, Simplex’s APIs will add an “error” object to the response of the API call, unless this is not possible - for example because the call did not reach Simplex servers or blocked by a firewall. The “error” object will be of type Error. Thanks to the described behavior, errors may be identified simply by checking if the response object has “error” as one of the fields, in addition to the option of checking the HTTP status code. The error object is not present in all the definitions of the API entry-points responses, but it will be available upon error in all of them.
  • HTTP status codes: Simplex uses conventional HTTP status codes to indicate success or failure of a request. In general, codes in the 2xx range indicate success, codes in 4xx range indicate an error that resulted from provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an internal, temporary error within Simplex’s servers.
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