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: https://docs.djangoproject.com/en/3.0/ref/models/fields/#uuidfield

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)
id

UUID to not disclose your volume.

order

ForeignKey to (swappable) Order model.

amount_required

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

currency

Currency code in ISO 4217 format.

status

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

backend

Identifier of the backend processor used to handle this Payment.

created_on

Datetime of Payment creation - automated.

last_payment_on

Datetime the Payment has been completed. Defaults to NULL.

amount_paid

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_locked

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_refunded

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

external_id

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

description

Payment description (max 128 chars).

fraud_status

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

fraud_message

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(self.id) 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.