This article will talk you through getting Stripe set up and running on your Moltin store.

One of the most important elements of your online store is the setup of a payment gateway to allow people to pay for their goods and here we’ll tell you how to do it. If you need more information on payment gateways, you can check out our documentation and to get help visit our forum.

Payment gateway providers act as the middleman to receive payments from your customers and pass the money on to you. There is a wide range of different payment processors to choose from, the best one for you will depend on the countries and currencies you want to receive payments from and the price plan that fits your budget. If you’re just starting out and you have no idea which processor to use, Stripe is generally a good starting point as both their API and dashboard are great to use.

Each payment processor has their own process for accepting payments, the steps involved in configuring the payment and the data passed in each step can vary vastly between companies. In order to keep integrating with different processors simple, we’ve tried to create a generic interface across the gateways we support. We’re constantly adding new payment processors to our list of supported gateways, so if you’d like us to add support for a new gateway, you can request one via this Github issue.

Getting set up

As mentioned above, for the purposes of this article we’ll be accepting payments with Stripe and so to start, we’ll need a Stripe account. To do this, head over to Stripe and sign up. You won’t need to add a credit card until you’re ready to start accepting real payments from your site.

Most payment gateways have a concept of test and live gateways. The test gateways allow you to send and receive payments without actually having to send any money. In the case of Stripe, you’ll get two API keys, one for your test and one for your live account. The test account is great for use during the development and testing phases of your site build.

Configuring the gateway

Once we have our Stripe account set up, the next step is to get the gateway setup for your store. To do this log into your dashboard and then click Advanced > Gateways followed by the edit icon on the Stripe row.

Setting up Stripe Payment Gateway

Here we’ll be asked for some information on the gateway. I’d recommend leaving the name as it is and the description empty. In the API key box, you need to add your Stripe secret API key. As the name suggests, this key should never be shared publicly. Even if you use one of our client side SDKs, the request to Stripe will always be made via our servers, so this key is never exposed to the end user.

You can find your Stripe API keys in the Stripe dashboard by going to Your Account > Account Settings and then click the Keys tab. In here you’ll see two sets of keys, one test and one live. Switching from the test to the live environment in Moltin is as simple as updating your Stripe gateway settings in the dashboard to use your live key rather than the test key. For now, we’ll use the test key.

Stripe API Keys

Creating an order

Before we can pay for our order, we first need to create an order to pay for. While the exact code for your order depends on which SDK you use and is out of the scope of this article, it is worth covering the process of creating an order with our API.

Step 1: Creating the cart

The first step to creating an order is to create a cart. The cart contains, as you might expect, the products the customer wants to order. It is worth noting that carts aren’t destroyed at any point in the order process and will stick around after the cart has been converted to an order and even once the order is completed. If you need to modify the contents of an order at any point in the order process, you can simply modify the original cart and generate a new order. Carts will generally be purged after a week of inactivity (unless you remove them manually). You can get more information on carts in our documentation.

An example of using the JS SDK to add a product to a cart would be:

1
2
3
4
5
moltin.Cart.Insert('<ID>', '<QUANTITY>', null, function(cart) {
    console.log(cart);
}, function(error) {
    // Something went wrong...
});

And in PHP:

1
$cart = Cart::Insert('<ID>', '<QUANTITY>');

Step 2: Convert the cart to an order

Once we have a cart with all of the products we want to buy, you’ll want to convert the cart to an order. To do this, we’ll use the checkout methods provided by the API. More information on the checkout functionality can be found in our documentation.

This is the point where the customer’s information is attached to the order as well as the payment gateway we want to use and the shipping method. We can do this with the JS SDK by calling:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
moltin.Cart.Complete({
  gateway: 'stripe',
  bill_to: {
    first_name: 'Jon',
    last_name:  'Doe',
    address_1:  '123 Sunny Street',
    address_2:  'Sunnycreek',
    city:       'Sunnyvale',
    county:     'California',
    country:    'US',
    postcode:   'CA94040',
    phone:      '6507123124'
  },
  ship_to: 'bill_to',
  shipping: 'free_shipping'
}, function(order) {
    // Handle the order
}, function(error) {
    // Something went wrong...
});

