Introduction

Crypto Voucher Widget is an innovative no-code solution which allows your users to buy Crypto Voucher cryptocurrency gift cards on your website directly. The whole process is completely hosted by us and does not require any extra effort from your side. We are taking full responsibility for the transactions, so you don’t need to worry about chargebacks while keeping the best conversion rate in the market.

Crypto Voucher is a gift card that you can redeem into various cryptocurrencies such as Bitcoin, Litecoin, DogeCoin, Etherum, USDC, BNB, MATIC. You can keep your funds in our internal wallet or send them directly to your external wallet. We offer more than 200+ payments including Credit cards and PayPal available for 160+ countries worldwide.

Credentials

In order to start integrating Crypto Voucher Widget, you will need your individual token. Once you log into Crypto Voucher, open "My profile" and head to the Referral system section. You will see a form to contact us in order to get your credentials.

Types of integration

You can integrate widget in two different ways, as a:

• Referral System - users on your website can make transactions and you'll earn provision for each transaction made with your implemented widget. Check details of provisions here: Crypto Voucher Referral System

Referral system integration

After the user performs a successful transaction on your website, you'll get up to 2% per transaction, plus 5$ if it was the client's first transaction!

Each transaction with the widget starts by opening an iframe with an embedded checkout website. You have to pass only one argument, which is the token that you got after opting for becoming our partner. Then you can start a transaction by passing authentication token to CryptoVoucherWidget object's constructor or directly as a url query param, depending on the integration method.

Arguments

Payment flow

Instant Payment Notifications

After each significant transaction status change, you'll be notified with a webhook sent to your API.

Each notification will be sent until we receive a response with a status code equal to 200. We usually retry resends in 1 minute intervals.

IPN statuses

Notification can contain info about 3 statuses, which are:

IPN content type: application/json

For transaction status - FINISHED - we additionally return information about taken provision and subtotal, which is transaction amount minus provision.

IPN notification

To verify whether the IPN was sent by Crypto Voucher, you should use the IPN Secret that you got from us. If you don't have the IPN Secret, please contact us at [email protected]

You should hash particular values using sha256 and compare results with the hashed values from the received IPN.

IPN response format for statuses STARTED and CANCELLED:

{
  "providerTransactionId": "20652951-1788-4c53-a195-3ac2c6cf65ee",
  "status": "STARTED",
  "amount": "20.00",
  "currency": "EUR",
  "clientEmail": "[email protected]",
  "hash": "8cb0f0cd671c970b55d44fac6a9fd5d37a675d43debdbb8c882a7444a717538c"
}

IPN response format for statuses FINISHED:

{
  "providerTransactionId": "20652951-1788-4c53-a195-3ac2c6cf65ee",
  "status": "FINISHED",
  "amount": "20.00",
  "provision": {
    "amount": 0.8,
    "currency": "EUR"
  },
  "subTotal": {
    "amount": 19.2,
    "currency": "EUR"
  },
  "currency": "EUR",
  "clientEmail": "[email protected]",
  "hash": "8cb0f0cd671c970b55d44fac6a9fd5d37a675d43debdbb8c882a7444a717538c"
}

Hash is calculated as follows:

const getIpnHash = ({ stringToBeHashed, secret }) => {
  const hasher = crypto.createHmac('sha256', secret);
  const hash = hasher.update(stringToBeHashed).digest('hex');
  return { hash };
};

const stringToBeHashed = `${extId}${currency}${amount}${ipnSecret}`;

const { hash } = getIpnHash({ stringToBeHashed, secret: ipnSecret });

Integration

Crypto Voucher Widget can be integrated in several ways. Main implementation method is by using the NPM package, which already supports all required features, like iframe events etc. If you’d prefer to implement it on your own, there are some important details that you can learn about in the following sections.

NPM package

The official NPM package is available here

Server Based Apps

Install package

npm i --save widget_embed_script

or

yarn add widget_embed_script

Add HTML element with unique id, anywhere in your website

<div id="crypto_voucher_widget_unique_id"></div>

Import package and styles

import CryptoVoucherWidget from 'widget_embed_script';
import '../node_modules/widget_embed_script/dist/style.css';

Create new JS object

