> Documentation index: [Saleor](/llms.txt) · [This section](/developer/llms.txt)
> Source: https://docs.saleor.io/developer/payments/stored-payments

# Stored Payment Methods

<a id="stored-payment-methods"></a>

## Stored payment methods

A stored payment method is a payment method saved by a customer for later use. It allows the user to use it without the need to provide all payment details again. Saleor uses synchronous webhooks to notify the Payment App about actions related to stored payment methods (such as [`LIST_STORED_PAYMENT_METHODS`](/developer/extending/webhooks/synchronous-events/stored-payment-method.md#list-stored-payment-methods)) requested by the customer.

<a id="listing-users-stored-payment-methods"></a>

### Listing user's stored payment methods

info

This feature is dedicated to [third-party](/api-reference/apps/enums/app-type-enum.md#thirdparty) apps.

Requesting [`checkout.storedPaymentMethods`](/api-reference/checkout/objects/checkout.md#stored-payment-methods) or [`User.storedPaymentMethods`](/api-reference/users/objects/user.md#stored-payment-methods) field triggers synchronous requests to each app subscribed to [`LIST_STORED_PAYMENT_METHODS`](/api-reference/webhooks/enums/webhook-event-type-sync-enum.md#list-stored-payment-methods) webhook. In response, Saleor returns a list of payment methods from the subscribed apps. Stored payment methods can be used in further steps of payment processing.

All details related to [`LIST_STORED_PAYMENT_METHODS`](/api-reference/webhooks/enums/webhook-event-type-sync-enum.md#list-stored-payment-methods) webhook can be found [in the Stored Payment Methods guide](/developer/extending/webhooks/synchronous-events/stored-payment-method.md#list-stored-payment-methods).

The diagram below shows the workflow of fetching stored payment methods with a Payment App:

```mermaid
sequenceDiagram
    actor User
    User->>Storefront: Ask for their stored payment methods
    Storefront->>Saleor: checkout.storedPaymentMethods query
    par For each payment gateway
      Saleor->>Payment App: LIST_STORED_PAYMENT_METHODS webhook
      Payment App->>Saleor: List of stored payment methods for the user
    end
    Saleor->>Storefront: List of stored payment methods
    Storefront->>User: Sees a list of saved payment methods
```

<a id="requesting-deletion-of-stored-payment-method"></a>

### Requesting deletion of stored payment method

info

This feature is dedicated to [third-party](/api-reference/apps/enums/app-type-enum.md#thirdparty) apps.

The user can request a deletion of their stored payment methods. Saleor doesn't store directly a user's payment methods or transmit payment method details. It is a part of the responsibility of the payment app. The request deletion will be sent to the payment app which owns the specific stored payment method. Saleor will also invalidate the cache of stored-payment-methods. Fetching [checkout.storedPaymentMethods](/api-reference/checkout/objects/checkout.md#stored-payment-methods) or [User.storedPaymentMethods](/api-reference/users/objects/user.md#stored-payment-methods) will trigger the request to the payment app which was the owner of the payment method.

```mermaid
sequenceDiagram
   actor User
   User->>Storefront: Request a delete of<br>stored payment methods
   Storefront->>Saleor: Mutation<br>storedPaymentMethodRequestDelete
   Saleor->>Payment App: STORED_PAYMENT_METHOD_DELETE_REQUESTED<br>webhook
   Payment App->>Saleor: Status of the request
   Saleor->>Storefront: Return status and<br>message from app
   Storefront->>User: Display result
```

The following example shows how to use the [storedPaymentMethodRequestDelete](/api-reference/payments/mutations/payment-gateway-initialize.md) mutation to request deletion of stored payment method:

**Mutation**

```graphql
mutation StoredPaymentMethodRequestDelete($id: ID!, $channel: String!) {
  storedPaymentMethodRequestDelete(id: $id, channel: $channel) {
    result
    errors {
      field
      message
      code
    }
  }
}
```

**Variables**

```json
{
  "id": "YXBwOmR1bW15LnBheW1lbnQ6cGF5bWVudC1tZXRob2Qx",
  "channel": "default-channel"
}
```

As a response, the mutation will return a [result](/api-reference/payments/enums/stored-payment-method-request-delete-result.md) field which determines the status of the requested action. In case of a failure result, the [errors](/api-reference/payments/objects/payment-method-request-delete-error.md) list will contain details of the failed action.

The mutation will trigger the [STORED\_PAYMENT\_METHOD\_DELETE\_REQUESTED](/api-reference/webhooks/enums/webhook-event-type-sync-enum.md#stored-payment-method-delete-requested) webhook. For more details about this webhook, please refer to its [documentation](/developer/extending/webhooks/synchronous-events/stored-payment-method.md#delete-stored-payment-method-requested).

<a id="tokenizing-a-new-payment-method"></a>

### Tokenizing a new payment method

info

This feature is dedicated to [third-party](/api-reference/apps/enums/app-type-enum.md#thirdparty) apps.

info

Tokenizing a payment method can also be done during the checkout process. Please refer to your payment app's documentation for details.

Customers can request to store their payment method for later use. The tokenization process is handled by the payment app subscribed to synchronous webhooks. The process consists of three steps: initialization of the payment gateway (if required), tokenizing the payment method, and handling additional actions (if required). Each step has its dedicated mutation and webhook, which are described below.

The diagram illustrates the general flow of tokenizing a payment method. The process may vary slightly for specific payment providers; for example, some payment providers may not require the initialization of the payment gateway.

```mermaid
sequenceDiagram
  Storefront->>+Saleor: shop.availablePaymentGateways query
  Saleor-->>-Storefront: Returns a list of payment gateways
  Storefront->>+Saleor: (If required) paymentGatewayInitializeTokenization<br>mutation to<br>initialize the paymentApp
  Saleor->>PaymentApp: PAYMENT_GATEWAY_INITIALIZE_TOKENIZATION_SESSION<br>webhook
  PaymentApp->>+PaymentProviderAPI: Process the request
  PaymentProviderAPI-->>-PaymentApp: OK
  PaymentApp-->>Saleor: Return data required to<br>start payment method<br>tokenization
  Saleor-->>-Storefront: Returns data from<br>payment apps
  Storefront ->>+ PaymentProviderAPI: Process the action on the frontend side
  PaymentProviderAPI -->>- Storefront: Ok
  Storefront ->>+ Saleor: paymentMethodInitializeTokenization<br>mutation to start<br>process of<br>tokenization
  Saleor ->>+ PaymentApp: PAYMENT_METHOD_INITIALIZE_TOKENIZATION_SESSION<br>webhook
  PaymentApp ->>+ PaymentProviderAPI: Process the<br>payment<br>method tokenization
  PaymentProviderAPI -->>- PaymentApp: Result of the tokenization
  PaymentApp -->>- Saleor: Result of the tokenization
  Saleor -->>- Storefront: Result of the tokenization
  Storefront ->>+ PaymentProviderAPI: (If required) Process additional<br>actions to finalize<br>the payment method tokenization
  PaymentProviderAPI -->>- Storefront: Result
  loop Processing in a loop. Until finalizing all additional actions
      Storefront ->>+ Saleor: (If required)<br>paymentMethodProcessTokenization<br>mutation to process additional action
      Saleor ->>+ PaymentApp: PAYMENT_METHOD_PROCESS_TOKENIZATION_SESSION<br>webhook
      PaymentApp ->>+ PaymentProviderAPI: Process<br> additional<br>action
      PaymentProviderAPI -->>- PaymentApp: Result of<br>additional<br>action
      PaymentApp -->>- Saleor: Result of<br>additional<br>action
      Saleor -->>- Storefront: Result of<br>additional<br>action
  end
```

<a id="initializing-the-payment-gateway-for-tokenizing-a-payment-method"></a>

#### Initializing the payment gateway for tokenizing a payment method

The [paymentGatewayInitializeTokenization](/api-reference/payments/mutations/payment-gateway-initialize-tokenization.md) mutation should be used when the payment gateway needs to be initialized first. For example, when retrieving the data required to initialize the drop-in on the storefront side.

This mutation triggers the synchronous webhook [PAYMENT\_GATEWAY\_INITIALIZE\_TOKENIZATION\_SESSION](/api-reference/webhooks/enums/webhook-event-type-sync-enum.md#payment-gateway-initialize-tokenization-session). The webhook is sent to the app with the provided [id](/api-reference/payments/mutations/payment-gateway-initialize-tokenization.md#id).

The `id` is the ID of the payment app received from [checkout.availablePaymentGateways](/api-reference/checkout/objects/checkout.md#available-payment-gateways) or `shop.availablePaymentGateways`. The JSON `data` is passed to the payment app via the synchronous webhook.

```graphql
mutation PaymentGatewayInitializeTokenization($id: String!, $channel: String!, $data: JSON) {
  paymentGatewayInitializeTokenization(id: $id, channel: $channel, data: $data) {
    result
    data
    errors {
      field
      code
      message
    }
  }
}
```

In the response, Saleor returns:

-   `result`: The enum value of [PaymentGatewayInitializeTokenizationResult](/api-reference/payments/enums/payment-gateway-initialize-tokenization-result.md).
-   `data`: The JSON `data` returned by the payment app.
-   `id`: The ID of the payment method.

More details about the triggered webhook [PAYMENT\_GATEWAY\_INITIALIZE\_TOKENIZATION\_SESSION](/api-reference/webhooks/enums/webhook-event-type-sync-enum.md#payment-gateway-initialize-tokenization-session) can be found [here](/developer/extending/webhooks/synchronous-events/stored-payment-method.md#initialize-payment-gateway-session).

<a id="initializing-payment-method-tokenization"></a>

#### Initializing payment method tokenization

The [paymentMethodInitializeTokenization](/api-reference/payments/mutations/payment-method-initialize-tokenization.md) mutation starts the process of tokenizing the payment method. This mutation triggers the synchronous webhook [PAYMENT\_METHOD\_INITIALIZE\_TOKENIZATION\_SESSION](/api-reference/webhooks/enums/webhook-event-type-sync-enum.md#payment-method-initialize-tokenization-session), which is sent to the app with the provided [id](/api-reference/payments/mutations/payment-method-initialize-tokenization.md#id).

The `id` is the ID of the payment app received from [checkout.availablePaymentGateways](/api-reference/checkout/objects/checkout.md#available-payment-gateways) or [shop.availablePaymentGateways](/api-reference/miscellaneous/objects/shop.md#available-payment-gateways). The JSON [data](/api-reference/payments/mutations/payment-method-initialize-tokenization.md#data) is passed to the payment app via the synchronous webhook. The `paymentFlowToSupport` is a value from the [TokenizedPaymentFlowEnum](/api-reference/payments/enums/tokenized-payment-flow-enum.md). It represents the requested payment flow that the payment method should follow.

**Mutation**

```graphql
mutation paymentMethodInitializeTokenization($id: String!, $channel: String!, $paymentFlowToSupport: TokenizedPaymentFlowEnum!, $data: JSON) {
  paymentMethodInitializeTokenization(
    id: $id
    channel: $channel
    data: $data
    paymentFlowToSupport: $paymentFlowToSupport
  ) {
    result
    data
    id
    errors {
      field
      code
      message
    }
  }
}
```

**Variables**

```json
{
  "id": "YXBwOmR1bW15LnBheW1lbnQ=",
  "channel": "default-channel",
  "data": {
    "foo": "bar"
  },
  "paymentFlowToSupport": "INTERACTIVE"
}
```

In the response, Saleor returns:

-   `result`: The enum value of [PaymentMethodTokenizationResult](/api-reference/payments/enums/payment-method-tokenization-result.md), which determines the status of the tokenization.
-   `data`: The JSON `data` returned by the payment app.
-   `id`: The ID of the payment method.

More details about the triggered [PAYMENT\_METHOD\_INITIALIZE\_TOKENIZATION\_SESSION](/api-reference/webhooks/enums/webhook-event-type-sync-enum.md#payment-method-initialize-tokenization-session) webhook can be found [here](/developer/extending/webhooks/synchronous-events/stored-payment-method.md#initialize-payment-method-tokenization).

<a id="processing-additional-actions-required-to-tokenize-the-payment-method"></a>

#### Processing additional actions required to tokenize the payment method

The [paymentMethodProcessTokenization](/api-reference/payments/mutations/payment-method-process-tokenization.md) mutation should be called when the payment app returns the `result` [PaymentMethodTokenizationResult.ADDITIONAL\_ACTION\_REQUIRED](/api-reference/payments/enums/payment-method-tokenization-result.md#additional-action-required). This mutation is dedicated to processing additional actions required to finalize the tokenization of the payment method.

This mutation triggers the synchronous webhook [PAYMENT\_METHOD\_PROCESS\_TOKENIZATION\_SESSION](/api-reference/webhooks/enums/webhook-event-type-sync-enum.md#payment-method-process-tokenization-session).

The `id` is the ID received as a response from [paymentMethodInitializeTokenization](/api-reference/payments/mutations/payment-method-initialize-tokenization.md) or previous [paymentMethodProcessTokenization](/api-reference/payments/mutations/payment-method-process-tokenization.md) calls. The JSON `data` is passed to the payment app via the synchronous webhook.

```graphql
mutation PaymentMethodProcessTokenization(
  $id: String!
  $channel: String!
  $data: JSON
) {
  paymentMethodProcessTokenization(id: $id, channel: $channel, data: $data) {
    result
    data
    id
    errors {
      field
      code
      message
    }
  }
}
```

In the response, Saleor returns:

-   `result`: The enum value of [PaymentMethodTokenizationResult](/api-reference/payments/enums/payment-method-tokenization-result.md), which determines the status of the tokenization.
-   `data`: The JSON `data` returned by the payment app.
-   `id`: The ID of the payment method.

More details about the triggered [PAYMENT\_METHOD\_PROCESS\_TOKENIZATION\_SESSION](/api-reference/webhooks/enums/webhook-event-type-sync-enum.md#payment-method-process-tokenization-session) webhook can be found [here](/developer/extending/webhooks/synchronous-events/stored-payment-method.md#process-additional-actions-for-payment-method-tokenization).