Carbon

Documentation

Welcome to Carbon's docs!

Get Started    

Checkout Widget

Overview

Provide a secure & seamless checkout experience for your users.

Checking out will require the following:

1). Use the iframe wrapped Carbon elements to collect and tokenize a user's payment card information in our checkout widget.
2). Use the returned tokenized card info to add and charge a payment card for checkout. We will return HTML for initiating 3DS authentication at the ACS (Access Control Server) of your user's bank.
3). Use the iframe wrapped Carbon elements to initiate 3DS authentication by loading the ACS HTML.
4). After 3DS authentication finishes, complete processing the payment at your termination URL.

1. Collect and tokenize payment card info

Example code

// Initiate carbon
let carbon = await window.CarbonCheckoutCli.default.carbonCheckout("API_KEY", "sandbox");

// Initiate elements object
let elements = carbon.elements();

// Create card element (will allow for css to be passed in)
let card = elements.create('card');

// Mount card UI to app
card.mount("card-element");

// Handle form submission.
var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();

  carbon.createToken(card).then(function(result) {
    if (result.error) {
      // Inform the user if there was an error.
      var errorElement = document.getElementById('card-errors');
      errorElement.textContent = result.error.message;
    } else {
      // Submit the form
      form.submit();
    }
  });
});

// Once /charge is resolved, url will be returned

// Create acs element
let acs = elements.create('acs');

// Mount acs UI to app
acs.mount("acs-containerf");
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <script type="text/javascript" src="https://carbon12.s3.amazonaws.com/carbonCheckoutCli.js.min.gz"></script>
    <title>Carbon Checkout</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <form action="/charge" method="post" id="payment-form">
      <div>
        <label for="card-elements">
          Credit or debit card
        </label>
        <div id="card-elements">
          <!-- A Carbon Element will be inserted here. -->
        </div>
    
        <!-- Form error displayed here. -->
        <div id="card-errors" role="alert"></div>
      </div>
    
      <button>Submit Payment</button>
    </form>
    <div id="carbonfiber"></div>
  </body>
</html>

Sandbox Testing

For card details to test in the sandbox environment, refer back to Sandbox Testing Information

2. Add and charge a payment card for checkout (POST)

Payment Gateway v Credit/Debit Purchases API

The payment gateway can be thought of as a configured extension of the credit/debit purchases API. For example, the checkout widget utilizes the same tokenization functionality highlighted here API integrators can utilize (NOT recommended given the increased PCI exposure). Similarly, you can use this same endpoint to add a card on our side with tokenized fields v not tokenized fields as highlighted here. It is strongly recommended to review our core credit/debit API doc section in conjunction with our payment gateway docs to make sure you understand the differences between a payment gateway v not payment gateway integration.

Note that the below checkout endpoint combines the functionality of our /v1/card/addNew and /v1/card/charge3d endpoints into one route for initiating a payment with a credit/debit card. It is strongly recommended you review documentation on those endpoints while integrating this checkout endpoint.

Superuser and Contact Auth Required

Secret Auth v Legacy Auth

While you can use your superuser JWT to add a tokenized credit/debit card, we strongly recommend using your secret key to authenticate. The request authorization header is exactly the same except you substitute your secret key for the JWT.

If you do not know your secret key, please reach out to [email protected] from your superuser email.

Example request/response

// 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 headers = {
  headers: {
    Authorization: `Bearer ${secretKey}`
  }
};

let tokenObject = {
  billingPostal: 'tok_sandbox_cX7qASdFWyDY3KbCXUZeMs',
  billingPremise: 'tok_sandbox_tbLwipMuUxoqZcwXuKwv8w',
  billingStreet: 'tok_sandbox_cQJ8WxYtgNj2faEiu61sP6',
  cardNumber: 'tok_sandbox_wCGBiawWVS2AX1rQfDj4x7',
  cvc: 'tok_sandbox_381fpMbdzMwyaoeiSKg732',
  expiry: 'tok_sandbox_eoXXh6Et8bssJD7r4bRGfF' 
};

 let data = {
   tokenObject: tokenObject, 
   contactId: '', 
   fiatBaseCurrency: "usd",
   fiatChargeAmount: "1000"
};

let url = `${ROOT}/v1/card/checkout`;

