fbpx

Quickstart

Cryptocurrencies have dramatically lowered the barrier to accepting payments on the web. FEX Commerce makes it easier than ever to accept cryptocurrency in the way cryptocurrencies were designed to be accepted: in a truly peer-to-peer fashion.

Introduction

FEX Commerce allows you to be your own bank with all the benefits of a hosted service. It’s no longer necessary to build and maintain infrastructure to monitor the blockchain; stay focused on running your business and leave the rest to us. Using public keys created on signup for each cryptocurrency, we’re able to generate payment addresses on your behalf and continuously monitor the blockchain to detect when payments are made.

Customers can now pay you directly from their computer or mobile device using the blockchain as the settlement network. With cryptocurrencies you no longer need to collect and store payment credentials or sensitive customer information.

Cryptocurrency Payments

Payments today rely on customers populating forms with credit card information. This information is then used to pull payments directly from the customer. Cryptocurrencies are different. Instead, a wallet is used to push payments directly to the merchant. A customer specifies the amount of cryptocurrency along with an address before sending funds. In this way, cryptocurrency payments are push payments.

When a customer requests to pay with cryptocurrency, we create a charge representing the expected payment. A charge can be thought of as a request for payment in one or more cryptocurrencies. Since cryptocurrency payments are made over a separate network, a unique payment address per cryptocurrency is generated on charge creation so we can associate customers to their payments. When a customer makes a cryptocurrency payment, they generate a transaction that is then broadcast to the cryptocurrency network for validation/confirmation.

Once a charge is created we start monitoring these unique addresses on the respective networks to detect any inbound payments. Each charge has an associated payment status.

When we detect the customer’s transaction on the blockchain, the payment status changes to Pending. This means the payment has been detected but it has not yet been validated by the network. When the transaction is fully validated and confirmed by the blockchain network, the payment status changes to Completed. These unique payment addresses are monitored for up to 60 minutes. If no payment is detected after 60 minutes then the payment status changes to Expired.

In some cases, a customer may make a payment after the 60 minutes has passed. In this case the payment status changes to Unresolved with a reason of Delayed.

In other cases a customer may overpay, underpay, or pay more than once. When this happens the payment status changes to Unresolved with reasons OverpaidUnderpaid, or Multiple respectively. The Unresolved payment status can be manually updated to Resolved by the merchant to indicate that the payment issue has been resolved.

Payment Statuses

A list of all payment statuses can be found below:

PAYMENT STATUS
DESCRIPTION
New
The payment has been created
Pending
The transaction has been detected
Completed
The transaction has been confirmed by the blockchain network
Expired
The payment request has expired (requests expire after 60 minutes if no payment has been detected)
Unresolved
The transaction has been confirmed but the payment diverged from what was expected
Unresolved (Underpaid)
The amount received was less than the amount requested
Unresolved (Overpaid)
The amount received was more than the amount requested
Unresolved (Delayed)
The amount received arrived after the payment request expired
Unresolved (Multiple)
Multiple payments were made to the same address
Unresolved (Other)
The transaction is of an unknown type
Resolved
The merchant has marked the payment as resolved
Cancelled
The request has been cancelled. Only new charges can be cancelled. Once a payment has been detected a charge cannot be cancelled.
Pending Refund
A refund has been initiated for this charge. Once a payment has been refunded it cannot be undone.
Refunded
A refund has been broadcasted and confirmed by the blockchain network

Here's a visual representation of how all this works:

Using the Commerce API

Accepting cryptocurrency payments with the FEX Commerce API is fast and easy. After you’ve signed up and created an API key, which only takes a few minutes, you just need to create a charge to receive a payment.

Payment Statuses

Use the FEX Commerce API to dynamically create charges. When you create a charge, we generate payment addresses on your behalf for each cryptocurrency that’s enabled and provide you with a hosted page you can send to customers to complete the payment. Here’s an example of dynamically creating a charge:

				
					curl -X POST https://api.commerce.favorbaas.com/charges/ \
-H "Content-Type: application/json" \
-H "X-CC-Api-Key: YOUR_API_KEY" \
-H "X-CC-Version: 2018-03-22" \
-d "@data.json"
				
			

Where data.json is simply a JSON object:

charge object is returned with payment addresses for each currency as well as a URL to a hosted page where a customer can complete their payment. Since we didn’t specify a price in our example, the customer is able to send any amount.

Receive a payment

Unlike credit cards where merchants must obtain payment credentials in order to charge a customer, cryptocurrencies are more like digital cash and rely on the customer explicitly sending money to the merchant.

After creating a charge, FEX Commerce will continuously monitor each blockchain network for a payment. Since cryptocurrencies are push payments, we set an expiration time for the charge which is currently 1 hour after the creation date. If the customer does not make a payment within that timeframe, we consider the charge to be expired.

Once a payment has been sent, we will update your Dashboard with the payment information. To get more information about the payment, simply retrieve the charge by supplying the unique charge code that was returned when the charge was created. Here’s an example of retrieving a charge:

				
					curl https://api.commerce.favorbaas.com/charges/2E8YCQWQ \