const widget = new CryptoVoucherWidget({
  selector: '#crypto_voucher_widget_unique_id',
  token: 'YOUR TOKEN HERE',
  baseUrl: 'https://widget-stage.cryptovoucher.io',
});

Call "start" method on the created object, first argument is amount, second is currency and third is external ID.

widget.start(25, 'EUR', 'external-id');

Static Websites

Check the latest version of the widget’s NPM package and replace it in import.

Import package from any CDN

import CryptoVoucherWidget from 'https://unpkg.com/[email protected]/dist/crypto-voucher-widget.es.js';
import 'https://unpkg.com/[email protected]/dist/style.css';

Add HTML element with unique id, anywhere in your website

<div id="crypto_voucher_widget_unique_id"></div>

Import package and styles

import CryptoVoucherWidget from 'widget_embed_script';
import './node_modules/widget_embed_script/dist/style.css';

Create new JS object

const widget = new CryptoVoucherWidget({
  selector: '#crypto_voucher_widget_unique_id',
  token: 'YOUR TOKEN HERE',
  baseUrl: 'https://widget-stage.cryptovoucher.io',
});

Call "start" method on created object, first argument is amount, second - currency and third is external id

widget.start(25, 'EUR', 'external-id');

Own integration implementation

If you don't want to use our solution, you can create integration for the widget yourself.

For your own implementation, you will have to create an iframe with src containing 3 url query arguments: amount, currency and extId, as follows: https://widget-url.io?amount=25&currency=EUR&t=AsDfGdSdFsDdSsSDDddDfDf24&extId=external-id

Example

<iframe
  width="100%"
  height="100%"
  src="https://widget-url.io?amount=25&currency=EUR&t=AsDfGdSdFsDdSsSDDddDfDf24&extId=external-id"
  frameborder="0"
  allowtransparency="true"
  scrolling="no"
/>

Additionally, you have to catch all close events sent by iframe, e.g. when the user clicks the "Go to homepage" button.

What more, you should implement a close button, in order to allow users to close the iframe by clicking on it.

Catching events sent by iframe

const parseIframeMessage = (event) => {
  if (event.origin !== baseUrl) return;

  switch (event.data) {
    case 'close_widget':
      return console.log('Iframe should be closed now');
  }
};

window.addEventListener('message', parseIframeMessage, false);

WordPress integration

We have a pre-made solution for WordPress-based websites that allow integrating the widget in a few simple steps.

Official plugin is available here: WordPress plugin

Integration process is very simple:

1. Go to plugins section and click "Add New"
   
2. Type "Crypto Voucher Widget" into search bar and wait for results
   
3. Click "Install Now" button
   
4. Click "Activate" button
   
5. Go to settings section and click "CV Widget Settings"
   
6. Paste your API token that you get after integration process and click "Save button"
   
7. Go to appearance section and select "Widgets"
   
8. Click on "+" button
   
9. Search for CV Widget
   
10. Place button in convenient and visible place on your website
    
11. Publish updated website by clicking button "Update"
    

Advanced aspects

Example:

window.startTransaction_hertlkj345h34({
  token: 'YOUR API TOKEN',
  amount: 10.5,
  currency: 'EUR',
  extId: 'random-uuid',
});

CheckoutV2 integration system

Checkout V2 is a new way of interaction that includes three endpoints.

Create transaction

POST /create-transaction
Request returns the widget transaction id and url where the customer can start the transaction.

Example

const baseUrl = 'https://market-api.cryptovoucher.io/widget-api';

fetch(`${baseUrl}/create-transaction`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Request-ID': 'random-uuid',
    'X-API-Key': 'YOUR API TOKEN',
    From: 'EMAIL FROM YOUR CRYPTO VOUCHER ACCOUNT',
    Authorization: 'Basic ' + btoa(`${YOUR_USERNAME}:${YOUR_PASSWORD}`),
  },
  body: JSON.stringify({
    amount: 2,
    currency: 'EUR',
    returnUrl: 'https://www.your-shop.com/example-order182',
    externalTransactionId: 'random-uuid',
    orderId: 182,
  }),
});

Response

