Getting started with moltin payment gateways

This article is an overview of how to receive orders using the moltin API. We’ll go through the order process, how payment gateways work and get Stripe set up so that we can receive both live and test payments.

If you need more information on payment gateways, you can check out the moltin payment gateway documentation and to get help, the Slack support channel.

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, if you’d like us to add support for a new gateway, you can request one in our Slack support channel.

Getting set up

As mentioned above, for the purposes of this article we’ll be accepting payments with Stripe. Before we can do this, 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 set up for your store. To do this log into your Forge account and then click Advanced > Gateways followed by the edit icon on the Stripe row.

Here we’ll be asked for some information on the gateway. I’d reccommend 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 publically. 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 clicking 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 Forge to use your live key rather than the test key. For now, we’ll use the test key.

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
6

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

And in PHP:

1
2
3

<?php
    $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
21

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
17
18

<?php
    $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 customers account. More information on the checkout functionality can be found in our documentation.

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 authorize 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 are 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
15

moltin.Checkout.Payment('payment', '<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 realise 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
11
12

<?php
    $result = Checkout::Payment('payment', '<ORDER ID>', [
        'data' => [
            'first_name' => 'John',
            'last_name' => 'Doe',
            'number' => '4242424242424242',
            'expiry_month' => '01',
            'expiry_year' => '2018',
            'cvv' => '123'
        ]
    ]);