Skip to main content

Payment Gateways

caution

We are in the process of deprecating plugins in favor of apps. If you plan on building a new integration with Saleor, we recommend using apps instead.

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, see the plugin.py file for an existing payment gateway.

note

You will also need to integrate your payment gateway into your storefront’s code.

Client token

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.

note

All the payment methods receive payment_information as a dataclass: PaymentData.

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

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

refund(payment_information): A refund is a full or partial return of captured funds to the customer.

Capture payment

capture(payment_information): A transfer of the money that was reserved during the authorization stage.

Void

void(payment_information): A cancellation of a pending authorization or capture.

Process payment

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.

PaymentData

NameTypeDescription
amountDecimalAmount to be authorized/captured/charged/refunded
payment_idintThe internal payment ID
graphql_payment_idstrThe graphql payment ID
currencystrThe currency used in this transaction
billingAddressDataBilling information
shippingAddressDataShipping information
order_idintOrder ID
customer_ip_addressstrIP address of the customer
customer_emailstrEmail address of the customer
tokenstrToken used for transaction, provided by the gateway
customer_idstrCustomer ID
reuse_sourceboolIndicates that if a payment method for this user has already been stored in payment service, the system should use this payment method
datadictAdditional data used to provide gateway required data to process the payment

AddressData

NameType
first_namestr
last_namestr
company_namestr
street_address_1str
street_address_2str
citystr
city_areastr
postal_codestr
countrystr
country_areastr
phonestr

GatewayConfig

NameTypeDescription
gateway_namestrDefine gateway name
auto_captureboolDefine if a gateway should also capture funds from the card. If false, payment should be only authorized
supported_currenciesstrDefine currencies which are supported by the gateway
connection_paramsdictList of parameters used for connecting to the payment’s gateway
store_customerboolIf set to True, the system will save this payment method for this customer
require_3d_secureboolDetermines if gateway should enforce 3D secure verification during payment

Returns

NameTypeDescription
gateway_responseGatewayResponseGatewayResponse containing details about every transaction, with is_success set to True if no error occurred
client_tokenstrUnique client token that will be used as an identifier in the payment process

GatewayResponse

NameTypeDescription
is_successboolStatus showing whether the transaction was successful or not
action_requiredboolDetermines if additional action is required to complete the payment
kindstrTransaction kind, one of: action_to_confirm, auth, cancel, capture, capture_failed, confirm, external, pending, refund, refund_failed, refund_ongoing, refund_reversed, void
amountDecimalAmount that the gateway actually charged or authorized
currencystrCurrency in which the gateway charged, needs to be an ISO 4217 code
transaction_idstrTransaction ID as returned by the gateway
errorstrAn error message, if one occurred. Should be None if no error occurred
customer_idstrCustomer ID
card_infoCreditCardInfoCredit Card information
raw_responsedictRaw gateway response as a dict object. By default, it is None
action_required_datadictPSP 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.
transaction_already_processeddictDetermines if we should create new transaction based on this response
psp_referencestrThe value which will be used in any filters over the transaction

CreditCardInfo

NameTypeDescription
last_4strLast four digits of card number
exp_yearintCard expiration year
exp_monthintCard expiration month
brandstrCard brand
name_on_cardstrCustomer name on the card

Handling errors

Gateway-specific errors should be parsed to Saleor’s universal format.

Transaction errors

Saleor unifies error codes across all gateways.

CodeGraphql API ValueDescription
incorrect_numberINCORRECT_NUMBERIncorrect card number
invalid_numberINVALID_NUMBERInvalid card number
incorrect_cvvINCORRECT_CVVIncorrect CVV (or CVC)
invalid_cvvINVALID_CVVInvalid CVV (or CVC)
incorrect_zipINCORRECT_ZIPIncorrect postal code
incorrect_addressINCORRECT_ADDRESSIncorrect address (excluding postal code)
invalid_expiry_dateINVALID_EXPIRY_DATEIncorrect card expiration date
expiredEXPIREDExpired payment method token
declinedDECLINEDTransaction was declined by the gateway
processing_errorPROCESSING_ERRORDefault error used for all cases not covered above