This tutorial helps you build your first checkout with Commerce.js. For this tutorial we will be using a dummy Chec account we've already setup, Feel free to replace the api keys and product permalink with your own. We'll also be using the Javascript SDK, but will include the cURL commands where we can for your reference.

What you'll accomplish in this tutorial.

  1. Setup Commerce.js
  2. Creating your first checkout token for a product
  3. Capturing an order with a card gateway

1. Setup Commerce.js

Install

First let's install the Commerce.js Javascript SDK and authenticate by using the following code

<script type="text/javascript" src="https://cdn.chec.io/v1/commerce.js"></script>

Alternatively you can use one of our server-side SDKs.

Authenticate

Next, to authenticate and get going, call Commerce.js with your public or private API key.

$ curl https://api.chec.io/v1/checkouts/commerce-js-basic?type=permalink \
    -H "X-Authorization: pk_test_1101361e43dd408534afd852d22f128d0b7aab34d59d6"
//This is the public API key created for our Chec Dummy Account, we have also turned on the console debugger
var myStore = new Commerce('pk_test_1101361e43dd408534afd852d22f128d0b7aab34d59d6', true);
//Remember to use your secret api key with our PHP SDK
Commerce\Auth::setApiKey('sk_test_110132cdeda71be409dc51db655820ab4116252090ced');
#Remember to use your secret api key with our Ruby SDK
Commerce.Auth('sk_test_110132cdeda71be409dc51db655820ab4116252090ced');

2. Creating your first checkout token

We've already created a test product with the permalink commerce-js-basic, let's go ahead an create a Checkout Token for it.

Request

$ curl https://api.chec.io/v1/checkouts/commerce-js-basic?type=permalink \
    -H "X-Authorization: pk_test_1101361e43dd408534afd852d22f128d0b7aab34d59d6"
myStore.Checkout.generateToken('commerce-js-basic', { 'type' : 'permalink' }, function(resp){
  //Render Checkout
  var token_id = resp.id; //e.g. chkt_959gvxcZ6lnJ7
  //...
  },
  function(error){
  //Error handler
  }
);
$token = Commerce\Checkout::generateToken('commerce-js-basic',  ['type' => 'permalink']);
token = Commerce.Checkout.generate_token('commerce-js-basic',  {:type => 'permalink'})

Response

The checkout token returned should look similar to this.

