• Log in
  • Contact Us

Get in touch  

Concepts • Integrations | Payments

Manual payment gateway (custom)

Last updated: 17 Oct 2019

The manual gateway allows you to record authorized and captured payments from third party payment gateways or through your own logic or business processes.

Manual gateway definition

Gateways provide access to external payment services. Moltin natively supports a number of payment gateway you can use for your project, such as Stripe, CardConnect, Braintree or Ayden. However, if you already have a gateway provider you wish to use, that isn't supported out of the box, or you would like to collect payments in a different way (e.g. cash on delivery), you can add it through the manual option. Essentially the manual gateway allows you to record authorized and captured payments from third party payment gateways or through your own logic or business processes.

The Manual gateway payment flow

Manual Payment Gateway flow (A)@2x

The diagram above provides a quick overview of how to go from unpaid order to paid order with Moltin using a third party payment gateway which will be broken down in further detail in the guide below.

You can only enable one manual gateway but you can integrate with as many third party providers as required through the same process described in the diagram above.

What you need for integration

  • Moltin dashboard to add credentials and enable the gateway.
  • Third party payment integration of your choice to use for payment.

Get your access token

You will need to get a client_credentials access token to follow along making the API requests outlined below.

curl -X POST https://api.moltin.com/oauth/access_token \
     -d "client_id=XXXX" \
     -d "client_secret=XXXX" \
     -d "grant_type=client_credentials"

PayPal integration

For PayPal-specific integration:

  1. Configure manual gateway with Moltin, as described below.
  2. Install the PayPal SDK using the client_credentialstoken.
  3. Use manual gateway with paypal.payment.create(create_payment_json).

Other third party integration

For specific instructions on how to use your chosen gateway provider you will need to check the providers documentation and configure your code accordingly.

Enable and configure Moltin gateway

By default all payment methods (gateways) are disabled. Enable the payment gateway using your Moltin dashboard or through the Moltin's API.

Enable in your dashboard

In your project's dashboard, go to Settings and select Gateways. This will take you to the main Gateways page where you’ll be able to view the list of all supported gateways. To enable the Manual gateway, click its edit icon, and then make sure that the Enabled checkbox is selected.

Click Save. This will take you back to the main Gateways screen. You’ll notice that the Manual gateway now has a green tick next to it.

Enable through the API

You can configure manual gateway programatically using the /gateways/manual endpoint.

curl -X PUT https://api.moltin.com/v2/gateways/manual \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer XXX" \
     -d $'{
        "data": {
           "type": "gateway",
           "enabled": true

Process workflow - generic walkthrough

As per the usual workflow, you need to create a cart and allow the items to be added to the cart. For more details on the usual product workflow, see: Checkout workflow.

Checkout the cart

This is the point where the customer’s information is attached to the order as well as the payment gateway. You'll need to specify manual as your gateway.

curl -X POST https://api.moltin.com/v2/carts/:reference/checkout \
  -H 'authorization: Bearer XXX' \
  -H 'content-type: application/json' \
  -d '{
    "data": {
      "customer": {
        "name": "Billy",
        "email": "billy@billy.com"
      "billing_address": {
        "first_name": "Jack",
        "last_name": "Macdowall",
        "company_name": "Macdowalls",
        "line_1": "1225 Invention Avenue",
        "line_2": "Birmingham",
        "postcode": "B21 9AF",
        "county": "West Midlands",
        "country": "UK"
      "shipping_address": {
        "first_name": "Otis",
        "last_name": "Sedmak",
        "company_name": "Sedmak & Co.",
        "line_1": "1251, Rexmere Ave",
        "line_2": "Farmingville, Suffolk",
        "postcode": "11738",
        "county": "New York",
        "country": "US",
        "instructions": "Leave in porch"

Pay for order

Once billing and/or shipping details have been provided, the order is then processed by a third party integration you've configured as your payment gateway. This transaction is processed outside of the Moltin's API environment, and if successful bring back an empty 200 OK response.

The request details will differ per provider, and this will typically be the type of authentication required by the vendor.

Once the order has been paid for successfully, the state endpoint should say approved. Once approved, you can go back to the Moltin's API to authorise the payment, or optionally, capture it.

Authorize and capture the payment

Transaction needs to be authorized and captured manually through Moltin. To capture a manual payment you will need to capture the individual transaction. You can do this via the dashboard or through the API.

Authorize payment

curl -X POST https://api.moltin.com/v2/orders/:orderId/payments \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer XXXX" \
     -d $'{
       "data": {
         "gateway": "manual",
         "method": "authorize"

Capture payment (requires Client Credentials)

curl -X POST https://api.moltin.com/v2/orders/:orderId/transactions/:transaction_id/capture \
     -H "Authorization: Bearer XXXX"

You can get a list of all the transactions for an order by calling the following (requires Client Credentials):

curl -X GET https://api.moltin.com/v2/orders/:orderId/transactions \
     -H "Authorization: Bearer XXXX"

Manage your stock

Optionally, if managing stock, make sure it is manually decremented. For more details, see: How inventory works.

curl -X POST https://api.moltin.com/v2/inventories/:productId/transactions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
       "type": "stock-transaction",
       "action": "decrement",
       "quantity": 5

Further reading

Explore More Concepts

01 Jul 2019

How to calculate cart and order totals

There are two methods that may be used to calculate cart and order totals. The method used depends on the calculation_method setting. The default is currently the simple method and this will continue...

Read More
James Carter
in Orders | Carts
18 Jun 2019

How promotions work

Promotions allow you to provide discounts to customers. By defining a Promotion and a code, you put in place the facility to offer discounts to customers applied directly to their shopping carts.

Read More
George FitzGibbons
in Carts | Promotions
06 Jun 2019

When to use a custom cart

Custom carts allow you to process an order for any type of item you wish to sell. The item does not need to exists in Moltin, which means custom cart items can be used for all sort of use cases.

Read More
George FitzGibbons
in Carts