Skip to main content

Introduction

caution

This feature is in the Feature Preview stage, which means that it is available for experimentation and feedback. However, it is still undergoing development and is subject to modifications.

A stored payment method is a payment method that can be used later by customers without providing all payment details. Saleor has synchronous webhooks that allow delegating the stored payment methods management to payment apps.

Key concepts​

The HANDLE_PAYMENTS permission is required for the App to receive store payment method webhooks.

The usage of the webhook is strictly related to the usage of stored payment method. You can find more details about it in the Stored Payment Methods.

info

This feature is dedicated to third-party apps.

List stored payment methods​

LIST_STORED_PAYMENT_METHODS

info

This feature was introduced in Saleor 3.15.

A synchronous webhook is called when the user wants to fetch stored payment methods. Triggered when a customer requested a field User.storedPaymentMethod, checkout.storedPaymentMethods.

The webhook expects to return a list of payment methods that are assigned to the customer. The payment methods from the webhook response will be returned as a response for User.storedPaymentMethod, checkout.storedPaymentMethods fields.

info

To reduce the number of HTTP requests triggered to the payment app, the response is cached on Saleor side. Saleor will trigger a new request when the cache expires or becomes invalid.

Request​

Saleor will send a LIST_STORED_PAYMENT_METHODS webhook by using the ListStoredPaymentMethods subscription type or with a pre-defined payload in case of a missing subscription query.

You can find more details about building webhook subscription query here.

The example below shows a sample webhook subscription defined to list stored payment methods:

subscription {
  event {
    ... on ListStoredPaymentMethods {
      user {
        id
      }
      channel {
        id
      }
    }
  }
}

The example below shows the pre-defined payload that will be used in the case when a subscription query is not provided:

{
  "user_id": "VXNlcjoyOA==",
  "channel_slug": "main"
}

Response​

The app needs to return a list of stored payment methods that can be used by customer.

The response in this case should have the following structure:

{
  "paymentMethods": [
    {
      "id": "<ID of stored payment method>",
      "supportedPaymentFlows": "<list of supported flows that can be performed with this payment method>",
      "type": "<type of the payment method. For example: Credit Card>",
      // "creditCardInfo": [Optional] credit card information if the payment method is a credit card.
      "creditCardInfo": {
        "brand": "<credit card brand>",
        "lastDigits": "<last digits>",
        "expMonth": "<expiration month>",
        "expYear": "<expiration year>",
        "firstDigits": "<[Optional] first digits>"
      },
      "name": "<[Optional] name of the payment method. For example: last 4 digits of credit card, obfuscated email>",
      "data": "<[Optional] JSON data that will be returned to client>"
    }
  ]
}
Expand ▼

Below are the possible supportedPaymentFlows values and their explanations:

  • INTERACTIVE - When the user needs to be present to prove the ownership of the payment method (instead of, for example, a subscription-based payment which does not require user interaction).
warning

There is no default payment flow. If the supportedPaymentFlows list is empty, the payment method will not be returned.

Delete stored payment method requested​

STORED_PAYMENT_METHOD_DELETE_REQUESTED

info

This feature was introduced in Saleor 3.16.

A synchronous webhook STORED_PAYMENT_METHOD_DELETE_REQUESTED is called when the user requests the deletion of the stored payment method. User can request the deletion of the stored payment method by triggering the mutation storedPaymentMethodRequestDelete. More details about the flow can be found here.

Request​

The example below shows a sample webhook subscription defined for STORED_PAYMENT_METHOD_DELETE_REQUESTED webhook:

subscription {
  event {
    ... on StoredPaymentMethodDeleteRequested {
      user {
        id
      }
      paymentMethodId
      channel {
        currencyCode
      }
    }
  }
}

The example below shows the pre-defined payload that will be used in the case when a subscription query is not provided:

{
  "payment_method_id": "payment-method-id",
  "user_id": "VXNlcjoyOA==",
  "channel_slug": "main"
}

Response​

The app needs to return the status of the requested deletion.

The response in this case should have the following structure:

  • Response that reports successful delete action
{
  "result": "SUCCESSFULLY_DELETED"
}
  • Response that reports failure to delete action
{
  "result": "FAILED_TO_DELETE",
  "error": "Error message that will be passed to the frontend."
}

The result field is an enum value of StoredPaymentMethodRequestDeleteResult. In case of returning failure result, the error message will be attached to the error returned by storedPaymentMethodRequestDelete mutation.

Initialize payment gateway session​

PAYMENT_GATEWAY_INITIALIZE_TOKENIZATION_SESSION

info

This feature was introduced in Saleor 3.16.

The synchronous PAYMENT_GATEWAY_INITIALIZE_TOKENIZATION_SESSION webhook is triggered when a customer requests the initialization of the payment gateway to tokenize a payment method. This webhook is activated by executing the paymentGatewayInitializeTokenization mutation.

The webhook payload includes details about the customer, channel, and data. The data field contains the JSON data provided as input in the paymentGatewayInitializeTokenization mutation.

The response must adhere to the expected format and will be returned within the paymentGatewayInitializeTokenization mutation.

Request​

Saleor will send a PAYMENT_GATEWAY_INITIALIZE_TOKENIZATION_SESSION webhook using the PaymentGatewayInitializeTokenizationSession subscription type or with a predefined payload in case of a missing subscription query.

For more details on building webhook subscription queries, refer to this documentation.

The example below demonstrates a sample webhook subscription defined to handle the initialization of the payment gateway for tokenizing a payment method:

