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.
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.
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 Overpaid, Underpaid, 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.
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 |
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.
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:
A 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.
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"
A 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
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.
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:
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:
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:
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:
The embeddable button is available as a Javascript.
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.
Next, import the javascript library and it’s css. On the Embed tab you’ll find a code snippet that can be used to embed a payment button on your website.
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 (
)
};
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:
}
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 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.
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
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.