• Version: 1.2.0

Checkout

Once you have products in a customers cart, you are ready to checkout and process payment. The checkout process works in two stages. First, you convert the cart into an order, adding a shipping method, payment gateway, billing and shipping addresses, and customer information. Next, process the payment for the order using the specified gateway.

There are two checkout endpoints: https://api.molt.in/v1/carts/{cart ID}/checkout and https://api.molt.in/v1/checkout/payment/{method}/{orderID}. Neither endpoint uses a checkout object. They are purely processing endpoints, but will use objects from most of the other endpoints in the Moltin API. Because of this, instead of talking about the data fields for the object, we’ll discuss the data fields that you can pass in each of the processes below and the data that they return.

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

This topic will cover the following processes:

Retrieve the Available Checkout Options

Before converting the cart to an order, you may want to see what options are available for checkout data. If you call a GET request using the cart checkout endpoint, you can see the following:

  • The contents and value of the cart.
  • The applicable shipping methods.
  • The addresses associated with the cart customer.
  • The enabled payment gateways.

You can then use these values in the checkout process.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/carts/:cartIdent/checkout \
  -H "Authorization: Bearer XXXX"

A successful call returns a 200 OK HTML status and a large array that contains information from multiple endpoints.

{
  "status":true,
  "result":
  {
    "cart":
    {
      "contents":
      {
        "d58658a1cbd12a86a21ea0051d472823":
          {
            "quantity":2,
            "id":"1019656230785778497",
            "order":null,
            "created_at":"2015-07-01 17:41:28",
            "updated_at":"2015-08-28 17:49:46",
            "sku":"1893015",
            "title":"Mr. Coffee- 12-Cup Coffeemaker - Black\/Red",
            "slug":"mr-coffee-12cup-blackred",
            "sale_price":0,
            "status":
            {
              "value":"Live",
              "data":
              {
                "key":"1",
                "value":"Live"
              }
            },
            "category":
            {
              "value":"Home Appliances",
              "data":
              {
                "1018996345081430307":
                {
                  "id":"1018996345081430307",
                  "order":null,
                  "created_at":"2015-06-30 19:50:24",
                  "updated_at":"2015-06-30 19:50:24",
                  "parent":null,
                  "slug":"home-appliances",
                  "status":
                  {
                    "value":"Live",
                    "data":
                    {
                      "key":"1",
                      "value":"Live"
                    }
                  },
                    "title":"Home Appliances",
                    "description":"Appliances for your home"
                  }
                }
              },
              "stock_level":0,
              "stock_status":
              {
                "value":"Unlimited",
                "data":
                {
                  "key":"0",
                  "value":"Unlimited"
                }
              },
              "description":"Brew delicious coffee with this Mr. Coffee FTX49 12-cup coffeemaker that features a fresh brew timer, so you can have a fresh cup in the morning. The 2-hour auto shutoff helps ensure safe operation.",
              "requires_shipping":
              {
                "value":"Yes",
                "data":
                {
                  "key":"1",
                  "value":"Yes"
                }
              },
              "weight":0,
              "height":0,
              "width":0,
              "depth":0,
              "catalog_only":
              {
                "value":"No",
                "data":
                {
                  "key":"0",
                  "value":"No"
                }
              },
              "tax_band":
              {
                "value":"Default",
                "data":
                {
                  "id":"1018614836851901054",
                  "title":"Default",
                  "description":null,
                  "rate":20,
                  "created_at":null,
                  "updated_at":null
                }
              },
              "collection":
              {
                "value":"Randoms",
                "data":
                {
                  "id":"1019731797556069242",
                  "order":null,
                  "created_at":"2015-07-01 20:11:36",
                  "updated_at":"2015-07-01 20:11:36",
                  "slug":"randoms",
                  "status":
                  {
                    "value":"Live",
                    "data":
                    {
                      "key":"1",
                      "value":"Live"
                    }
                  },
                    "title":"Randoms",
                    "description":"Some random products for testing"
                  }
                },
                "brand":null,
                "price":49.99,
                "is_variation":false,
                "modifiers":
                {
                  "1045049396858716721":
                  {
                    "id":"1045049396858716721",
                    "order":null,
                    "created_at":"2015-08-05 18:33:33",
                    "updated_at":"2015-08-05 18:33:33",
                    "type":
                    {
                      "value":"Variant",
                      "data":
                      {
                        "key":"variant",
                        "value":"Variant"
                      }
                    },
                    "title":"color",
                    "instructions":"",
                    "product":1019656230785778497
                  }
                },
                "images":[],
                "pricing":
                {
                  "pre_discount":
                  {
                    "formatted":
                    {
                      "with_tax":"\u00a359.99",
                      "without_tax":"\u00a349.99",
                      "tax":"\u00a310.00"
                    },
                    "rounded":
                    {
                      "with_tax":59.99,
                      "without_tax":49.99,
                      "tax":10
                    },
                    "raw":
                    {
                      "with_tax":59.988,
                      "without_tax":49.99,
                      "tax":9.998
                    }
                  },
                  "post_discount":
                  {
                    "formatted":
                    {
                      "with_tax":"\u00a359.99",
                      "without_tax":"\u00a349.99",
                      "tax":"\u00a310.00"},
                      "rounded":
                      {
                        "with_tax":59.99,
                        "without_tax":49.99,
                        "tax":10
                      },
                      "raw":
                      {
                        "with_tax":59.988,
                        "without_tax":49.99,
                        "tax":9.998
                      }
                    }
                  },
                  "name":"Mr. Coffee - 12-Cup Coffeemaker - Black\/Red",
                  "totals":
                  {
                    "pre_discount":
                    {
                      "formatted":
                      {
                        "with_tax":"\u00a3119.98",
                        "without_tax":"\u00a399.98",
                        "tax":"\u00a320.00"
                      },
                      "rounded":
                      {
                        "with_tax":119.98,
                        "without_tax":99.98,
                        "tax":20
                      },
                      "raw":
                      {
                        "with_tax":119.976,
                        "without_tax":99.98,
                        "tax":19.996
                      }
                    },
                    "post_discount":
                    {
                      "formatted":
                      {
                        "with_tax":"\u00a3119.98",
                        "without_tax":"\u00a399.98",
                        "tax":"\u00a320.00"
                      },
                      "rounded":
                      {
                        "with_tax":119.98,
                        "without_tax":99.98,
                        "tax":20
                      },
                      "raw":
                      {
                        "with_tax":119.976,
                        "without_tax":99.98,
                        "tax":19.996
                      }
                    }
                  },
                  "tax_rate":20,
                  "total":119.976,
                  "total_before_tax":99.98
                }
              },
              "totals":
              {
                "pre_discount":
                {
                  "formatted":
                  {
                    "with_tax":"\u00a3119.98",
                    "without_tax":"\u00a399.98",
                    "tax":"\u00a30.00"
                  },
                  "rounded":
                  {
                    "with_tax":119.98,
                    "without_tax":99.98,
                    "tax":0
                  },
                  "raw":
                  {
                    "with_tax":119.976,
                    "without_tax":99.98,
                    "tax":0
                  }
                },
                "post_discount":
                {
                  "formatted":
                  {
                    "with_tax":"\u00a3119.98",
                    "without_tax":"\u00a399.98",
                    "tax":"\u00a30.00"
                  },
                  "rounded":
                  {
                    "with_tax":119.98,
                    "without_tax":99.98,
                    "tax":0
                  },
                  "raw":
                  {
                    "with_tax":119.976,
                    "without_tax":99.98,
                    "tax":0
                  }
                }
              }
            },
            "shipping":
            {
              "required":true,
              "methods":
              [
                {
                  "id":"1059477589212529113",
                  "order":null,
                  "created_at":"2015-08-25 16:19:50",
                  "updated_at":"2015-08-25 16:19:50",
                  "title":"Standard Ground",
                  "slug":"standard-ground",
                  "company":"FexEx",
                  "status":
                  {
                    "value":"Live",
                    "data":
                    {
                      "key":"1",
                      "value":"Live"
                    }
                  },
                  "price_min":0,
                  "price_max":0,
                  "weight_min":0,
                  "weight_max":0,
                  "tax_band":
                  {
                    "value":"Electronics",
                    "data":
                    {
                      "id":"1059477294000636820",
                      "title":"Electronics",
                      "description":null,
                      "rate":8,
                      "created_at":null,
                      "updated_at":null
                    }
                  },
                  "description":"",
                  "price":
                  {
                    "value":"\u00a35.35",
                    "data":
                    {
                      "formatted":
                      {
                        "with_tax":"\u00a35.35",
                        "without_tax":"\u00a34.95",
                        "tax":"\u00a30.40"
                      },
                      "rounded":
                      {
                        "with_tax":5.35,
                        "without_tax":4.95,
                        "tax":0.4
                      },
                      "raw":
                      {
                        "with_tax":5.346,
                        "without_tax":4.95,
                        "tax":0.396
                      }
                    }
                  },
                  "pricing":
                  {
                    "pre_discount":
                    {
                      "formatted":
                      {
                        "with_tax":"\u00a35.77",
                        "without_tax":"\u00a35.35",
                        "tax":"\u00a30.42"
                      },
                      "rounded":
                      {
                        "with_tax":5.77,
                        "without_tax":5.35,
                        "tax":0.42
                      },
                      "raw":
                      {
                        "with_tax":5.77368,
                        "without_tax":5.346,
                        "tax":0.42768
                      }
                    },
                    "post_discount":
                    {
                      "formatted":
                      {
                        "with_tax":"\u00a35.77",
                        "without_tax":"\u00a35.35",
                        "tax":"\u00a30.42"
                      },
                      "rounded":
                      {
                        "with_tax":5.77,
                        "without_tax":5.35,
                        "tax":0.42
                      },
                      "raw":
                      {
                        "with_tax":5.77368,
                        "without_tax":5.346,
                        "tax":0.42768
                      }
                    }
                  },
                  "totals":
                  {
                    "pre_discount":
                    {
                      "formatted":
                      {
                        "with_tax":"\u00a3125.75",
                        "without_tax":"\u00a3105.33",
                        "tax":"\u00a30.00"
                      },
                      "rounded":
                      {
                        "with_tax":125.75,
                        "without_tax":105.33,
                        "tax":0
                      },
                      "raw":
                      {
                        "with_tax":125.74968,
                        "without_tax":105.326,
                        "tax":0
                      }
                    },
                    "post_discount":
                    {
                      "formatted":
                      {
                        "with_tax":"\u00a3125.75",
                        "without_tax":"\u00a3105.33",
                        "tax":"\u00a30.00"
                      },
                      "rounded":
                      {
                        "with_tax":125.75,
                        "without_tax":105.33,
                        "tax":0
                      },
                      "raw":
                      {
                        "with_tax":125.74968,
                        "without_tax":105.326,
                        "tax":0
                      }
                    }
                  }
                }
              ]
            },
            "addresses":[],
            "gateways":
            {
              "2checkout":
              {
                "id":"1059581882334708105",
                "store_id":1018614836482801759,
                "name":"2Checkout",
                "slug":"2checkout",
                "description":null,
                "enabled":true
              }
            }
          }
        }