{
  "id": "chkt_J5aBD1EY9ZVRyl",
  "cart_id": null,
  "created": 1479758594,
  "expires": 1479931394,
  "analytics": {
    "google": {
      "settings": {
        "tracking_id": null,
        "linked_domains": null
      }
    }
  },
  "conditionals": {
    "collects_fullname": true,
    "collects_shipping_address": false,
    "collects_billing_address": false,
    "has_physical_delivery": false,
    "has_digital_delivery": true,
    "has_available_discounts": true,
    "has_pay_what_you_want": false,
    "collects_extrafields": true,
    "is_cart_free": false
  },
  "collects": {
    "fullname": true,
    "shipping_address": false,
    "billing_address": false,
    "extrafields": true
  },
  "has": {
    "physical_delivery": false,
    "digital_delivery": true,
    "available_discounts": true,
    "pay_what_you_want": false
  },
  "is": {
    "cart_free": false
  },
  "line_items": [
    {
      "id": "item_7RyWOwmK5nEa2V",
      "product_id": "prod_L1vOoZzb4oRa8Z",
      "name": "Test Product (Basic)",
      "image": null,
      "description": "<p>This is a test product</p>",
      "quantity": 1,
      "price": {
        "raw": 49,
        "formatted": "49.00",
        "formatted_with_symbol": "$49.00",
        "formatted_with_code": "49.00 USD"
      },
      "subtotal": {
        "raw": 49,
        "formatted": "49.00",
        "formatted_with_symbol": "$49.00",
        "formatted_with_code": "49.00 USD"
      },
      "variants": [],
      "conditionals": {
        "is_active": true,
        "is_free": false,
        "is_pay_what_you_want": false,
        "is_preorder": false,
        "is_quantity_limited": false,
        "is_sold_out": false,
        "has_digital_delivery": true,
        "has_physical_delivery": false,
        "has_images": false,
        "has_video": false,
        "has_rich_embed": false,
        "collects_fullname": true,
        "collects_shipping_address": false,
        "collects_billing_address": false,
        "collects_extrafields": true
      },
      "is": {
        "active": true,
        "free": false,
        "pay_what_you_want": false,
        "preorder": false,
        "quantity_limited": false,
        "sold_out": false
      },
      "has": {
        "digital_delivery": true,
        "physical_delivery": false,
        "images": false,
        "video": false,
        "rich_embed": false
      },
      "collects": {
        "fullname": true,
        "shipping_address": false,
        "billing_address": false,
        "extrafields": true
      }
    }
  ],
  "merchant": {
    "id": 11013,
    "business_name": "Commerce.js Test Account",
    "business_description": "Commerce.js is a full-stack eCommerce api for designers and developers",
    "currency": {
      "symbol": "$",
      "code": "USD"
    },
    "support_email": "sandbox@commercejs.com",
    "logo": "https://cdn.chec.io/merchants/11013/images/icon/22cef3acab8fb6ca004f388df18066cdf851603357d1d54e251b5|csj.logo.white.png",
    "logo_shape": "circle",
    "cover": "https://cdn.chec.io/merchants/11013/images/cover/ba3250991947bff6c6d55e044d150644b1a16ee157d1d54e25278|Comjs.Twitter.Header.png",
    "statement_descriptor": null,
    "has": {
      "logo": true,
      "cover": true,
      "business_description": true
    }
  },
  "extrafields": [
    {
      "id": "extr_7RyWOwmK5nEa2V",
      "name": "Website",
      "type": "text",
      "required": true,
      "options": null
    }
  ],
  "gateways": {
    "available": {
      "test_gateway": true,
      "stripe": false,
      "chec": false,
      "paypal": true
    },
    "available_count": 2,
    "test_gateway": {
      "type": "card",
      "settings": []
    },
    "paypal": {
      "type": "third_party",
      "settings": {
        "email": "paypal@trychec.com"
      }
    }
  },
  "shipping_methods": [],
  "live": {
    "merchant_id": 11013,
    "currency": {
      "code": "USD",
      "symbol": "$"
    },
    "line_items": [
      {
        "id": "item_7RyWOwmK5nEa2V",
        "product_id": "prod_L1vOoZzb4oRa8Z",
        "product_name": "Test Product (Basic)",
        "quantity": 1,
        "price": {
          "raw": 49,
          "formatted": "49.00",
          "formatted_with_symbol": "$49.00",
          "formatted_with_code": "49.00 USD"
        },
        "line_total": {
          "raw": 49,
          "formatted": "49.00",
          "formatted_with_symbol": "$49.00",
          "formatted_with_code": "49.00 USD"
        },
        "variants": [],
        "tax": {
          "is_taxable": false,
          "taxable_amount": null,
          "amount": null,
          "breakdown": null
        }
      }
    ],
    "subtotal": {
      "raw": 49,
      "formatted": "49.00",
      "formatted_with_symbol": "$49.00",
      "formatted_with_code": "49.00 USD"
    },
    "discount": [],
    "shipping": {
      "available_options": [],
      "price": {
        "raw": 0,
        "formatted": "0.00",
        "formatted_with_symbol": "$0.00",
        "formatted_with_code": "0.00 USD"
      }
    },
    "tax": {
      "amount": {
        "raw": 0,
        "formatted": "0.00",
        "formatted_with_symbol": "$0.00",
        "formatted_with_code": "0.00 USD"
      }
    },
    "total": {
      "raw": 49,
      "formatted": "49.00",
      "formatted_with_symbol": "$49.00",
      "formatted_with_code": "49.00 USD"
    },
    "total_with_tax": {
      "raw": 49,
      "formatted": "49.00",
      "formatted_with_symbol": "$49.00",
      "formatted_with_code": "49.00 USD"
    },
    "pay_what_you_want": {
      "enabled": false,
      "minimum": null,
      "customer_set_price": null
    }
  }
}