axios.post(url, data, headers).then(result => console.log(result)).catch(err => console.log(err));
{
  message: 'Success checking out',
  code: 200,
  details: 
  { orderId: '86d74252-44ea-419f-93cc-9c09ac19c78d',
    acsUrl: ' <div> <h2 class="acs__load" style="text-align:center;">Loading ACS Page...</h2> <form style="visibility:hidden;" name="form" id="form" action=https://sandbox.carbon.money/v1/card/sandboxacs method="POST"> <input type="hidden" name="PaReq" value=eJxVUttugkAQ/RXiu8wOCFUzbmL1oTa1MfWS1LcVJmIqoAsY/Pvu4n2fzpn7mVlaJJp5POeo0ixpykWhtuzs4kFrNvzhYxuDNz8U3bAjEL12LxQdPwi6YUtS45d0Yl3s8kyiK1yP4EZNKR0lKislqej4PvmWYdDxPSS4UkpZT8ZSvD6Ci5kylbIcKb3JM2eaZ3x2CBobRXmVlfosu15IcCNU6b1MyvJQ9AEKlcWbvHajJt1NbTqcEAyPwQylt+wbkKeHPZdMYHMJHgPPKosK06vexXKNq2opktF6sdS/+LlcpfV58Zd8zT0xILARFKuSpSewh4i+I7Dvi37HaGnspFI7pETPyrsSOtgew2fPs4XMOTRnkVFp69wZcX0wakyEWfUdU8xFJHMdszY9LSZ4aBh92BNEpdlqgE+rDrA5RuOwdXdmjb7AS2FLCGwqXO8M179h0Muf+QeSSbuS /> <input type="hidden" name="TermUrl" value=https://sandbox.carbon.money/v1/card/charge3d/complete /> <input type="hidden" name="MD" value=UEZOVVBqeE5SRDQ4VFVSSVBraExORll2ZUdnNFIxbEJVa2xpWnpOT2FtdFBhWGM5UFR3dlRVUklQanhoWTNOVmNtdythSFIwY0hNNkx5OTNaV0poY0hBdWMyVmpkWEpsZEhKaFpHbHVaeTV1WlhRdllXTnpMMjFoYzNSbGNtTmhjbVF1WTJkcFBDOWhZM05WY213K1BIQmhia3hsYm1kMGFENHhOand2Y0dGdVRHVnVaM1JvUGp4dFpYTnpZV2RsU1dRK1VFRlNaWEV0TVRVM016WXdPRFkwTURFeE1pMDVOakEwTXpVMU9EWThMMjFsYzNOaFoyVkpaRDQ4TDAxRVBqd3ZVMVErOm1kZkZpdEJHSkF0OVBaRmoyYmxEUDJIS0cwV3h0SFd5NTM3WC9oMktLNXhDWEZrdERpaGZUTit3cHJ6TDhtclUvNQ== /> </form> </div> ' 
  } 
} 
// also check out the /v1/card/addNew and /v1/card/charge3D 
// error documentation mentioned earlier
// as we relay error responses from those endpoints to /v1/card/checkout

// 400
{
  message: "'tokenObject' must include the following fields: 
        'cardNumber', 'expiry', 'cvc', 'billingPremise', 'billingStreet', 'billingPostal'",
  code: 400
}

// 429
{
 message: 'Card is not enrolled in 3D Secure. Please try a different card.'
 code: 429,
 details: {
   charge3denrolled: 'N'
 }
}

// 429
{
 message: 'Card has an unknown enrollment in 3D Secure. Please try again or try a different card if the problem persists.'
 code: 429,
 details: {
   charge3denrolled: 'U'
 }
}

// 500
{
  message: 'There was an error checking out.',
  code: 500
}
Parameters
Access
Description

contactId

required

fiatBaseCurrency

required

The settlement currency for the crypto purchase. Case-insensitive. Must be a valid three-character ISO 4217 currency code. For a list of ISO 4217 codes go to this link: https://www.iban.com/currency-codes and check out our list of supported fiat base currencies here. Note that as mentioned above FX from the user's local currency of their credit/debit card to the settlement currency is automatic and specific rates are determined by the user's issuing bank.

fiatChargeAmount

required

The amount you'd like to charge a card. You need to pass in a string without any decimals. For example a charge of $10.39 would be rendered as "1039" and $233.91 would be "23391".

tokenObject

required

Tokenized credit/debit card fields. Will/must have the following keys: 'cardNumber', 'expiry', 'cvc', 'billingPremise', 'billingStreet', 'billingPostal'. For more information, please check out this.

3DS Enrollment

Make sure to reference the error responses in the example code section above for handling when payment cards are not enrolled in 3D Secure or when payment cards have an unknown 3DS enrollment.

3. Begin 3DS Authentication

Use the returned acs html from a successful checkout response to begin initiation of 3DS authentication.

This subsection will be expanded soon.

4. Complete payment

Please go here to learn more about completing processing for payments after 3DS authentication finishes. This subsection will also be expanded soon.

Checkout Widget


Suggested Edits are limited on API Reference Pages

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