Wallet API Integration

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

The end-user chooses the “Buy with Credit Card” \ “Buy with Simplex Account” option in the main menu
In the designated page, the end-user chooses the desired amount of the fiat money or the crypto currency.
The end-user is getting a quote for his request
On click, data is shared with Simplex and the user is directed to the Simplex’s checkout pages.
The end-user is asked to provide the payment details and might be required to provide additional verification details.
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).
The user is notified whether the purchase was approved or declined.

Detailed Technical Flow

The end-user browses to the partner’s website and chooses the desired crypto-currency he/she wishes to purchase
The end-user chooses the “Buy with Credit Card” \ “Buy with Simplex Account” option from the main menu
The end-user types the desired fiat or crypto amount and gets a quote in return (utilizing the GetQuote end-point)
The End-user chooses to continue and click on the designated button
The partner generates payment ID
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.
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.
The end-user is redirected to the partner’s specified return URL by clicking a button
A new event is published to the events API - “payment_request_submitted”
Simplex starts the payment risk assessment process.
Partner calls Simplex Events API (as part of a polling process).
Payment is approved (or declined) by Simplex and credit card is charged \ credit is taken off the Simplex Account.
A new event is published - “payment_simplexcc_approved” (or “payment_simplexcc_declined”)
Partner calls events endpoint(as part of a polling process). An event is returned - “payment_simplexcc_approved” (or “payment_simplexcc_declined”).
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.
The partner deletes the event after polling the events

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.

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

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

Optional field

If you want all relevant payment methods to be displayed, do not include this parameter in your request.

This is our recommended approach since we will be adding new payment methods frequently.

If you like to receive a quote for only one payment method or a subset of all payment methods please contact: customer.success@simplex.com

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"
}

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"
}

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"
    ]
}

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

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

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

ip

string

users login ip

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": {
			"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",
            "ip": "176.12.200.206"
		}
	},
	"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
}

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:

Version: Version of Simplex’s form to work with. Currently is “1”.
Partner: partner name, as supplied by Simplex (e.g. wallex)
Payment flow type: should be “wallet”
Return URL - Success: URL to redirect the user to, in case of successful checkout completion
Return URL - Fail: URL to redirect the user to, in case of failure during checkout process
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>

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:

payment_id - obtained in the Payment Request API call.

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:

checkoutLoadSucceeded
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:

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:

Customer provided her card details and is waiting for the crypto
Customer provided KYC details and the payment is pending until the offline KYC process finishes
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:

The customer online flow ended successfully. In this case the payment may result in success, depending on the final result of optional offline process
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"
});

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 Production URL: https://backend-wallet-api.simplexcc.com/wallet/merchant/v2

GetEvents

GET /events

DeleteEvent

DELETE /events/{event_id}

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"
	}]
}

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"
}

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.

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.

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.

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