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
}
}
}
}In here, the mollie_meta and mollie_available_issuers attributes are added.
Variables
- $cartId: Your reference to the cart of the shopper.
When setting the payment method on the cart, you can add the issuer that the user has selected in your frontend:
(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"
}
}) {
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.
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.
Variables
- $amount: The total amount of the current cart. For example:
20.00. - $currency: The currency currently active. For example:
EUR.
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:
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_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