As you can see the The Checkout Token Object returned by Chec contains a lot of information to help you generate your checkout.


3. Capturing an order with a card gateway.

Important

We utilize key => value multidimensional arrays to immediately associate values with their parent(s) id when submitting data. For example with line items, the key would be the line_item_id and related values would be nested under that key.

  • Line item's quantity: line_item[{line_item_id}][quantity]
  • Line item's variant: line_item[{line_item_id}][variant][{variant_id}] = "{option_id}"

Request (using Test Gateway)

$ curl https://api.chec.io/v1/checkouts/{checkout_token_id} \
  -H "X-Authorization: pk_test_1101361e43dd408534afd852d22f128d0b7aab34d59d6" \
  -d line_items[item_7RyWOwmK5nEa2V][quantity]="1" \
  -d extrafields[extr_7RyWOwmK5nEa2V]="commercejs.com" \
  -d customer[firstname]="John" \
  -d customer[lastname]="Doe" \
  -d customer[email]="buyer@email.com" \
  -d payment[gateway]="test_gateway" \
  -d payment[card][number]="4242 4242 4242 4242" \
  -d payment[card][expiry_month]="01" \
  -d payment[card][expiry_month]="2019" \
  -d payment[card][cvc]="123" \
  -d payment[card][postal_zip_code]="94107"
myStore.Checkout.capture('{checkout_token_id}',
  {
  "line_items": {
    //Key is the line item id for "Test Product (Basic)"
    "item_7RyWOwmK5nEa2V": {
      "quantity": 1
      }
  },
  "extrafields": {
    "extr_7RyWOwmK5nEa2V": "commercejs.com" //Key is the extrafield's ID for "Website"
  },
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "buyer@email.com"
  },
  "payment": {
    "gateway": "test_gateway",
     "card": {
       "number": "4242 4242 4242 4242",
       "expiry_month": "01",
       "expiry_year": "2019",
       "cvc": "123",
       "postal_zip_code": "94107"
      }
    }
  },
  function(resp) {
      console.log(resp)
  },
  function(error) {
    console.log(error)
  }

);

$order = [
    'line_items' => [
      'item_7RyWOwmK5nEa2V' => [
        'quantity' => '1'
        ]
      ],
    'extrafields' => [
        "extr_7RyWOwmK5nEa2V": "commercejs.com" //Key is the extrafield's ID for "Website"
    ],
    'customer' => [
        "firstname": "John",
        "lastname": "Doe",
        "email": "buyer@email.com"
    ],
    'payment' =>
		    ['gateway' => 'test_gateway',
         'card' => [
            "number" => "4242 4242 4242 4242",
            "expiry_month" => "01",
            "expiry_year" => "2019",
            "cvc" => "123",
            "postal_zip_code" => "94107"
        ],
    ]
];

Commerce\Checkout::capture('{checkout_token_id}', $order);

token = Commerce.Checkout.capture('{checkout_token_id}',
    {
     :line_items => {
       :item_7RyWOwmK5nEa2V => {
         :quantity => 1
        }
      },
     :extrafields => {
       :extr_7RyWOwmK5nEa2V => "commercejs.com"
      },
     :customer => {
       :firstname => "John",
       :lastname => "Doe",
       :email => "buyer@email.com"
      },
     :payment => {
       :gateway => "test_gateway",
       :card => {
         :number => "4242 4242 4242 4242",
         :expiry_month => "01",
         :expiry_year => "2019",
         :cvc => "123",
         :postal_zip_code => "94107"
        }
      }
    })

