Adding a new payment gateway
Saleor uses a universal flow that each gateway should implement by providing a class that contains all the necessary methods.
All of the plugin methods take
previous_value as a second argument.
More information about
previous_value can be found here.
For a gateway to work correctly, you also need to specify
supported_currencies in your gateway configuration.
It determines in which currencies the gateway can be used.
For more information on the plugin implementation methods and configurations of supported currencies,
plugin.py file for an existing payment gateway.
You will also need to integrate your payment gateway into your storefront’s code.
get_client_token: A client token is a signed data blob that includes configuration and authorization information required by the payment gateway.
Client tokens should not be reused; a new client token should be generated for each payment request.
All the payment methods receive
payment_information as a dataclass:
You are in charge of configuring your gateway. Based on the existing implementations, you may use the
GatewayConfig class to configure your plugin.
authorize(payment_information): Authorization is a process of reserving the amount of money against the customer’s funding source. The money does not change hands until the authorization is captured.
refund(payment_information): A refund is a full or partial return of captured funds to the customer.
capture(payment_information): A transfer of the money that was reserved during the authorization stage.
void(payment_information): A cancellation of a pending authorization or capture.
process_payment(payment_information): Used for the checkout process, it should perform all the necessary steps to process a payment. It should use already-defined functions, like authorize and capture.
|Amount to be authorized/captured/charged/refunded|
|The internal payment ID|
|The graphql payment ID|
|The currency used in this transaction|
|IP address of the customer|
|Email address of the customer|
|Token used for transaction, provided by the gateway|
|Indicates that if a payment method for this user has already been stored in payment service, the system should use this payment method|
|Additional data used to provide gateway required data to process the payment|
|Define gateway name|
|Define if a gateway should also capture funds from the card. If false, payment should be only authorized|
|Define currencies which are supported by the gateway|
|List of parameters used for connecting to the payment’s gateway|
|If set to True, the system will save this payment method for this customer|
|Determines if gateway should enforce 3D secure verification during payment|
|GatewayResponse containing details about every transaction, with |
|Unique client token that will be used as an identifier in the payment process|
|Status showing whether the transaction was successful or not|
|Determines if additional action is required to complete the payment|
|Transaction kind, one of: action_to_confirm, auth, cancel, capture, capture_failed, confirm, external, pending, refund, refund_failed, refund_ongoing, refund_reversed, void|
|Amount that the gateway actually charged or authorized|
|Currency in which the gateway charged, needs to be an ISO 4217 code|
|Transaction ID as returned by the gateway|
|An error message, if one occurred. Should be |
|Credit Card information|
|Raw gateway response as a dict object. By default, it is |
|PSP additional data, required from the shopper, such as: to scan a QR code, to authenticate a payment with 3D Secure, or to log in to their bank's website to complete the payment.|
|Determines if we should create new transaction based on this response|
|The value which will be used in any filters over the transaction|
|Last four digits of card number|
|Card expiration year|
|Card expiration month|
|Customer name on the card|
Gateway-specific errors should be parsed to Saleor’s universal format.
Saleor unifies error codes across all gateways.
|Code||Graphql API Value||Description|
|Incorrect card number|
|Invalid card number|
|Incorrect CVV (or CVC)|
|Invalid CVV (or CVC)|
|Incorrect postal code|
|Incorrect address (excluding postal code)|
|Incorrect card expiration date|
|Expired payment method token|
|Transaction was declined by the gateway|
|Default error used for all cases not covered above|