Skip to content

Home

Jump to bottom
kevinverschoor edited this page Jul 12, 2023 · 8 revisions

Table of Contents

Magento - Queries and Mutations

Create an order

Please follow this Magento tutorial to start an order https://developer.adobe.com/commerce/webapi/graphql/tutorials/checkout/


Retrieving Payment Methods

Via the Magento cart query you can retrieve all available payment methods.
Our extension adds the attributes logo and pay_issuers.

Sample:

query ($cart_id: String!) {
  cart(cart_id: $cart_id) {
    available_payment_methods {
      code
      title
      logo
      pay_issuers {
        id
        name
        visibleName
        logo
      }
    }
  }
}

Variables

$cartId: The cartId Magento provided when creating a cart


Setting Payment Method on cart

Via the Magento setPaymentMethodOnCart mutation you can set a payment method on your cart.
Our extension adds the option to add an issuer when setting a Payment method.

Sample:

mutation ($cart_id: String!) {
  setPaymentMethodOnCart(input: {
      cart_id: $cart_id
      payment_method: {
          code: "paynl_payment_ideal",
          pay_issuer: "5"        
      }
  }) {
    cart {
      selected_payment_method {
        code
      }   
    }
  }
}

Variables

$cartId: The cartId Magento provides upon creating a cart


Placing the order

Via the Magento placeOrder mutation you can place the order.

While placing the order you can request our pay_redirect_url attribute, which is used to redirect your customer to the payment page.

After completing the payment your customer will be redirected back to the Magento store, or the URL you send as the pay_return_url variable.
Note: The pay_return_url variable is not required.

Sample:

mutation {
  placeOrder(
    input: {
        cart_id: $cart_id, 
        pay_return_url: $pay_return_url, 
        pay_send_increment_id: $pay_send_increment_id
    }
  ){
    order {
      order_number
      pay_redirect_url
    }
  }
}

Variables

$cartId: The cartId Magento provides upon creating a cart
$pay_return_url: The URL the customer is redirected to after completing a payment.
$pay_send_increment_id: Boolean. When set to true, the Magento incrementId will be added to the pay_return_url as query string.


Restoring the cart

Once an order is placed using the Magento placeOrder mutation the cart becomes inactive even when the payment is cancelled.
Our extension adds the paynlRestoreCart mutation, which restores the cart upon use.

Sample:

mutation ($cart_id: String!) {
    paynlRestoreCart(cart_id: $cart_id) 
}

Variables

$cartId: The cartId Magento provides upon creating a cart


Pay. - Queries and Mutations

Get Pay. transaction status

The paynlGetTransaction query retrieves a Pay. transaction status based on the Pay. order-ID. This query expects pay_order_id as an argument and returns a paynlGetTransactionOutput.

This query requires an INTEGRATION or ADMIN Authorization token to be used.
See here how to create an Authorization token.

Sample:

query paynlGetTransaction($pay_order_id: String!) {
    paynlGetTransaction(pay_order_id: $pay_order_id) {
        orderId
        state  
        stateName          
        amount {
            value
            currency
        }  
        amountOriginal {
            value
            currency
        } 
        amountPaid {
            value
            currency
        }  
        amountPaidOriginal {
            value
            currency
        }
        amountRefund {
            value
            currency
        } 
        amountRefundOriginal {
            value
            currency
        }
        created
        orderNumber
        isSuccess
    }
}

Variables

$pay_order_id: The order id provided by Pay. This is not the same as the order id in Magento.


Refunding order

The paynlRefundTransaction mutation refunds the order.
This mutation expects the pay_order_id and the amount. It will return PaynlResultOutput.

This mutation requires an INTEGRATION or ADMIN Authorization token to be used.
See here how to create an Authorization token.

The paynlRefundTransaction mutation has a ACL rule linked to it,
in order to use this mutation the GraphQL - Refund rule has to be turned on in the user's roles.

Sample:

mutation ($pay_order_id: String!, $amount: String) {
    paynlRefundTransaction(
        pay_order_id: $pay_order_id,
        amount: $amount
    ){
        result,
        message
    }
}

Variables

$pay_order_id: The order id provided by Pay. This is not the same as the order id in Magento.
$amount: The amount you wish to refund.


Capturing order

The paynlCaptureTransaction mutation captures the order.
This mutation expects the pay_order_id. It will return PaynlResultOutput.

This mutation requires an INTEGRATION or ADMIN Authorization token to be used.
See here how to create an Authorization token.

