Version: 2.10

Payment Gateways

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.

For more information on the plugin implementation methods, 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.

For more information on how to configure your plugin, see the Plugins topic.

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
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
reuse_sourceboolIndicates that if a payment method for this user has already been stored in payment service, the system should use this payment method

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
auto_captureboolDefine if a gateway should also capture funds from the card. If false, payment should be only authorized
template_pathstrPath to a template that will be rendered for the checkout
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

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
transaction_idstrTransaction ID as returned by the gateway
kindstrTransaction kind, one of: auth, capture, charge, refund, void
is_successboolStatus showing whether the transaction was successful or not
amountDecimalAmount that the gateway actually charged or authorized
currencystrCurrency in which the gateway charged, needs to be an ISO 4217 code
errorstrAn error message, if one occurred. Should be None if no error occurred
raw_responsedictRaw gateway response as a dict object. By default it is None

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