Carbon

Documentation

Welcome to Carbon's docs!

Get Started    

HTML Script & Custom URLs

HTML Script Overview

You can setup your own widget HTML from scratch via a JS script or embed our custom URL in an iFrame to integrate our widget.

A partner must set the 'publicKey' field for authentication if you're integrating the HTML script or custom URL. A partner must also set the 'environment' field and 'targetContainerId' field if you're integrating the HTML script.

One other major field a partner may change includes the 'tokens' field (if enabled), a comma-delimited list of tokens as a string (with no spaces). By default all tokens we support will be included. Check out this for the list of tokens we can support at the moment. We are aggressively expanding our crypto selection so stay tuned frequently for more crypto you may want to add to your integration!

Several other major fields a partner may integrate includes the 'currencies' field (the base settlement currency for the purchase--options are 'usd', 'eur', and 'gbp'), the 'amount' field (the base purchase amount), and the 'receiveAddress' field. More on all of these parameters later.

Check out this section for more information on how to create a developer account and obtain credentials. Only 'sandbox' widgets are automatically authorized. To obtain production access check out this.

Reach out to gavin @ carbon.money & daniel @ carbon.money if you would like to discuss enabling more custom widget functionality or have any more questions.

Note you used to only be able authenticate via the legacy 'apikey' field, which involved your superuser UUID. That should be secret and never publicly exposed so we instead strongly recommend superusers to authenticate via their 'publicKey'. The public key is shown at the top of the bottom screenshot. You can access the api keys either from your dashboard account home ('Production/Sandbox Publishable Key') or from the Developers -> Api Key section in your left tab (below screenshot). We will deprecate legacy api key authentication on May 20, 2020. Please reach out to [email protected] if you have any questions or concerns.

Custom URLs

Input Parameters

You can generate an iFrame using a custom url working off of the root base url https://buy.carbon.money. You can pass in parameters through the URL and add tokens and features easily. More on iFrame setup is available here.

Widget Size

Right now our current widget is at width 420px and height 550px. Some other sizes have not always worked for partners.

Credit/Debit API Overview

You may find it helpful to peruse our Credit/Debit API docs to contextualize your widget integration: https://docs.carbon.money/docs/credit-debit

One-screen Checkout

If you specify one token, a receive address for that token, and an amount, we will automatically forward your user to the checkout screen for lighting fast transacting!*

An example screenshot is below.

*If the user is not authenticated, the user will have to register / login first.

Input Parameters

Parameter
Access
Description

clientName

required & can append to URL

By default this will be Carbon Fiber. You can change this to whatever you like. The main place it will appear is when different wallets or providers connect to the user, upon which they will see clientName is asking to connect to your account.

environment

required

You must choose an environment in which your widget will render. Options are 'sandbox' or 'production'. If you want to integrate our production widget using a custom URL, choose https://buy.carbon.money as your root. In sandbox, use https://buysandbox.carbon.money

apiKey (DEPRECATED)

was required & can append to URL

You need a valid API key to use the widget. Please use the legacy API key! Make sure the legacy API key you insert matches the previously selected 'environment'.

publicKey

required & can append to URL

You need a valid public key to use the widget. Make sure the public key you insert matches the previously selected 'environment'.

tokens

optional & can append to URL

By default, you'll see all the tokens we have available. However you can narrow the list by adding a comma separated string of different coins you want to list. For example, if you want to show just ethereum and tron, you will use eth,trx.

homeScreenMessage

optional & can append to URL

By default, when the widget loads, you'll see a loading text of The API for fiat < > crypto. You can change this to something more pertinent for your users.

receiveAddress

optional & can append to URL, however, note that param is different when used in URL

In some cases (for example wallets or exchanges), you may already have a way of authenticating and/or registering addresses internally. You can pass in a variable or a constant for a deposit address in this optional object parameter. The address will autofill.

For URL params, options include receiveAddress + coin (first letter capitalized) following the camelcase convention. For example: receiveAddressEth, receiveAddressEos.

For widget params, you need to pass in an object for receiveAddress. Each key-value pair will consist of a 'cryptocurrencySymbol' from our list of supported crypto and the value will be the blockchain address for that cryptocurrencySymbol. An example is below:

receiveAddress: {
btc: 'btcAddress',
eth: 'ethAddress'
}

targetContainerId

required

The widget needs a DOM element to fill in this the widget - targetContainerId sets the ID of the div to target.

darkTheme

optional (Boolean) can append to URL

Defaults to false.

Determines color theme, whether dark or light. Set to true or false.

currencies

optional (String) can append to URL

Default settlement currency to display amounts in. Defaults to usd.

The available settlement currencies are 'usd', 'eur' and 'gbp'.

For more on our settlement currencies, check out this

amount

optional (String) can append to URL

