GraphQL integration

GraphQL allows you to query data from an external system in the format your application requires. This allows you to build a complete custom frontend for your Magento store, but still manage all products, categories, orders, etc. within Magento. The implementation of Mollie allows you to place an order within Magento using one of the Mollie payment methods.

In version 1.26.0 the GraphQL implementation has changed so that it complies with the regular Magento flow. The original flow still works but is deprecated so it's recommended that you use the new flow.

Retrieve the available payment methods

This is the regular Magento GraphQL query, but enhanced with Mollie specific attributes:

query {
  cart(cart_id: "{{cart_token}}") {
    available_payment_methods {
      code
      title
      mollie_meta {
          image
      }
      mollie_available_issuers {
        name
        code
        image
        svg
      }
    }
  }
}

In here, the mollie_meta and mollie_available_issuers attributes are added.

Set the payment method

When setting the payment method on the cart, you can add the issuer that the user has selected in your frontend:

mutation {
  setPaymentMethodOnCart(input: {
      cart_id: "{{cart_token}}"
      payment_method: {
          code: "mollie_methods_ideal"
          mollie_selected_issuer: "ideal_ABNANL2A"
      }
  }) {
    cart {
      selected_payment_method {
        code
      }
      mollie_available_issuers {
        name
        code
        image
        svg
      }
    }
  }
}

Placing the order

When placing the order you can request the mollie_redirect_url. This is where you need to redirect your customer after placing the order to finish the transaction. After finishing the transaction the user is redirected back to the Magento store, or the URL configured in the advanced settings.

mutation PlaceMollieOrder {
  placeOrder(input: {
      cart_id: "{{cart_token}}"
  }) {
    order {
      mollie_redirect_url
      mollie_payment_token
      // ...
    }
  }
}

Redirection after placing the order

The above mutation will create an order, but when the customer finishes the transaction, they will be redirected to the default Magento success page. Mollie offers 2 ways of setting a custom URL: static or dynamic.

Static setting the URL can be done by navigating in the backend to Stores -> Configuration -> Mollie -> Advanced -> PWA Storefront Integration and set Use custom return URL? to Yes. In the field that appears you can set a fixed URL where the user will get redirected after the transaction.

You can also set the return URL using GraphQL. You can do this by adding the mollie_return_url attribute to the PlaceOrder mutation input like so:

mutation PlaceMollieOrder {
  placeOrder(input: {
      cart_id: "{{cart_token}}"
      mollie_return_url: "https://example.com/transaction/mollie/process?order_id={{order_id}}&payment_token={{payment_token}}"
  }) {
    order {
      mollie_redirect_url
      mollie_payment_token
      // ...
    }
  }
}

Both URLs can be set at the same time, but the URL provided in the GraphQL request takes precedence over the URL from the configuration.

Please note that it is recommended that you check the transaction when the customer is returned from Mollie. See the next chapter for this.

Process transaction

When the user is redirected from Mollie back to your processing page (see Redirection after placing the order), it is possible that the order status isn't updated yet by the webhook. For this reason, it is recommended to trigger this process, which also resets the cart for the user when required, for example when the transaction was canceled.

mutation {
  mollieProcessTransaction(input: {
      payment_token: "{{payment_token}}"
  }) {
    paymentStatus // SUCCESS, FAILED, etc.
    cart {
      // ...
    }
  }
}

For all available statuses see this enum: https://github.com/mollie/magento2/blob/master/etc/schema.graphqls#L93

Resetting the cart

Note: We recommend using the above-stated mollieProcessTransaction which is better suitable for this purpose.

When the order gets placed, the cart is set to inactive. When the users get redirected back from the payment page to your webshop page, the payment can be in a canceled or expired state. In that case, it is possible to restore the cart:

mutation {
  mollieRestoreCart(input: {
      cart_id: "{{cart_token}}"
  }) {
    cart
  }
}

Extra: Retrieving available payment methods

Warning: This is not intended to be used in the checkout

In some cases, you want to retrieve the available payment methods from Mollie, to show them in your footer, for example. You can use this endpoint to retrieve them depending on the current currency:

query { 
 molliePaymentMethods(input:{amount:20, currency:"EUR"}) {
   methods {
     code
     image
     name
   }
 }
}

The amount and currency parameters are optional, but if you have a multicurrency setup, you must provide the currency for the current view, as payment methods may vary depending on the currency.

Retrieve the customer order

When the customer finishes the transaction they will get returned back to the store. Depending on your settings (see Configurtion -> Mollie -> Advanced -> PWA Storefront Integration -> Use custom return url?) this URL contains the order_hash parameter. You can use this order_hash to retrieve the CustomerOrder data like this:

type Query {
    mollieCustomerOrder (
        hash: "{{order_hash}}"
    ) {
        id
        increment_id
        created_at
        grand_total
        status
    }
}

Before version 1.26.0

To create an order using GraphQL you normally should roughly follow these steps:

• Create a shopping cart
• Add products
• Select Shipping method
• Get payment methods
• Select Payment method
• Place order

When placing an order using Mollie the method should look like this (bold = changed/new):

• Create a shopping cart
• Add products
• Select Shipping method
• Get payment methods (and retrieve a list of available issuers)
• Select Payment method
• Place order (but add mollie_payment_token in your request)
• Start the mollie transaction by calling createMollieTransaction (add the value of mollie_payment_token and issuers in your request)
• This last step will return the checkout URL. You need to redirect your customer to this URL so the payment can be handled by Mollie.

The Mollie extension also allows you to retrieve the order details using the generated payment token.

Example request

Request the available payment methods with issuers

query {
  cart(cart_id: "{{cart_token}}") {
    available_payment_methods {
      code
      title
      mollie_meta {
        image
      }
      mollie_available_issuers {
        name
        code
        image
        svg
      }
    }
  }
}

Request the available issuers for the current cart

query {
  cart(cart_id: "{{cart_token}}") {
    selected_payment_method {
      code
      mollie_meta {
        image
      }
    }
    mollie_available_issuers {
      name
      code
      image
      svg
    }
  }
}

Place order request

mutation {
  placeOrder(input: {
      cart_id: "{{cart_token}}"
  }) {
    order {
      order_id
      mollie_payment_token
    }
  }
}

Create Mollie Transaction request

mutation {
  createMollieTransaction(input: {
      payment_token: "{{payment_token}}"
      issuer: "{{issuer}}"
  }) {
    checkout_url
  }
}

Retrieve the customer order

type Query {
    mollieCustomerOrder (
        hash: "{{order_hash}}"
    ) {
        id
        increment_id
        created_at
        grand_total
        status
    }
}