Blog • Integrations | Payments

How payment gateways work

Last updated: 05 Jul 2019

Integrate any third party gateway with your Moltin's project using the /gateways/[gateway] endpoint.

What you need for integration

  • Configured products and gateway using Moltin dashboard or API.
  • Third party gateway account (typically to generate the API Keys).

Integration steps summary

  1. Configure products through Moltin API or dashboard.
  2. Enable the third party payment gateway through Moltin API or dashboard, and provide the API Key.
  3. Use the enabled gateway as a dedicated gateway when making payment calls.
  4. You can configure and enable multiple gateways. It's the orders/:orderId/payments endpoint that decides which gateway will be used for a transaction.

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"

Enable a gateway on Moltin

To enable a third party gateway programatically or through the dashboard, set the gateway as enabled and provide login detail. This will enable the gateway on your project, and tell the API which API key to use.

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

Integrate with Moltin's checkout flow

Use Moltin API to create a checkout flow. See the JavaScript SDK for more API interactions. At minimum, you’ll need ability to:

  1. Add items to a cart.
  2. Check out a cart.
  3. Pay for an order. That's where you'll use a gateway.

Add item(s) to a cart

This section will walk you briefly through steps required to add item(s) to a cart. The scenario assumes that it's a one singular product added to a new cart. For more details, see Carts in API Reference.

You can use any URL safe value you want for your cart IDs. If a cart doesn’t already exist with that ID, it’ll be created the first time you add an item. If this request is successful, you’ll get a 201 response with all of the cart items that exist in the updated cart.

curl -X POST https://api.moltin.com/v2/carts/:cartID/items \
     -H "Authorization: Bearer XXX" \
     -H "Content-Type: application/json" \
     -d $'{
         "data": {
            "type": "cart_item",
             "id": "5a13d787-9e81-4aea-91f6-d281a7aef8b7",
             "quantity": 1
  }
}'

Check out a cart

Checking out a cart converts it into an unpaid order. You don’t have to specify the payment gateway you’d like to use at this point. At minimum, you'll need to provide billing details. Shipping is optional. For more details, see Checkout in API Reference.

curl -X POST https://api.moltin.com/v2/carts/:cartID/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": "US",
                "city": "billing city"
    }
  }
}'

Make a payment - generic overview

Payment transactions are processed similarly for all gateways. The typical workflow includes three main steps detailed below. For a specific 3rd party related details, see the detailed walkthrough below.

A payment transaction is created and an attempt to pay is made. The transaction is forwarded to the third party gateway specified by the customer (this of course depends on how many active gateways you have configured).

The payment is processed by the third party gateway. Payment transactions are always processed outside of Moltin for security reasons. Typically, you'd use a token rather than pass the card details directly. If, however, you wish to pass the cart details directly to the third party provider, Moltin enforces the use of the secure HTTPS protocol. If the transaction is successful, a 200 OK response is returned. Use the response (success or failure) to update the transaction, which will then in turn automatically update the order and payment statuses.

Pay by card - generic overview

Paying by card is the most typical scenario that looks the same on any gateway. You'd use a payments endpoint to send the card details to the gateway you've specified in the request.

curl -X POST https://api.moltin.com/v2/orders/:order_id/payments \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
        "data": {
          "gateway": "[gateway]",
          "method": "purchase",
          "first_name": "John",
          "last_name": "Smith",
          "number": "4242424242424242",
          "month": "10",
          "year": "2021",
          "verification_value": "123"
      }
    }'

Manual (custom) gateway

The manual gateway allows you to record authorized and captured payments from third party payment gateways or through your own logic or business processes. We describe the manual gateway in more details in the Manual gateway (custom) guide.

Third party payment gateways - detailed walkthrough

Below, we document third party integrations Moltin natively supports and supported payment methods. If you wish to use a provider that is not listed here, don't worry, you can still integrate it with Moltin using a custom payment gateway.

Stripe

How Stripe works with Moltin - quick overview

The client application created with the Moltin API calls the Stripe API and passes to the browser cart details needed for checkout. Stripe validates the purchase data and returns a token/source Moltin API uses to complete the payment transaction.

Supported payment types:

  • card payment
  • token/source payment

Stripe integration

Making a payment through Stripe is a two-step process. you'll need to:

  1. Collect customer's payment details outside of Moltin and pass them to Stripe. Stripe returns a payment token.
  2. Pass the token value in the payment field, and complete the payment transaction on Moltin's side. If successful, you'll get a 200 OK response. For more details, see the API Reference.
curl -X POST https://api.moltin.com/v2/orders/:orderId/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
        "data": {
          "gateway": "stripe",
          "method": "purchase",
          "payment": "tok_visa",
          "options": {
            "destination": "acct_XXX",
            "receipt_email": "john@example.com"
          }
        }
      }'

Using token, as opposed to passing payment details directly through Moltin API, is a secure and preferred method, although it is also possible to provide payment details directly, in which case it is absolutely vital to use the HTTPS protocol.

Source vs. token

Rather than requesting a token back from Stripe, you can request a source, and pass it exactly like a token, through the payment field. Tokens are for single use only, and expire within minutes after their creation; whereas sources can be charged directly, or attached to customers for later reuse. For more details, see Stripe documentation.

CardConnect

How CardConnect works with Moltin - quick overview

The client application created with the Moltin API calls the CardConnect API and passes to the browser cart details needed for checkout. The transaction is then verified and processed outside of Moltin, and if successful brings back an empty 200 OK response. For more details, see the API Reference.

Supported payment types:

  • card payment

Adyen

How Adyen works with Moltin - quick overview

The client application created with the Moltin API calls the Adyen API and passes to the browser cart details needed for checkout. The transaction is then securely transmitted to and from the Adyen payments platform, and if successful brings back the 200 OK response. For more details, see the API Reference

Supported payment types:

  • card payment

Braintree

How Braintree works with Moltin - quick overview

The client application created with the Moltin API calls the Braintree API and passes to the browser cart details needed for checkout. The transaction is then securely transmitted to and from the Braintree payments platform, and if successful brings back the 200 OK response. For more details, see the API Reference

Supported payment types:

  1. Card payment
  2. Customer ID payment
  3. Token payment
  4. Nonce payment

(1.) Braintree Card payment

For details, see the above section: Pay by card.

(2.) Customer ID payment

This method allows you to bill a specific Braintree customer. Braintree will be the default billing method in the customer's account.

curl -X POST https://api.moltin.com/v2/orders/:order_id/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
        "data": {
          "gateway": "braintree",
          "method": "purchase",
          "payment": BRAINTREE_CUSTOMER_ID
      }
  }'

(3.) Braintree token payment

Pay for an order with a specific Braintree Payment Method Token. This is similar to the Customer ID payment type, but you can define a number of payment methods to use as Tokens.

curl -X POST https://api.moltin.com/v2/orders/:order_id/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
        "data": {
          "gateway": "braintree",
          "method": "purchase",
          "payment": BRAINTREE_CUSTOMER_ID,
          "options": {
              "payment_method_token": BRAINTREE_PAYMENT_METHOD_TOKEN
          }
        }
      }'

(4.) Braintree nonce payment

Pay for an order with a previously created Braintree Payment Method Nonce. Use this method for a secure, one-time-use reference to transmit payment information when you wish your server to communicate sensitive payment information to Braintree without ever touching the raw data.

curl -X POST https://api.moltin.com/v2/orders/{ORDER_ID}/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
        "data": {
          "gateway": "braintree",
          "method": "purchase",
          "payment": BRAINTREE_PAYMENT_NONCE,
          "options": {
              "payment_method_nonce": true
          }
        }
      }'

Further reading