subscription {
  event {
    ... on PaymentGatewayInitializeTokenizationSession {
      user {
        id
      }
      channel {
        id
      }
      data
    }
  }
}

The following example illustrates the predefined payload that will be used if a subscription query is not provided:

{
  "user_id": "VXNlcjoyOA==",
  "channel_slug": "main",
  "data": { "data": "from-input" }
}

Response​

The application should return the status of the initialization and optionally data required to finalize the initialization on the client side.

  • Response indicating successful initialization:
{
  "result": "SUCCESSFULLY_INITIALIZED",
  "data": { "data": "additional-data" }
}
  • Response indicating failed initialization:
{
  "result": "FAILED_TO_INITIALIZE",
  "error": "Error message that will be passed to the frontend."
}

The result field is an enum value of PaymentGatewayInitializeTokenizationResultEnum. In the event of returning a failure result, the errors message will be attached to the error returned by the paymentGatewayInitializeTokenization mutation.

Initialize payment method tokenization​

PAYMENT_METHOD_INITIALIZE_TOKENIZATION_SESSION

info

This feature was introduced in Saleor 3.16.

The synchronous PAYMENT_METHOD_INITIALIZE_TOKENIZATION_SESSION webhook is triggered when a customer requests the tokenization of a payment method. This webhook is activated by executing the paymentMethodInitializeTokenization mutation.

The webhook payload includes details about the customer, channel, and data. The data field contains the JSON data provided as input in the paymentMethodInitializeTokenization mutation.

The response must conform to the expected format and will be returned within the paymentMethodInitializeTokenization mutation.

Request​

Saleor will send a PAYMENT_METHOD_INITIALIZE_TOKENIZATION_SESSION webhook using the PaymentMethodInitializeTokenizationSession subscription type or with a predefined payload in case of a missing subscription query.

For detailed information on building webhook subscription queries, please refer to this documentation.

The following example demonstrates a sample webhook subscription defined to handle the tokenization of a payment method:

subscription {
  event {
    ... on PaymentMethodInitializeTokenizationSession {
      paymentFlowToSupport
      user {
        id
      }
      channel {
        id
      }
      data
    }
  }
}

The next example illustrates the predefined payload that will be used if a subscription query is not provided:

{
  "user_id": "VXNlcjoyOA==",
  "channel_slug": "main",
  "data": { "data": "from-input" },
  "payment_flow_to_support": "interactive"
}

Response​

  • A response indicating successful tokenization should include the result, the id of the stored payment method, and optionally data to be passed to the client:
{
  "result": "SUCCESSFULLY_TOKENIZED",
  "id": "payment-method-id",
  "data": { "data": "additional-data" }
}
  • A response indicating a required additional action should contain the expected result, the id, and optionally data:
{
  "result": "ADDITIONAL_ACTION_REQUIRED",
  "id": "id",
  "data": { "data": "additional-data" }
}
  • A response indicating a pending tokenization:
{
  "result": "PENDING",
  "data": { "data": "additional-data" }
}
  • A response indicating a failed tokenization:
{
  "result": "FAILED_TO_TOKENIZE",
  "error": "Error message that will be passed to the frontend."
}

The result field is an enum value of PaymentMethodTokenizationResultEnum. In case of a failure result, the error message will be attached to the error returned by the paymentMethodInitializeTokenization mutation.

Process additional actions for payment method tokenization​

PAYMENT_METHOD_PROCESS_TOKENIZATION_SESSION

info

This feature was introduced in Saleor 3.16.

The synchronous PAYMENT_METHOD_PROCESS_TOKENIZATION_SESSION webhook is triggered when a customer requests to process additional actions required for tokenizing the payment method. This webhook is activated by executing the paymentMethodProcessTokenization mutation.

The webhook payload includes details about the customer, channel, and [data]. The data field contains the JSON data provided as input in the paymentMethodProcessTokenization mutation.

The response must adhere to the expected format and will be returned within the paymentMethodProcessTokenization mutation.

Request​

Saleor will send a PAYMENT_METHOD_PROCESS_TOKENIZATION_SESSION webhook using the PaymentMethodProcessTokenizationSession subscription type or with a predefined payload in case of a missing subscription query.

For detailed information on building webhook subscription queries, please refer to this documentation.

The following example demonstrates a sample webhook subscription defined to handle the tokenization of a payment method:

subscription {
  event {
    ... on PaymentMethodProcessTokenizationSession {
      id
      user {
        id
      }
      channel {
        id
      }
      data
    }
  }
}

The next example illustrates the predefined payload that will be used if a subscription query is not provided:

{
  "user_id": "VXNlcjoyOA==",
  "channel_slug": "main",
  "data": { "data": "from-input" }
}

Response​

  • A response indicating successful tokenization should include the result, the id of the stored payment method, and optionally data to be passed to the client:
{
  "result": "SUCCESSFULLY_TOKENIZED",
  "id": "payment-method-id",
  "data": { "data": "additional-data" }
}
  • A response indicating a required additional action should contain the expected result, an id, and optional data:
{
  "result": "ADDITIONAL_ACTION_REQUIRED",
  "id": "payment-method-id",
  "data": { "data": "additional-data" }
}
  • A response indicating a pending tokenization:
{
  "result": "PENDING",
  "data": { "data": "additional-data" }
}
  • A response indicating a failed tokenization:
{
  "result": "FAILED_TO_TOKENIZE",
  "error": "Error message that will be passed to the frontend."
}

The result field is an enum value of PaymentMethodTokenizationResultEnum. In case of a failure result, the error message will be attached to the error returned by the paymentMethodProcessTokenization mutation.