Stored Payment Methods
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
) requested by the customer.
Listing user's stored payment methods
This feature is dedicated to third-party apps.
Requesting checkout.storedPaymentMethods
or User.storedPaymentMethods
field triggers synchronous requests to each app subscribed to 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
webhook can be found in the Stored Payment Methods guide.
The diagram below shows the workflow of fetching stored payment methods with a Payment App:
Requesting deletion of stored payment method
This feature is dedicated to third-party 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 or User.storedPaymentMethods will trigger the request to the payment app which was the owner of the payment method.
The following example shows how to use the storedPaymentMethodRequestDelete mutation to request deletion of stored payment method:
mutation {
storedPaymentMethodRequestDelete(
id: "YXBwOmR1bW15LnBheW1lbnQ6cGF5bWVudC1tZXRob2Qx"
channel: "default-channel"
) {
result
message
errors {
field
message
code
}
}
}
As a response, the mutation will return a result field which determines the status of the requested action. In case of a failure result, the errors list will contain details of the failed action.
The mutation will trigger the STORED_PAYMENT_METHOD_DELETE_REQUESTED webhook. For more details about this webhook, please refer to its documentation.
Tokenizing a new payment method
This feature is dedicated to third-party apps.
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.
Initializing the payment gateway for tokenizing a payment method
The paymentGatewayInitializeTokenization 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. The webhook is sent to the app with the provided id.
The id
is the ID of the payment app received from checkout.availablePaymentGateways or shop.availablePaymentGateways
. The JSON data
is passed to the payment app via the synchronous webhook.
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.data
: The JSONdata
returned by the payment app.id
: The ID of the payment method.
More details about the triggered webhook PAYMENT_GATEWAY_INITIALIZE_TOKENIZATION_SESSION can be found here.
Initializing payment method tokenization
The paymentMethodInitializeTokenization mutation starts the process of tokenizing the payment method. This mutation triggers the synchronous webhook PAYMENT_METHOD_INITIALIZE_TOKENIZATION_SESSION, which is sent to the app with the provided id.
The id
is the ID of the payment app received from checkout.availablePaymentGateways or shop.availablePaymentGateways. The JSON data is passed to the payment app via the synchronous webhook. The paymentFlowToSupport
is a value from the TokenizedPaymentFlowEnum. It represents the requested payment flow that the payment method should follow.
mutation {
paymentMethodInitializeTokenization(
id: "YXBwOmR1bW15LnBheW1lbnQ="
channel: "default-channel"
data: {"foo": "bar"}
paymentFlowToSupport: INTERACTIVE
) {
result
data
id
errors {
field
code
message
}
}
}
In the response, Saleor returns:
result
: The enum value of PaymentMethodTokenizationResult, which determines the status of the tokenization.data
: The JSONdata
returned by the payment app.id
: The ID of the payment method.
More details about the triggered PAYMENT_METHOD_INITIALIZE_TOKENIZATION_SESSION webhook can be found here.
Processing additional actions required to tokenize the payment method
The paymentMethodProcessTokenization mutation should be called when the payment app returns the result
PaymentMethodTokenizationResult.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.
The id
is the ID received as a response from paymentMethodInitializeTokenization or previous paymentMethodProcessTokenization calls. The JSON data
is passed to the payment app via the synchronous webhook.
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, which determines the status of the tokenization.data
: The JSONdata
returned by the payment app.id
: The ID of the payment method.
More details about the triggered PAYMENT_METHOD_PROCESS_TOKENIZATION_SESSION webhook can be found here.