Payment services during a checkout authorization

Payment Services for Adobe Commerce and Magento Open Source is your turnkey self-service solution, including sandbox testing and a simple setup, for providing robust and secure payment processing for your Commerce websites.

These steps describe the flow of requests and responses required to complete a typical checkout authorization with Payment Services enabled.

Checkout workflow

Payment Services sequence diagram

Run the getPaymentConfig query to fetch the payment configuration needed to render details about PayPal components, such as hosted fields, smart buttons, and Apple Pay.
Commerce returns payment configuration information.
Run setPaymentMethodOnCart to set the payment method.
Adobe Commerce returns a Cart object.
Run createPaymentOrder to begin the authorization process.
Commerce forwards the request to PayPal.
PayPal returns an id value.
Adobe Commerce generates a order_id and forwards the value in the mp_order_id field and the PayPal response in the id field.
(Optional) If hosted fields and the Signifyd integration are enabled, run getPaymentOrder.
(Optional) Adobe Commerce returns details about the payment order.
Run placeOrder.
Commerce sends an authorization request to PayPal.
PayPal returns the result to Commerce.
Commerce creates an order.

`setPaymentMethodOnCartInput` object

For the PayPal Smart Buttons and Apple Pay payment methods, you do not need to run the setPaymentMethodOnCart mutation. The hosted fields payment method requires that you run the mutation only if one of the following conditions are true:

You intend to vault a card by setting is_active_payment_token_enabler to true.
You have a stored payment method checkout where you intend to use a stored card by setting a public_hash value.

In these cases, the payment_method object must contain a payment_services_paypal_hosted_fields object.

`payment_services_paypal_hosted_fields` object

The payment_services_paypal_hosted_fields can contain the following attributes:

Attribute	Data Type	Description
`cardBin`	String	Card bin number
`cardExpiryMonth`	String	Expiration month of the card
`cardExpiryYear`	String	Expiration year of the card
`cardLast4`	String	Last four digits of the card
`holderName`	String	Name on card
`is_active_payment_token_enabler`	Boolean	Indicates whether a customer-entered credit/debit card should be tokenized for later usage. The default value is false. Required only if vaulting is enabled for Payment Services payment integration
`payments_order_id`	String	The unique order ID generated in Commerce if Payment Services is enabled after PayPal returns the `paypal_order_id`
`paypal_order_id`	String	The unique order ID generated by PayPal when receiving the authorization request
`payment_source`	String	The payment source for the payment method

`setPaymentMethodOnCart` mutation example

The following example shows the setPaymentMethodOnCart mutation constructed for the PayPal Hosted Fields payment method.

Request:

mutation {
    setPaymentMethodOnCart ( input: {
      cart_id: "uocGxUi5H97XFAMhY3s66q4aFYG3Bmdr",
      payment_method: {
        code: "payment_services_paypal_hosted_fields",
        payment_services_paypal_hosted_fields: {
          payment_source: "cc",
          payments_order_id: "mp-order-a4babd34-13d3-4ac0-b1b0-109bb7be1574",
          paypal_order_id: "9R90936863877801D",
          is_active_payment_token_enabler: true
        }
      }
    }
    ) {
       cart {
         id
         selected_payment_method {
           code
         }
       }
    }
  } 
Copied to your clipboard
mutation {
    setPaymentMethodOnCart ( input: {
      cart_id: "uocGxUi5H97XFAMhY3s66q4aFYG3Bmdr",
      payment_method: {
        code: "payment_services_paypal_hosted_fields",
        payment_services_paypal_hosted_fields: {
          payment_source: "cc",
          payments_order_id: "mp-order-a4babd34-13d3-4ac0-b1b0-109bb7be1574",
          paypal_order_id: "9R90936863877801D",
          is_active_payment_token_enabler: true
        }
      }
    }
    ) {
       cart {
         id
         selected_payment_method {
           code
         }
       }
    }
  }

Response:

{
  "data": {
    "setPaymentMethodOnCart": {
      "cart": {
        "id": "r8TKHa58b7Y8VaZHLyABNxrEdS8hJJTZ",
        "selected_payment_method": {
          "code": "payment_services_paypal_hosted_fields"
        }
      }
    }
  }
}
Copied to your clipboard
{
  "data": {
    "setPaymentMethodOnCart": {
      "cart": {
        "id": "r8TKHa58b7Y8VaZHLyABNxrEdS8hJJTZ",
        "selected_payment_method": {
          "code": "payment_services_paypal_hosted_fields"
        }
      }
    }
  }
}