Or in PHP:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$order = Cart::Order([
  'gateway' => 'stripe',
  'shipping' => 'free_shipping',
  'bill_to'  => [
    first_name => 'Jon',
    last_name => 'Doe',
    address_1 => '123 Sunny Street',
    address_2 => 'Sunnycreek',
    city => 'Sunnyvale',
    county => 'California',
    country => 'US',
    postcode => 'CA94040',
    phone => '6507123124'
  ],
  'ship_to'  => 'bill_to'
]);

There are lots of additional parameters that can be passed here. For example, we could pass a customer parameter with a customer ID to attach the order to a customer’s account.

Paying for an order

At this point we have an incomplete order, we just need to pay for it and we’re done! The data we need to pass to make the payment depends on the gateway we’re using. For example, to accept a BitCoin payment you’d need different information than for a Stripe payment. I’ll continue to use Stripe here.

First off, we pass a payment parameter. This tells the API that you actually want to take the payment now. There are a few other options here such as refund for issuing a refund or to authorize a payment you can take later. Some gateways support some methods and not others. I’m just going to use payment here to take the payment right away.

Next, we pass the ID of the order created in the previous step. Finally, we pass the card details to take the payment from. If you’re using the Stripe test keys, you can leave the card details as they are as they will work on the Stripe test system.

There are lots of other card details you can use with the Stripe test API to force specific results. Full information on these details can be found in the Stripe docs on testing.

Make the payment in JS:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
moltin.Checkout.Payment('purchase', '<ORDER ID>', {
    data: {
        first_name: 'John',
        last_name: 'Doe',
        number: '4242424242424242',
        expiry_month: '01',
        expiry_year: '2018',
        cvv: '123'
    }
}, function(result) {
    console.log(result);
}, function(error) {
    // Something went wrong...
});

Make the payment in PHP:

If you accept credit card payments using one of our server-side SDKs, it is important to realize that credit card data will be passing through your server and as such, you should take the relevant steps to keep this data secure.

1
2
3
4
5
6
7
8
9
10
$result = Checkout::Payment('purchase', '<ORDER ID>', [
    'data' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'number' => '4242424242424242',
        'expiry_month' => '01',
        'expiry_year' => '2018',
        'cvv' => '123'
    ]
]);

Alternate payment methods

Stripe allows us to do more than just charge a card at the time of purchase. We also have the ability to create customers and payment methods which can then be charged at a later date without having to store any card details on our server. The Moltin API will allow you to harness this additional functionality when using Stripe as your payment processor.

Before being able to take the payment, the customer and payment method must be created via the Stripe API. There is lots of information on doing this in the Stripe API docs on customers and tokens. The main thing to remember here is that if you want to charge a payment method once, you should use a token, if you want to make more than one charge, you must attach the token to the customer and then bill the customer.

Once you have your token or customer ID, making the charge via the Moltin API is very similar to accepting a card payment, you just send over slightly different data.

To charge a customer in JavaScript:

1
2
3
4
5
6
7
moltin.Checkout.Payment('purchase', '<ORDER ID>', {
    customer_reference: 'STRIPE_CUSTOMER_ID'
}, function(result) {
    console.log(result);
}, function(error) {
    // Something went wrong...
});

And in PHP:

1
2
3
$result = Checkout::Payment('purchase', '<ORDER ID>', [
    'customer_reference' => 'STRIPE_CUSTOMER_ID'
]);

To charge a token in JavaScript:

1
2
3
4
5
6
7
moltin.Checkout.Payment('purchase', '<ORDER ID>', {
    card_reference: 'STRIPE_CARD_ID'
}, function(result) {
    console.log(result);
}, function(error) {
    // Something went wrong...
});

And in PHP:

1
2
3
$result = Checkout::Payment('purchase', '<ORDER ID>', [
    card_reference => 'STRIPE_CARD_ID'
]);

When using payment methods other than a card, it is important to remember not to send over the data array/object as the API will assume you’re making a standard card payment when this is present.

Congratulations! You can now add a payment gateway to your store.

James Owers

Written by James Owers - Senior Engineer @ Moltin