• Log in
  • Sign up
  • Contact Us

Get in touch  

Concepts • Integrations | Payments

Manual payment gateway (custom)

Last updated: 05 Jul 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 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