API

payments.core.provider_factory(variant: str, payment: BasePayment | None = None)

Return the provider instance based on variant.

Parameters:

variant – The name of a variant defined in PAYMENT_VARIANTS.

class payments.models.BasePayment(*args, **kwargs)

Represents a single transaction. Each instance has one or more PaymentItem.

property attrs

A JSON-serialised wrapper around extra_data.

This property exposes a a dict or list which is serialised into the extra_data text field. Usage of this wrapper is preferred over accessing the underlying field directly.

You may think of this as a JSONField which is saved to the extra_data column.

capture(amount=None)

Capture a pre-authorized payment.

Note that not all providers support this method.

change_status(status: PaymentStatus | str, message='')

Updates the Payment status and sends the status_changed signal.

created

Creation date and time

currency

Currency code (may be provider-specific)

get_failure_url() → str

URL where users will be redirected after a failed payment.

Return the URL where users will be redirected after a failed attempt to complete a payment. This is usually a page explaining the situation to the user with an option to retry the payment.

Note that the URL may contain the ID of this payment, allowing the target page to show relevant contextual information.

Subclasses MUST implement this method.

get_form(data=None)

Return a form to be rendered to complete this payment.

Please note that this may raise a RedirectNeeded exception. In this case, the user should be redirected to the supplied URL.

Note that not all providers support a pure form-based flow; some will immediately raise RedirectNeeded.

get_purchased_items() → Iterable[PurchasedItem]

Return an iterable of purchased items.

This information is sent to the payment processor when initiating the payment flow. See PurchasedItem for details.

Subclasses MUST implement this method.

get_success_url() → str

URL where users will be redirected after a successful payment.

Return the URL where users will be redirected after a successful payment. This is usually a page showing a payment summary, though it’s application-dependant what to show on it.

Note that the URL may contain the ID of this payment, allowing the target page to show relevant contextual information.

Subclasses MUST implement this method.

modified

Date and time of last modification

release()

Release a pre-authorized payment.

Note that not all providers support this method.

save(**kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

status

Transaction status

total

Total amount (gross)

transaction_id

Transaction ID (if applicable)

class payments.PurchasedItem(name: str, quantity: int, price: Decimal, currency: str, sku: str, tax_rate: Decimal | None = None)

A single item in a purchase.

currency: str

Alias for field number 3

name: str

Alias for field number 0

price: Decimal

Alias for field number 2

quantity: int

Alias for field number 1

sku: str

Alias for field number 4

tax_rate: Decimal | None

Alias for field number 5