Default base amount for purchase. If not specified, the default base amount will be 5. You should specify an amount of at least $5 (or the equivalent if you're specifying a settlement currency that is not USD) as our current minimum base purchase amount is $5.

NOTE: By base amount we mean the total amount MINUS fees. For more on base amounts v total amounts, refer to this. For more on fees, refer to this.

showCarbonLogo

option (Boolean)

true shows Carbon logo at the top of the widget. false shows generic "Buy Crypto" message

Note

The below code is meant to be a minimalistic example to get started with. If you copy/paste the below code and try to open it from your Finder, some functionality may not work as parts of our code check for either localhost or a whitelisted url. If you want to play around with our widget as quickly as possible, you can use node's http-server global module or python's http.server/SimpleHTTPServer to run an index.html file with the below code (substituting in your sandbox/production API key of course) on your localhost! Check this stack overflow question for more information: https://stackoverflow.com/questions/38497334/how-to-run-html-file-on-localhost.

For example, you can install the 'http-server' node package, save the below file (with your 'api key' and 'environment' updated) as index.html in a directory, run the http-server command in that directory, and then access the html file via localhost:8080.

Note that not only functionality but also styling will likely be messed up if you don't run the html file from localhost!

Feel free to play around with other HTML script variables (or url variables) apart from the required ones in the example below.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1, shrink-to-fit=no"
    />
    <title>Carbon Fiber</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div
      class="carbonfiber"
      id="carbonfiber"
      style='display:flex;justify-content: center;align-items: center; height: 100%'
    >
    </div>
    <script type="text/javascript" src="https://d2xxy1rwbjzckp.cloudfront.net/carbonFiber.js.min.gz"></script>
    <script>
    	CarbonWidget.default.carbonFiber.render({
        clientName: "Carbon Fiber",
        environment: "production",
        publicKey: "pk_live_jK3kaJ1kp83e16Pn37w9WkpQ", // production
        targetContainerId: 'carbonfiber',
      });
    </script>
  </body>
</html>
  

Customizing Widget Confirmation Screen

We currently let you modify the widget confirmation screen by changing the button text and the redirect url.

default widget confirmation screen template

default widget confirmation screen template

Change Confirmation Button Text

POST

Now, you can customize the confirmation screen on the widget by changing the url of the button as well as the text! If you need to redirect users to a site, this is a perfect opportunity.

Pro Tip: You can get your current widgetText by just doing a GET call instead of a POST with no data passed in.

// legacy auth that will be deprecated in our v2 api
/*
let jwtToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJlMzE3YjdlNy0yMzQ1LTQ0MWMtODA0Ni1kYjgxNTkyYmEyN2YiLCJzdXBlclVzZXIiOnRydWUsImNvbnRhY3QiOmZhbHNlLCJlbWFpbCI6ImRhbmllbEBjYXJib24ubW9uZXkiLCJpYXQiOjE1NTczMjc5MTR9.WZnSR5N1FebmT9nMu97PJvku49NY0jk4aKVPKm_1MlM';
*/
// we strongly recommend using your secret key to more securely authenticate your superuser instead
let secretKey = 'sk_test_A41Hm6IY3Q5LJ7ham34Zpkcj';

let url = `${ROOT}/v1/users/widgetText`;

let headers = {
  headers: {
    Authorization: `Bearer ${secretKey}`
  }
}

let data = {
  widgetText: "Go back to app"
}

axios.post(url, data, header).then(result => console.log(result)).catch(err => console.log(err));
{
   message: "successfully updated widgetText to Go back to app"
}

If you change the confirmation button's text, you may also want to change the URL the confirmation button is pointing to.

Again, you can do a GET to retrieve the current URL or POST to change the URL.

Change Confirmation Button URL

POST
// legacy auth that will be deprecated in our v2 api
/*
let jwtToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJlMzE3YjdlNy0yMzQ1LTQ0MWMtODA0Ni1kYjgxNTkyYmEyN2YiLCJzdXBlclVzZXIiOnRydWUsImNvbnRhY3QiOmZhbHNlLCJlbWFpbCI6ImRhbmllbEBjYXJib24ubW9uZXkiLCJpYXQiOjE1NTczMjc5MTR9.WZnSR5N1FebmT9nMu97PJvku49NY0jk4aKVPKm_1MlM';
*/
// we strongly recommend using your secret key to more securely authenticate your superuser instead
let secretKey = 'sk_test_A41Hm6IY3Q5LJ7ham34Zpkcj';

let url = `${ROOT}/v1/users/widgetButtonURL`;

let headers = {
  headers: {
    Authorization: `Bearer ${secretKey}`
  }
}

let data = {
  widgetButtonURL: "https://app.com/cool_redirect"
}

axios.post(url, data, header).then(result => console.log(result)).catch(err => console.log(err));
{
   message: "successfully updated widgetButtonURL to https://app.com/cool_redirect"
}

Updated about a month ago


What's Next

iFrame/Webview

HTML Script & Custom URLs


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.