-H "X-CC-Version: 2018-03-22"
				
			

charge object is returned with specific information about the payment including, but not limited to, the transaction hash and the number of confirmations that have been received. Learn more

Not a developer?

It’s easy to accept cryptocurrency payments with FEX Commerce even if you’re not a developer.

Embed payment buttons
Payment buttons allow you to accept cryptocurrency on your website with minimal coding and users never need to leave your site to make a payment. Learn more

Create hosted pages
Hosted pages are publicly accessible checkout pages that can be shared with anyone. Hosted pages are a serverless solution for accepting cryptocurrency payments.

Get started with Shopify
If you have a Shopify store, you can get started accepting payments right away by adding FEX Commerce as an alternative payment method from within Shopify. Learn more

Use a shopping cart plugin
Soon you’ll be able to accept cryptocurrency using one of our shopping cart plugins. Integration with a shopping cart plugin is simple and doesn’t require any custom integration.

Guides

Payment buttons

Embedding a payment button on your website is a quick and easy way to start accepting cryptocurrency payments, whether it’s to accept donations for an open source project or to sell tickets to your event. Let’s start.

Whitelist your website

Before embedding a payment button, you’ll need to first whitelist your website. You can do this by navigating to Settings and adding your website under the Whitelisted domains section by clicking on Whitelist a domain.

You’ll be asked to enter your website domain; enter your website and click Save. Note that at this time we only allow https domains.

Create a payment button

To create a payment button click on the Accept payments button within the dashboard.

To make it easy to accept payments without developing a custom integration, we’ve made it possible to choose between two basic payment types:

Once you’ve gone through the flow you’ll be given a link to a hosted page where you can immediately start accepting cryptocurrency payments. On the Embed tab you’ll find a code snippet that can be used to embed a payment button on your website.

Embed your payment button
Now all you need to do is add the code snippet to your website and you’re all set to start accepting cryptocurrency payments!

Testing payment buttons
Best practice is to test before deploying. Here’s a quick way to test your payment button before pushing it to the world.

First you should whitelist localhost or, if you’re using a service like ngrok, the forwarding URL. You can whitelist localhost by adding http://localhost:8000 as a whitelisted domain by taking the steps mentioned earlier.

Second, create a simple HTML file with the button code embedded so you can serve the file locally. At the command line create an empty folder along with an empty index.html file:

				
					$ mkdir payment-button && cd payment-button && touch index.html
				
			

Now simply add the payment button code snippet to your index.html file using your preferred editor. The contents of your file should look something like this:

				
					<div>
  <a class="donate-with-crypto"
     href="https://commerce.favorbaas.com/checkout/6da189f179bc31">
    <span>Donate with Crypto</span>
  </a>
  <script src="https://commerce.favorbaas.com/v1/checkout.js">
  </script>
</div>
				
			

From within the payment-button directory, run python’s SimpleHTTPServer (this assumes you already have python installed):

				
					$ python -m SimpleHTTPServer
				
			

Next navigate to http://localhost:8000 in your browser. You should see your payment button rendered in the browser.

Callback Functions (Advanced)
The embedded button exposes the following callbacks:

Initialization
An onload query parameter specified in the script source will be called by the script once it has initialized:

				
					<script src="https://commerce.favorbaas.com/v1/checkout.js?onload=SOME_CALLBACK_FUNCTION"/>
				
			

Event Callbacks
Once the BuyWithCrypto class has been instantiated, multiple event callbacks can be registered with it:

				
					BuyWithCrypto.registerCallback('onSuccess', function(e){
    // Charge was successfully completed
});

BuyWithCrypto.registerCallback('onFailure', function(e){
    // Charge failed
});

BuyWithCrypto.registerCallback('onPaymentDetected', function(e){
    // Payment has been detected but not yet confirmed
});
				
			

When triggered, the callbacks will be called with the following event object:

				
					{
    buttonId: "unique id for this embeddable button",
    code: CHARGE_CODE,
    event: "charge_failed" OR "charge_confirmed" OR "payment_detected"
}
				
			

The CHARGE_CODE is the code of the created charge, and can be found here.

Metadata
Custom metadata can be passed to the associated checkout with a data-custom prop. It can be seen in use here:

				
					<div>
  <a class="buy-with-crypto" data-custom="MY_CUSTOM_DATA" href="https://commerce.favorbaas.com/checkout/6da189f179bc31">
    <span>This is a button.</span>
  </a>
  <script src="https://commerce.favorbaase.com/v1/checkout.js"></script>
</div>
				
			

Caching
By default, FEX Commerce will cache the state of transactions in case a user accidentally navigates away from the page in the middle of their payment. This behaviour can be disabled with a data-cache-disabled prop as seen here:

				
					 <div>
   <a class="buy-with-crypto" data-cache-disabled="true" href="https://commerce.favorbaas.com/checkout/6da189f179bc31">
     <span>This is a button.</span>
   </a>
   <script src="https://commerce.favorbaas.com/v1/checkout.js"></script>
 </div>
				
			

