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.
- Default checkout steps
- Before you begin
- GraphQL queries and mutations
- Retrieve the customer order
- Before version 1.26.0
- Example requests
When building a headless front for a webshop, most of the time you need to go through these steps to invoke a successful payment throug Mollie
- Retrieve the payment methods. This allows you to retrieve specific Mollie data, like the available issuers and the image for the payment method.
- Get customer input. The customer needs to pick a payment method, but it is also possible that
- Call the Place Order mutation.
- Check the payment status. Depending on the result you might need to redirect the user to the hosted checkout page.
Make sure you have completed these steps:
- Install the Mollie Magento2 extension.
- Installed & enabled the extension within Magento.
- Entered your API key in Magento (Stores -> Configuration -> Mollie -> General).
- Successfully checked the API keys.
This is the regular Magento GraphQL cart query, but enhanced with Mollie specific attributes:
query($cartId: String!) {
cart(cart_id: $cartId) {
available_payment_methods {
code
title
mollie_meta {
image
}
mollie_available_issuers {
name
code
image
svg
}
mollie_available_terminals {
id
brand
model
serialNumber
description
}
}
}
}In here, the mollie_meta, mollie_available_issuers and mollie_available_terminals attributes are added.
Variables
- $cartId: Your reference to the cart of the shopper.
When setting the payment method on the cart, you can add payment method-specific user input. In this example, we've added a field called mollie_selected_issuer to set the selected issuer, and the mollie_card_token field, to set the token generated by Mollie Components.
(We recommend using GrahpQL variables like $cartId for the code and mollie_selected_issuer fields, but for clarity we've used hard-coded values here)
mutation($cartId: String!) {
setPaymentMethodOnCart(input: {
cart_id: $cartId
payment_method: {
code: "mollie_methods_ideal"
mollie_selected_issuer: "ideal_ABNANL2A"
mollie_card_token: "token-generated-by-Mollie-Components"
}
}) {
cart {
selected_payment_method {
code
}
mollie_available_issuers {
name
code
image
svg
}
}
}
}This mutation has the field mollie_selected_issuer added.
Variables
- $cartId: Your reference to the cart of the shopper.
When retrieving the cart you can also retrieve the applied payment fee. The amount will only be filled when a payment is set and that payment method has a payment fee activated.
query {
cart(cart_id: $cartId) {
prices {
mollie_payment_fee {
fee {
value
currency
}
base_fee {
value
currency
}
fee_tax {
value
currency
}
base_fee_tax {
value
currency
}
}
}
}
}Variables
- $cartId: Your reference to the cart of the shopper.
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.
Please note: Depending on your implementation it is possible that the mollie_redirect_url is empty. This only happens with Apple Pay and Credit Card payments. With Credit Card payments this only happens when the Mollie Components are implemented. In those cases, a visit to the hosted payment page is not required anymore. You can then call the Process Transaction mutation to check the outcome of the payment and redirect appropriately.
mutation PlaceMollieOrder($cartId: String!) {
placeOrder(input: {
cart_id: $cartId
}) {
order {
mollie_redirect_url
mollie_payment_token
// ...
}
}
}Variables
- $cartId: Your reference to the cart of the shopper.
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:
(depend on your situation the mollie_return_url can be static or dynamic. If this is dynamic we recommend that you use a variable for this)
mutation PlaceMollieOrder($cartId: String!) {
placeOrder(input: {
cart_id: $cartId
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.
Variables
- $cartId: Your reference to the cart of the shopper.
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. You can use redirect_to_success_page and redirect_to_cart to know where to redirect the user.
mutation($paymentToken: String!) {
mollieProcessTransaction(input: {
payment_token: $paymentToken
}) {
paymentStatus // SUCCESS, FAILED, etc.
redirect_to_cart // True of false, always the opposite of redirect_to_success_page
redirect_to_success_page // True of false, always the opposite of redirect_to_cart
cart {
// ...
}
}
}
For all available statuses see this enum: https://github.com/mollie/magento2/blob/master/etc/schema.graphqls#L93
Variables
- $paymentToken: The token provided by the previous step (see Redirection after placing the order)
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($cartId: String!) {
mollieRestoreCart(input: {
cart_id: $cartId
}) {
cart
}
}Variables
- $cartId: Your reference to the cart of the shopper.
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($amount: Float!, $currency: String!) {
molliePaymentMethods(input:{amount:$amount, currency:$currency}) {
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.
Tip: Use GET requests to retrieve the methods. This way, the result will be cached.
Variables
- $amount: The total amount of the current cart. For example:
20.00. - $currency: The currency currently active. For example:
EUR.
If you want to let customers enter their credit card data in your checkout, you must implement Mollie Components. This is a set of Javascript APIs you need to implement in your PWA. More information on implementing this can be found here.
To initialize the javascript part for Mollie Components, you need the profile id. You can set this manually in your code, but you can also fetch this from the Magento configuration:
query {
storeConfig {
mollie {
profile_id
live_mode
}
}
}You need to do an extra step to integrate this with the Magento 2 GraphQL APIs. When a user has entered their Credit Card data, you can then retrieve a token with this call (Source):
var { token, error } = await mollie.createToken();This token then needs to be sent to your Magento 2 backend in the mollie_card_token field:
mutation($cartId: String!) {
setPaymentMethodOnCart(input: {
cart_id: $cartId
payment_method: {
code: "mollie_methods_creditcard"
mollie_card_token: "token-generated-by-Mollie-Components"
}
}) {
// ...
}
}Please note: After calling the PlaceOrder mutation, the mollie_redirect_url field may be empty. In that case, you can call the Process transaction mutation to check the outcome of the payment and redirect appropriately.
Variables
- $cartId: Your reference to the cart of the shopper.
- $mollieCardToken: The token generated by Mollie Components.
The payment link allows merchants to create an order in their backend. The order confirmation is then sent to the customer containing a link where they can pay the order amount. This uses the store URL by default, but you can change this under Configuration -> Mollie -> Advanced -> PWA Storefront Integration -> Use custom payment link URL.
When you set a custom URL in here, it allows you to set the {{order}} in the URL. This value is replaced in the URL by a token representing the order. This token can then be used to retrieve the URL where you need to redirect the customer. If already_paid is set to true, you can redirect the user to your homepage.
mutation($order: String!) {
molliePaymentLinkRedirect(order: $order) {
already_paid
redirect_url
}
}Variables
- $order: The token representing the order
When the customer finishes the transaction they will get returned back to the store. Depending on your settings (see Configuration -> 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:
query($orderHash: String!) {
mollieCustomerOrder (
hash: $orderHash
) {
id
increment_id
created_at
grand_total
status
}
}Variables
- $orderHash: The string provided in the URL.
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_tokenin your request) -
Start the mollie transaction by calling
createMollieTransaction(add the value ofmollie_payment_tokenandissuersin 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.
query($cartId: String!) {
cart(cart_id: $cartId) {
available_payment_methods {
code
title
mollie_meta {
image
}
mollie_available_issuers {
name
code
image
svg
}
}
}
}Variables
- $cartId: Your reference to the cart of the shopper.
query($cartId: String!) {
cart(cart_id: $cartId) {
selected_payment_method {
code
mollie_meta {
image
}
}
mollie_available_issuers {
name
code
image
svg
}
}
}Variables
- $cartId: Your reference to the cart of the shopper.
mutation($cartId: String!) {
placeOrder(input: {
cart_id: $cartId
}) {
order {
order_id
mollie_redirect_url
mollie_payment_token
}
}
}Variables
- $cartId: Your reference to the cart of the shopper.
mutation($paymentToken: String!, $issuer: String) {
createMollieTransaction(input: {
payment_token: $paymentToken
issuer: $issuer
}) {
checkout_url
}
}
Variables
- $paymentToken: The token provided by the previous step (see Redirection after placing the order)
- $issuer: The code of the issuer selected by the shopper.
type Query($orderHash: String!) {
mollieCustomerOrder (
hash: $orderHash
) {
id
increment_id
created_at
grand_total
status
}
}
Variables
- $orderHash: The string provided in the URL.
- Install Mollie using Composer
- Update Mollie using Composer
- Install Mollie using the Magento® Marketplace