Request (using Stripe)

Important Remember to use Stripe.js to create a card token before submitting. Instead of submit the credit card details directly to Chec you should only submit the token id in payment[card][token].

$ curl https://api.chec.io/v1/checkouts/chkt_J5aBD1EY9ZVRyl \
  -H "X-Authorization: pk_test_1101361e43dd408534afd852d22f128d0b7aab34d59d6" \
  -d line_items[item_7RyWOwmK5nEa2V][quantity]="1" \
  -d extrafields[extr_7RyWOwmK5nEa2V]="commercejs.com" \
  -d customer[firstname]="John" \
  -d customer[lastname]="Doe" \
  -d customer[email]="buyer@email.com" \
  -d payment[gateway]="stripe" \
  -d payment[card][token]="tok_18p356Jf7a6prG89YGcm7cpZ"
myStore.Checkout.capture('{checkout_token_id}',
  {
  "line_items": {
    //Key is the line item id for "Test Product"
    "item_7RyWOwmK5nEa2V": {
      "quantity": 1
    }
  },
  "extrafields": {
    "extr_7RyWOwmK5nEa2V": "commercejs.com" //Key is the extrafield's ID for "Website"
  },
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "buyer@email.com"
  },
  "payment": {
    "gateway": "stripe",
     "card": {
       "token": "tok_18p356Jf7a6prG89YGcm7cpZ"
      }
    }
  },
  function(resp) {

      console.log(resp)

  },

  function(error) {

    console.log(error)

  }

);

$order = [
    'line_items' => [
      'item_7RyWOwmK5nEa2V' => [
        'quantity' => '1'
        ]
      ],
    'extrafields' => [
        "extr_7RyWOwmK5nEa2V": "commercejs.com" //Key is the extrafield's ID for "Website"
    ],
    'customer' => [
        "firstname": "John",
        "lastname": "Doe",
        "email": "buyer@email.com"
    ],
    'payment' =>
		    ['gateway' => 'stripe',
         'card' => [
            "token" => "tok_18p356Jf7a6prG89YGcm7cpZ"
        ],
    ]
];

Commerce\Checkout::capture('{checkout_token_id}', $order);

Commerce.Checkout.capture('{checkout_token_id}',
    {
     :line_items => {
       :item_7RyWOwmK5nEa2V => {
         :quantity => 1
        }
      },
     :extrafields => {
       :extr_7RyWOwmK5nEa2V => "commercejs.com"
      },
     :customer => {
       :firstname => "John",
       :lastname => "Doe",
       :email => "buyer@email.com"
      },
     :payment => {
       :gateway => "test_gateway",
       :card => {
         :token => "tok_18p356Jf7a6prG89YGcm7cpZ"
        }
      }
    })

Response (Receipt)

If successful, The Receipt Object will be returned!

