Customization - Payment API

Django-getpaid was designed to be very customizable. In this document you’ll read about the Payment API which lets you customize most of the mechanics of django-getpaid.

Since most Payment methods act as interface to PaymentProcessor, you can use this to add extra layer between the Payment and the PaymentProcessor.

Basic Order API

class getpaid.models.AbstractOrder(*args, **kwargs)

Please consider setting either primary or secondary key of your Orders to UUIDField. This way you will hide your volume which is valuable business information that should be kept hidden. If you set it as secondary key, remember to use dbindex=True (primary keys are indexed by default). Read more:

get_return_url(*args, success=None, **kwargs) → str

Method used to determine the final url the client should see after returning from gateway. Client will be redirected to this url after backend handled the original callback (i.e. updated payment status) and only if SUCCESS_URL or FAILURE_URL settings are NOT set. By default it returns the result of get_absolute_url

get_absolute_url() → str

Standard method recommended in Django docs. It should return the URL to see details of particular Payment (or usually - Order).

is_ready_for_payment() → bool

Most of the validation is made in PaymentMethodForm but if you need any extra validation. For example you most probably want to disable making another payment for order that is already paid.

You can raise ValidationError if you want more verbose error message.

get_items() → List[getpaid.types.ItemInfo]

There are backends that require some sort of item list to be attached to the payment. But it’s up to you if the list is real or contains only one item called “Payment for stuff in {myshop}” ;)

Returns:List of ItemInfo dicts. Default: order summary.
Return type:List[ItemInfo]
get_total_amount() → decimal.Decimal

This method must return the total value of the Order.

Returns:Decimal object
get_buyer_info() → getpaid.types.BuyerInfo

This method should return dict with necessary user info. For most backends email should be sufficient. Refer to :class`BuyerInfo` for expected structure.

get_description() → str
Returns:Description of the Order. Should return the value of appropriate field.

Basic Payment API

AbstractPayment defines a minimal set of fields that are expected by BaseProcessor API. If you want to have it completely your own way, make sure to provide properties linking your fieldnames to expected names.

class getpaid.models.AbstractPayment(*args, **kwargs)

UUID to not disclose your volume.


ForeignKey to (swappable) Order model.


Decimal value with 4 decimal places. Total value of the Order that needs to be paid.


Currency code in ISO 4217 format.


Status of the Payment - one of PAYMENT_STATUS_CHOICES. This field is managed using django-fsm.


Identifier of the backend processor used to handle this Payment.


Datetime of Payment creation - automated.


Datetime the Payment has been completed. Defaults to NULL.


Amount actually paid by the buyer. Should be equal amount_required if backend does not support partial payments. Will be smaller than that after partial refund is done.


Amount that has been pre-authed by the buyer. Needs to be charged to finalize payment or released if the transaction cannot be fulfilled.


Amount that was refunded. Technically this should be equal to amount_required - amount_paid.


ID of the payment on paywall’s system. Optional.


Payment description (max 128 chars).


Field representing the result of fraud check (only on supported backends).


Message provided along with the fraud status.

get_processor() → getpaid.processor.BaseProcessor

Returns the processor instance for the backend that was chosen for this Payment. By default it takes it from global backend registry and tries to import it when it’s not there. You most probably don’t want to mess with this.

get_unique_id() → str

Return unique identifier for this payment. Most paywalls call this “external id”. Default: str( which is uuid4.

get_items() → List[getpaid.types.ItemInfo]

Some backends require the list of items to be added to Payment.

This method relays the call to Order. It is here simply because you can change the Order’s fieldname when customizing Payment model. In that case you need to overwrite this method so that it properly returns a list.

get_form(*args, **kwargs) → django.forms.forms.BaseForm

Interfaces processor’s get_form.

Returns a Form to be used on intermediate page if the method returned by get_redirect_method is ‘POST’.

get_template_names(view=None) → List[str]

Interfaces processor’s get_template_names.

Used to get templates for intermediate page when get_redirect_method returns ‘POST’.

handle_paywall_callback(request, **kwargs) → django.http.response.HttpResponse

Interfaces processor’s handle_paywall_callback.

Called when ‘PUSH’ flow is used for a backend. In this scenario paywall will send a request to our server with information about the state of Payment. Broker can send several such requests during Payment’s lifetime. Backend should analyze this request and return appropriate response that can be understood by paywall.

Parameters:request – Request sent by paywall.
Returns:HttpResponse instance
fetch_status() → getpaid.types.PaymentStatusResponse

Interfaces processor’s fetch_payment_status.

Used during ‘PULL’ flow. Fetches status from paywall and proposes a callback depending on the response.

fetch_and_update_status() → getpaid.types.PaymentStatusResponse

Used during ‘PULL’ flow to automatically fetch and update Payment’s status.

prepare_transaction(request: Optional[django.http.request.HttpRequest] = None, view: Optional[django.views.generic.base.View] = None, **kwargs) → django.http.response.HttpResponse

Interfaces processor’s prepare_transaction().

prepare_transaction_for_rest(request: Optional[django.http.request.HttpRequest] = None, view: Optional[django.views.generic.base.View] = None, **kwargs) → getpaid.types.RestfulResult

Helper function returning data as dict to better integrate with Django REST Framework.

confirm_prepared(**kwargs) → None

Used to confirm that paywall registered POSTed form.

confirm_lock(amount: Union[decimal.Decimal, float, int, None] = None, **kwargs) → None

Used to confirm that certain amount has been locked (pre-authed).

charge(amount: Union[decimal.Decimal, float, int, None] = None, **kwargs) → getpaid.types.ChargeResponse

Interfaces processor’s charge().

confirm_charge_sent(**kwargs) → None

Used during async charge cycle - after you send charge request, the confirmation will be sent to callback endpoint.

confirm_payment(amount: Union[decimal.Decimal, float, int, None] = None, **kwargs) → None

Used when receiving callback confirmation.

mark_as_paid(**kwargs) → None

Marks payment as fully paid if condition is met.

release_lock(**kwargs) → decimal.Decimal

Interfaces processor’s charge().

start_refund(amount: Union[decimal.Decimal, float, int, None] = None, **kwargs) → decimal.Decimal

Interfaces processor’s charge().

cancel_refund(**kwargs) → bool

Interfaces processor’s charge().

confirm_refund(amount: Union[decimal.Decimal, float, int, None] = None, **kwargs) → None

Used when receiving callback confirmation.

mark_as_refunded(**kwargs) → None

Verify if refund was partial or full.

fail(**kwargs) → None

Sets Payment as failed.