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.
-
start_refund
(amount: Union[decimal.Decimal, float, int, None] = None, **kwargs) → decimal.Decimal¶ 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.
-