{
  "statusCode": 200,
  "widgetTransactionId": "7e5ce9e3-e2fb-42dd-b148-20260538f916",
  "redirectUrl": "https://widget-stage.cryptovoucher.io/init/7e5ce9e3-e2fb-42dd-b148-20260538f916"
}

Available currencies

GET /available-currencies
The request returns the available currencies and the minimum and maximum transaction amount

fetch(`${baseUrl}/available-currencies`, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR API TOKEN',
    From: 'EMAIL FROM YOUR CRYPTO VOUCHER ACCOUNT',
    Authorization: 'Basic ' + btoa(`${YOUR_USERNAME}:${YOUR_PASSWORD}`),
  },
});

Response

{
  "statusCode": 200,
  "availableCurrencies": {
    "EUR": {
      "min": "1.00",
      "max": "10000.00"
    },
    "USD": {
      "min": "1.04",
      "max": "10407.85"
    }
  }
}

Transaction status

GET /{widgetTransactionId}
The request returns information about the transaction.

Response can contain info about 3 statuses, which are:

For transaction status - FINISHED - we additionally return information about taken provision and subtotal, which is transaction amount minus provision.

To verify response, you should use the IPN Secret that you got from us. If you don't have the IPN Secret, please contact us at [email protected]

You should hash particular values using sha256 and compare results with the hashed values from the received IPN.

fetch(`${baseUrl}/${widgetTransactionId}`, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR API TOKEN',
    From: 'EMAIL FROM YOUR CRYPTO VOUCHER ACCOUNT',
    Authorization: 'Basic ' + btoa(`${YOUR_USERNAME}:${YOUR_PASSWORD}`),
  },
});

Response format for statuses STARTED and CANCELLED:

{
  "providerTransactionId": "20652951-1788-4c53-a195-3ac2c6cf65ee",
  "status": "STARTED",
  "amount": "20.00",
  "currency": "EUR",
  "clientEmail": "[email protected]",
  "hash": "8cb0f0cd671c970b55d44fac6a9fd5d37a675d43debdbb8c882a7444a717538c"
}

Response format for statuses FINISHED:

{
  "providerTransactionId": "20652951-1788-4c53-a195-3ac2c6cf65ee",
  "status": "FINISHED",
  "amount": "20.00",
  "provision": {
    "amount": 0.8,
    "currency": "EUR"
  },
  "subTotal": {
    "amount": 19.2,
    "currency": "EUR"
  },
  "currency": "EUR",
  "clientEmail": "[email protected]",
  "hash": "8cb0f0cd671c970b55d44fac6a9fd5d37a675d43debdbb8c882a7444a717538c"
}

Hash is calculated as follows:

const getIpnHash = ({ stringToBeHashed, secret }) => {
  const hasher = crypto.createHmac('sha256', secret);
  const hash = hasher.update(stringToBeHashed).digest('hex');
  return { hash };
};

const stringToBeHashed = `${extId}${currency}${amount}${ipnSecret}`;

const { hash } = getIpnHash({ stringToBeHashed, secret: ipnSecret });

Errors

Occasionally you might encounter errors when accessing the API. There are four possible types:

Example errors

{
  "status": 500,
  "code": "internal-server-error",
  "description": "The server encountered an error and could not complete your request"
}

{
  "statusCode": 401,
  "code": "invalid-authorization",
  "description": "Missing or invalid authentication credentials"
}

{
  "statusCode": 400,
  "code": "amount-too-low",
  "description": "Provided amount is too low for selected currency."
}

WordPress plugin integration

We have new a solution for WordPress-based websites.

Integration process:

1. Go to plugins section and click "Add New"
   
2. Click "Upload Plugin" button
   
3. Click "Choose file" button
   
4. Select the plugin file from your computer. You will receive the plugin file from us when you decide to become a partner of the widget
   
5. Click "Install Now" button
   
6. Click "Activate Plugin" button
   
7. If the plugin has been installed correctly, you should see it in the plugins tab
   
8. Go to WooCommerce section and click "Settings"
   
9. Select "Payments"
   
10. Find "Crypto Voucher plugin" and click "Manage" button
    
11. Complete authorization data and click "Save changes" button
    
12. Crypto Voucher will be available now