The paynlCaptureTransaction mutation has a ACL rule linked to it,
in order to use this mutation the GraphQL - Capture rule has to be turned on in the user's roles.

Sample:

mutation paynlCaptureTransaction($pay_order_id: String!, $order_number: String!) {
    paynlCaptureTransaction(pay_order_id: $pay_order_id, order_number: $order_number) {
        result,
        message
    }
}

Variables

$pay_order_id: The order id provided by Pay. This is not the same as the order id in Magento.
$order_number: The order number provided by Magento. This is the order_number you recieve from the PlaceOrder mutation.



Voiding order

The paynlVoidTransaction mutation voids the order.
This mutation expects the pay_order_id. It will return PaynlResultOutput.

This mutation requires an INTEGRATION or ADMIN Authorization token to be used.
See here how to create an Authorization token.

The paynlVoidTransaction mutation has a ACL rule linked to it,
in order to use this mutation the GraphQL - Void rule has to be turned on in the user's roles.

Sample:

mutation paynlVoidTransaction($pay_order_id: String!) {
    paynlVoidTransaction(pay_order_id: $pay_order_id) {
        result,
        message
    }
}

Variables

$pay_order_id: The order id provided by Pay. This is not the same as the order id in Magento.


Create Authorization token

Some queries & mutations requests in the Pay. GraphQL extension require an ADMIN or INTEGRATION Authorization token to be used.

ADMIN Authorization token
You can create an ADMIN Authorization token by making a POST to the following REST URL: https://mymagento.com/rest/all/V1/integration/admin/token?username=MyName&password=MyPassword

An ADMIN Authorization token has a default lifetime of 1 hour, in order to extend the duration you can change this setting in the Magento backend.
In the backend navigate to Stores -> Configuration -> Services -> OAuth and then expand the Access Token Expiration tab, here you can change the duration of your ADMIN Authorization token.

INTEGRATION Authorization token (Magento 2.4.3 or lower only)
You can create an INTEGRATION token via the Magento backend.

  • Navigate to System -> Integrations.
  • Then click "Add New Integration" at the top right of the screen.
  • Enter a name for your new integration, and leave the other fields blank (they are optional).
  • Then click "Save" at the top right of the screen.
  • Now in the integration-list, click on Activate on your newly made integration.
  • Then click "Allow" at the top right of the screen.
  • You will now be presented with several codes. Copy past the "Access Token" and Click Done.

Access Control List Rules

In Magento you can give users, user roles with Access Control List Rules (ACL). These user roles are used to define permission of specific admins. Some mutations can only be used when these user roles are enabled for the user.

In order to activate user roles for users navigate to the following page in the Magento backend:
System > Permissions > User Roles

Select the user-group you want to activate the roles for and navigate to the tab Role Resources.

On this page you have 2 options in Resource Access:

  1. All (default), this gives the user access to all available roles.
  2. Custom, this allows you to add specific roles to a user.


Types

Order

Variable Type Description
pay_redirect_url String The URL to redirect to the Pay. checkout

PlaceOrderInput

Variable Type Description
pay_return_url String URL to send the customer to once the payment has finished.

Cart

Variable Type Description
logo String Logo for the selected payment method.
pay_issuers [PayIssuer] Issuers available for the selected payment method.

AvailablePaymentMethod

Variable Type Description
logo String Logo for the selected payment method.
pay_issuers [PayIssuer] Issuers available for the selected payment method.

PaymentMethod

Variable Type Description
logo String Logo for the selected payment method.
pay_issuers [PayIssuer] Issuers available for the selected payment method.

PayIssuer

Variable Type Description
id String URL to send the customer to, once the payment has finished.
name String URL to send the customer to, once the payment has finished.
visibleName String URL to send the customer to, once the payment has finished.
logo String URL to send the customer to, once the payment has finished.

paynlGetTransactionOutput

Variable Type Description
orderId String The Pay. order-ID.
state Int The state number.
stateName String The state name.
currency String The currency used in the payment
amount String The amount in cents.
currenyAmount String The amount in cents in the currency.
paidAmount String The paid amount in cents.
paidCurrenyAmount String The paid amount in cents in the currency.
refundAmount String The refunded amount in cents.
refundCurrenyAmount String The refunded amount in cents in the currency.
created String Date of creation.
orderNumber String The order number given by Magento.
isSuccess Boolean True, in case of a successfull payment.



Outputs

PaynlResultOutput

Variable Type Description
result Boolean The result of the action.
message String The message output from Pay.
Clone this wiki locally