Using React

The embeddable button is also available as a React component.

Usage and Installation
First, whitelist your website and create a checkout with the API. Once your checkout has been created, keep track of the ID that was returned.

The component can be installed using Yarn or NPM:

				
					npm i -S react-fex-commerce
# OR
yarn add react-fex-commerce
				
			

Next, import the component and its corresponding CSS. Finally, add your checkout ID

				
					import FEXCommerceButton from 'react-fex-commerce';
import 'react-fex\fex-commerce/dist/fexCommerceButtonCommerceButtonavor-commerce-button.css';

const App = () => {
  return (
    <FEXCommerceButton checkoutId={'My checkout ID'}/>
  )
};
				
			

Props

The FEXCommerceButton component passes any extra props to its underlying button component, but also accepts a few custom props:

PROP NAME
DEFAULT
REQUIRED
TYPE
styled
false
no
boolean
checkoutId
nil
If no chargeId, yes
string
chargeId
nil
If no chargeId, yes
string
onLoad
nil
no
()=>void
onChargeSuccess
nil
no
(MessageData)=>void
onChargeFailure
nil
no
(MessageData)=>void
onPaymentDetected
nil
no
(MessageData)=>void
onModalClosed
nil
no
()=>void
disableCaching
false
no
boolean
disableCaching
false
no
string

Warning: If disableCaching is set to true, users that accidentally close their payment windows will be unable to see their transaction’s status upon reopening.

Message Data

				
					type MessageData = {
  event: 'charge_confirmed' | 'charge_failed' | 'payment_detected',
  code: <CHARGE_CODE>
}
				
			

Using Shopify

Accept multiple cryptocurrencies on your Shopify store with FEX Commerce within just a few minutes.

Signup for FEX Commerce

Sign up for a FEX Commerce account and follow the instructions to get started. After verifying your email address, adding two-factor authentication, and securely storing your recovery phrase, you’re ready to start accepting cryptocurrency payments.

Create a FEX Commerce API Key

First navigate to your Settings page which can be accessed using the left hand navigation menu:

Within Settings you’ll find an API Keys section. Click on Create an API Key to create a new API key that will be used to connect your Shopify store to your FEX Commerce account:

Under Alternative payments select FEX Commerce.

Under Email enter the email address used to create your FEX Commerce account and for API Key copy and paste the API Key created earlier within FEX Commerce.

Click Save to finish! Your customers are now able to checkout and pay with Bitcoin, Bitcoin Cash, DAI, Ethereum, Litecoin, Dogecoin, or USD Coin.

Webhooks

Webhooks allow you to monitor for updates to charges associated with your account. You might use webhooks to update a database record when a payment succeeds or to email a customer when a payment has been confirmed.

FEX Commerce will send webhook events whenever a charge is created, confirmed or fails. Take a look at our API docs to learn more about our implementation.

Creating a webhook
Subscribe to webhook notifications by adding an endpoint to the Webhook subscriptions section on your Settings page within FEX Commerce. Click Add an endpoint to add the URL where you’d like to receive webhooks.

You’ll be prompted to enter the endpoint URL (https only) where you’d like to receive webhooks. You can choose to be notified of all events or just a subset of events that you care about.

Receiving webhook notifications
FEX Commerce will validate that the connection to your service is secure before sending your webhook data. For this to work, your server must be correctly configured to support https.

Responding to a webhook
Your endpoint should respond with a 200 HTTP status code to acknowledge receipt of a webhook. If there is no acknowledgement of receipt, we will retry with an exponential backoff for up to three days. The maximum retry interval is 1 hour.

Checking signatures
FEX Commerce signs every webhook event it sends to your endpoints. The signature is included as a X-CC-Webhook-Signature header. This header contains the SHA256 HMAC signature of the raw request payload, computed using your webhook shared secret as the key. You can obtain your shared webhook secret in settings. Always make sure that you verify the webhook signature before acting on it inside your system.

Integrations

Shopify
If you have a Shopify store, you can get started accepting payments right away by adding FEX Commerce as an alternative payment method from within Shopify.
Learn more

WooCommerce

A WooCommerce payment gateway that allows your customers to pay with cryptocurrency via FEX Commerce.
Learn More

Libraries

Python

Available on PyPI through pip and easy_install:

				
					pip install fex-commerce-commerce

or

easy_install fex-commerce
				
			

Check out the source code and more detailed documentation on Github.

Node.js
Available on npm:

				
					npm install fex-commerce-node
				
			

Check out the source code and more detailed documentation on Github.

Ruby
Available as a gem:

				
					gem install fex_commerce
				
			

Check out the source code and more detailed documentation on Github.

PHP
Available via composer:

				
					composer require fex/fex-commerce
				
			

Check out the source code and more detailed documentation on Github.

HTML Snippets Powered By : XYZScripts.com