The array above can help you sort out what checkout information you still need to gather from the customer.

Convert a Cart into an Order

To check out the cart and create an order, you’ll need to POST the information in the table below to the https://api.molt.in/v1/carts/{cart ID}/checkout endpoint.

Key Type Required Unique Details
customer Integer or String No No The ID number or email address of the customer to associate with this order.
shipping Integer No No The ID number of the shipping method the order will use.
gateway String Yes No The slug of the gateway to use to process payment.
bill_to Integer or Array Yes No The ID number or details of the billing address. If passing an array, the array items will be the same as those used to create addresses.
ship_to Integer or Array No No The ID number or details of the shipping address. If both addresses are the same, you can set ship_to=bill_to.

In order to send array values, you may need to add the -g / –globoff switch to the statement so that the bracket characters pass through as array indicators correctly.

curl -X POST https://api.molt.in/v1/carts/:cartIdent/checkout \
  -g \
  -H "Authorization: Bearer XXXX" \
  -d "customer[first_name]=John" \
  -d "customer[last_name]=Doe" \
  -d "customer[email]=support@moltin.com" \
  -d "shipping=1059477589212529113" \
  -d "gateway=manual" \
  -d "bill_to[first_name]=Jon" \
  -d "bill_to[last_name]=Doe" \
  -d "bill_to[address_1]=123 Moltin Street" \
  -d "bill_to[city]=Mountain View" \
  -d "bill_to[county]=California" \
  -d "bill_to[country]=US" \
  -d "bill_to[postcode]=94040"
  -d "ship_to=bill_to"