{
  "id": "ord_RyWOwmD7plnEa2",
  "cart_id": "",
  "checkout_token_id": "chkt_J5aBD1EY9ZVRyl",
  "created": 1479759493,
  "redirect": false,
  "customer_reference": "CMMRCJSTS-29388",
  "status_payment": "paid",
  "status_fulfillment": "fulfilled",
  "customer": {
    "email": "buyer@email.com",
    "firstname": "John",
    "lastname": "Doe"
  },
  "extrafields": [
    {
      "id": "extr_7RyWOwmK5nEa2V",
      "name": "Website",
      "value": "commercejs.com",
      "required": true
    }
  ],
  "shipping": null,
  "billing": null,
  "order": {
    "line_items": [
      {
        "id": "item_7RyWOwmK5nEa2V",
        "product_id": "prod_L1vOoZzb4oRa8Z",
        "product_name": "Test Product (Basic)",
        "quantity": 1,
        "price": {
          "raw": 49,
          "formatted": "49.00",
          "formatted_with_symbol": "$49.00",
          "formatted_with_code": "49.00 USD"
        },
        "line_total": {
          "raw": 49,
          "formatted": "49.00",
          "formatted_with_symbol": "$49.00",
          "formatted_with_code": "49.00 USD"
        },
        "variants": [],
        "tax": {
          "is_taxable": false,
          "taxable_amount": null,
          "amount": null,
          "breakdown": null
        }
      }
    ],
    "subtotal": {
      "raw": 49,
      "formatted": "49.00",
      "formatted_with_symbol": "$49.00",
      "formatted_with_code": "49.00 USD"
    },
    "discount": [],
    "shipping": {
      "price": {
        "raw": 0,
        "formatted": "0.00",
        "formatted_with_symbol": "$0.00",
        "formatted_with_code": "0.00 USD"
      }
    },
    "tax": {
      "amount": {
        "raw": 0,
        "formatted": "0.00",
        "formatted_with_symbol": "$0.00",
        "formatted_with_code": "0.00 USD"
      },
      "included_in_price": false,
      "breakdown": null,
      "zone": null
    },
    "total": {
      "raw": 49,
      "formatted": "49.00",
      "formatted_with_symbol": "$49.00",
      "formatted_with_code": "49.00 USD"
    },
    "total_with_tax": {
      "raw": 49,
      "formatted": "49.00",
      "formatted_with_symbol": "$49.00",
      "formatted_with_code": "49.00 USD"
    },
    "pay_what_you_want": {
      "enabled": false,
      "minimum": null,
      "customer_set_price": null
    }
  },
  "payment": {
    "id": "pymnt_19k7KEtOfqxD973",
    "transaction_id": 1479759493,
    "card_type": "visa",
    "gateway": "test_gateway",
    "reference": 4242
  },
  "fulfillment": {
    "shipping": null,
    "digital": [
      {
        "provider": "chec",
        "provider_type": "native_digital",
        "line_item_id": "item_7RyWOwmK5nEa2V",
        "product_id": "prod_L1vOoZzb4oRa8Z",
        "product_name": "Test Product (Basic)",
        "packages": [
          {
            "id": "ful_Op1YoVbV4oXLv9",
            "name": "logo.large.png",
            "access_link": "https://api.chec.io/fulfill/ord_RyWOwmD7plnEa2/ful_Op1YoVbV4oXLv9",
            "ext": "PNG",
            "size": "205.52 KB",
            "size_in_bytes": "210456"
          }
        ],
        "lifespan": {
          "expires": true,
          "expiry_date": 1480364294,
          "duration": "1",
          "period": "weeks",
          "download_limit": "10",
          "human": "Download links expire on November 28th, 2016, and can be accessed 10 time(s)"
        }
      }
    ]
  },
  "conditionals": {
    "collects_fullname": true,
    "collects_shipping_address": false,
    "collects_billing_address": false,
    "fulfill_shipping": false,
    "fulfill_digital": true,
    "has_available_discounts": true,
    "has_pay_what_you_want": false,
    "collects_extrafields": true,
    "is_cart_free": false
  },
  "metadata": [],
  "fraud": [],
  "merchant": {
    "id": 11013,
    "business_name": "Commerce.js Test Account",
    "business_description": "Commerce.js is a full-stack eCommerce api for designers and developers",
    "currency": {
      "symbol": "$",
      "code": "USD"
    },
    "support_email": "sandbox@commercejs.com",
    "logo": "https://cdn.chec.io/merchants/11013/images/icon/22cef3acab8fb6ca004f388df18066cdf851603357d1d54e251b5|csj.logo.white.png",
    "logo_shape": "circle",
    "cover": "https://cdn.chec.io/merchants/11013/images/cover/ba3250991947bff6c6d55e044d150644b1a16ee157d1d54e25278|Comjs.Twitter.Header.png",
    "statement_descriptor": null,
    "has": {
      "logo": true,
      "cover": true,
      "business_description": true
    }
  }
}

And that's it!