This will return 200 OK and the information for the new order. You will need the order ID returned to you to process payment in the next section.

Process Payment

Now that we have created an order, we can authorize and collect payment for it. In the **, we mentioned the https://api.molt.in/v1/carts/checkout/payment/{method}/{orderID} endpoint. {method} can be any of the following:

  • authorize - Makes sure that the credit card details are correct and the payment amount can be recorded on their account. This does not request any funds from the credit card account.
  • complete_authorize - Handles the return from off-site payment gateways after the authorization completes.
  • capture - Charges and captures a payment amount that you have previously authorized.
  • purchase - Authorizes and immediately captures payment.
  • complete_purchase - Handles return from off-site gateways after purchase calls complete.
  • refund - Returns a previously captured amount from a processed transaction.
  • void - Cancels, if possible, a capture transaction. Most payment gateways require void transactions within 24 hours.

For these calls, you must pass a data array, which should include the payment details required by the payment gateway. Most on-site gateways require the following:

  • first_name
  • last_name
  • number
  • expiry_month
  • expiry_year
  • cvv

Other payment gateways may require/accept other items. The Moltin API will pass the contents of the data array directly to the gateway, so you can pass any additional data fields.

For this example, we are using the Dummy gateway. Let’s treat this as a standard on-site gateway.

curl -X POST https://api.molt.in/v1/checkout/payment/purchase/:orderId \
  -H "Authorization: Bearer XXXX" \
  -g \
  -d "data[first_name]=John" \
  -d "data[last_name]=Doe" \
  -d "data[number]=4242424242424242" \
  -d "data[expiry_month]=08" \
  -d "data[expiry_year]=2020" \
  -d "data[cvv]=123"

On success, this will return 200 OK. If the authorization succeeds, payment should be credited to your account with the gateway shortly.