payments.views package

Submodules

payments.views.admin module

payments.views.admin.admin_members_with_balance(request)

Shows any open balances held by members

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse

payments.views.admin.admin_members_with_balance_csv(request)

Shows any open balances held by members - as CSV

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse - CSV

payments.views.admin.admin_orgs_with_balance(request)

Shows any open balances held by orgs

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse

payments.views.admin.admin_orgs_with_balance_csv(request)

Shows any open balances held by orgs - as CSV

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse - CSV

payments.views.admin.admin_payments_static_history(request)

history for static data for payments

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse

payments.views.admin.admin_payments_static_org_override(request)

Manage static data for individual orgs (override default values)

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse

payments.views.admin.admin_payments_static_org_override_add(request)

Manage static data for individual orgs (override default values) This screen adds an override

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse

payments.views.admin.admin_view_specific_transactions(request, trans_type)

Shows transactions of a specific type. e.g. manual adjustments or settlements

Parameters:

• request (HTTPRequest) – standard request object

• trans_type (str) – which transactions to show

Returns:

HTTPResponse (Can be CSV)

payments.views.admin.manual_adjust_member(request)

make a manual adjustment on a member account

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse

payments.views.admin.manual_adjust_org(request, org_id=None, default_transaction=None)

make a manual adjustment on an organisation account

Parameters:

• request (HTTPRequest) – standard request object

• org_id – optional id of organisation

• default_transaction – Allows a default for transaction type to be selected

Returns:

HTTPResponse

payments.views.admin.refund_stripe_transaction_sub(stripe_item, amount, description, counterparty=None)

Atomic transaction update for refunds

payments.views.admin.settlement(request)

process payments to organisations. This is expected to be a monthly

activity.

At certain points in time an administrator will clear out the balances of the organisations accounts and transfer actual money to them through the banking system. This is not currently possible to do electronically so this is a manual process.

The administrator should use this list to match with the bank transactions and then confirm through this view that the payments have been made.

Note: the club can set their own minimum_balance_after_settlement amount to maintain a float in their account. This is so they can still make outgoing payments before further incoming payments come in.

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse

payments.views.core module

Handles all activities associated with payments that do not talk to users.

This module handles all of the functions that do not interact directly with a user. i.e. they do not generally accept a Request and return an HttpResponse. Arguably these could have been put directly into models.py but it seems cleaner to store them here.

See also Payments Views. This handles the user side of the interactions. They both work together.

Key Points:

• Payments is a service module, it is requested to do things on behalf of another module and does not know why it is doing them.

• Payments are often not real time, for manual payments, the user will be taken to another screen that interacts directly with Stripe, and for automatic top up payments, the top up may fail and require user input.

• The asynchronous nature of payments makes it more complex than many of the Cobalt modules so the documentation needs to be of a higher standard. See Payments Overview for more details.

payments.views.core.auto_topup_member(member, topup_required=None, payment_type='Auto Top Up')

process an auto top up for a member.

Internal function to handle a member needing to process an auto top up. This function deals with successful top ups and failed top ups. For failed top ups it will notify the user and disable auto topups. It is the calling functions problem to handle the consequences of the non-payment.

Parameters:

• object. (member - a User)

• up (topup_required - the amount of the top) – is larger than the top up amount. e.g. balance is 25, top up amount is 50, payment is 300.

• member (payment_type - defaults to Auto Top Up. We allow this to be overridden so that a) – manually topping up their account using their registered auto top up card get the payment type of Manual Top Up on their statement.

Returns:

return_code - True for success, False for failure message - explanation

payments.views.core.callback_router(route_code, route_payload, stripe_transaction=None, status='Success')

Central function to handle callbacks

Callbacks are an asynchronous way for us to let the calling application know if a payment succeeded or not.

We could use a routing table for this but there will only ever be a small number of callbacks in Cobalt so we are okay to hardcode it.

Parameters:

• route_code – (str) hard coded value to map to a function call

• route_payload (str)

• stripe_transaction – StripeTransaction. Optional. Sometimes (e.g. member transfer) we want to get the data from the Stripe transaction rather than the payload.

• status – Success (default) or Failure. Did the payment work or not.

Returns:

Nothing

payments.views.core.get_balance(member)

Gets member account balance

This function returns the current balance of the member’s account.

Parameters:

member (User) – A User object

Returns:

The member’s current balance

Return type:

float

payments.views.core.get_balance_and_recent_trans_org(org)

Gets organisation account balance and most recent transactions

This function returns the current balance of the organisation’s account and the most recent transactions.

Parameters:

org (organisations.models.Organisation) – An Organisation object

Returns:

The member’s current balance list: the most recent transactions

Return type:

float

payments.views.core.get_balance_detail(member)

Called by dashboard to show basic information

Parameters:

member – A User object - the member whose balance is required

Returns:

Keys - balance and last_top_up

Return type:

dict

payments.views.core.get_payments_statistics()

Get statistics about payments. Called by utils statistics

payments.views.core.get_user_pending_payments(system_number)

Get any IOUs for this user. Called by the dashboard

payments.views.core.low_balance_warning(member: User)

Handle a user without auto top up enabled, falling below the low balance threshold

payments.views.core.member_to_member_transfer_callback(stripe_transaction=None)

Callback for member to member transfers. We have already made the payments, so just let people know.

We will get a stripe_transaction from the manual payment screen (callback from stripe webhook). If we don’t get one that is because this was handled already so ignore.

Three scenarios (doesn’t matter if manual or auto top up):

1. The user had enough funds to pay the other member - emails already sent, stripe_tran = None

2. The user paid the full amount on their credit card - stripe amount = transfer amount

3. The user had some funds and paid the rest on their credit card - stripe amt + previous bal = transfer amount

payments.views.core.org_balance(organisation)

Returns org balance

Parameters:

organisation (organisations.models.Organisation) – Organisation object

Returns:

balance

Return type:

float

payments.views.core.org_balance_at_date(organisation, as_at_date)

Returns org balance as at a specified date

Parameters:

• organisation (organisations.models.Organisation) – Organisation object

• as_at_date – date

Returns:

balance

Return type:

float

payments.views.core.payments_status_summary()

Called by utils to show a management summary of how payments is working.

Parameters:

None

Returns:

various indicators in a dictionary

Return type:

dict

payments.views.core.statement_common(user)

Member statement view - common part across online, pdf and csv

Handles the non-formatting parts of statements.

Parameters:

user (User) – standard user object

Returns:

5-element tuple containing

• summary (dict): Basic info about user from MasterPoints

• club (str): Home club name

• balance (float or str): Users account balance

• auto_button (bool): status of auto top up

• events_list (list): list of MemberTransactions

payments.views.core.stripe_auto_payment_intent(request)

Called from the auto top up webpage.

This is very similar to the one off payment. It lets Stripe know to expect a credit card and provides a token to confirm which one it is.

When a user is going to set up a credit card we tell Stripe and Stripe gets ready for it. By this point in the process we have handed over control to the Stripe code which calls this function over Ajax.

This functions expects a json payload as part of request.

Parameters:

payload. (request - This needs to contain a Json)

Notes

The Json should include: data{“stripe_customer_id”: This is the Stripe customer_id in our table for the customer that we are handling}

Returns:

{‘publishableKey’:? ‘clientSecret’:?}

Return type:

json

Notes

publishableKey = our Public Stripe key, clientSecret = client secret from Stripe

payments.views.core.stripe_current_balance()

Get our (ABF) current balance with Stripe

payments.views.core.stripe_manual_payment_intent(request)

Called from the checkout webpage.

When a user is going to pay with a credit card we tell Stripe and Stripe gets ready for it. By this point in the process we have handed over control to the Stripe code which calls this function over Ajax.

This functions expects a json payload as part of request.

Parameters:

payload. (request - This needs to contain a Json)

Notes

The Json should include: data{“id”: This is the StripeTransaction in our table that we are handling “amount”: The amount in the system currency}

Returns:

{‘publishableKey’:? ‘clientSecret’:?}

Return type:

json

Notes

publishableKey = our Public Stripe key, clientSecret = client secret from Stripe

payments.views.core.stripe_webhook(request)

Callback from Stripe webhook

In development, Stripe sends us everything. In production we can configure the events that we receive. This is the only way for Stripe to communicate with us.

Note

Stripe sends us multiple similar things, for example payment.intent.succeeded will accompany anything that uses a payment intent. Be careful to only handle one out of the multiple events.

For manual payments we can receive:

• payment.intent.created - ignore

• charge.succeeded - process

• payment.intent.succeeded - ignore

For automatic payment set up, we get:

• customer.created - ignore

• setup_intent.created - ignore

• payment_method.attached - process

• setup_intent.succeeded - ignore

For automatic payments we get:

• payment_intent.succeeded - ignore

• payment_intent.created - ignore

• charge_succeeded - ignore (we already know this from the API call)

Meta data

We use meta data to track what the event related to. This is added by us when we call Stripe and returned to us by Stripe in the callback.

Fields used:

• cobalt_tran_type - either Manual or Auto for manual and auto top up transactions. If this is missing then the transaction is invalid.

• cobalt_pay_id - for manual payments this is the linked transaction in MemberTransaction.

Parameters:

documentation (Stripe json payload - see Stripe)

Returns:

HTTPStatus Code

payments.views.core.stripe_webhook_autosetup(event)

Handles auto top up setup events from Stripe webhook

Called by stripe_webhook to look after successful incoming auto top up set ups.

Parameters:

Stripe (event - the event payload from)

Returns:

HTTPResponse code - 200 for success, 400 for error

payments.views.core.stripe_webhook_manual(event)

Handles manual payment events from Stripe webhook

Called by stripe_webhook to look after incoming manual payments.

Parameters:

Stripe (event - the event payload from)

Returns:

HTTPResponse code - 200 for success, 400 for error

payments.views.core.update_account(member, amount, description, payment_type, stripe_transaction=None, other_member=None, organisation=None, session=None)

Function to update a customer account by adding a transaction.

Parameters:

• member (User) – owner of the account

• amount (float) – value (plus is a deduction, minus is a credit)

• description (str) – to appear on statement

• payment_type (str) – type of payment

• stripe_transaction (StripeTransaction, optional) – linked Stripe transaction

• other_member (User, optional) – linked member

• organisation (organisations.models.Organisation, optional) – linked organisation

• session (club_sessions.models.Session, optional) – club_session.session linked to this transaction

Returns:

MemberTransaction

payments.views.core.update_organisation(organisation, amount, description, payment_type, other_organisation=None, member=None, bank_settlement_amount=None, session=None, event=None)

method to update an organisations account

Parameters:

• organisation (organisations.models.Organisation) – organisation to update

• amount (float) – value (plus is a deduction, minus is a credit)

• description (str) – to appear on statement

• payment_type (str) – type of payment

• member (User, optional) – linked member

• other_organisation (organisations.model.Organisation, optional) – linked organisation

• bank_settlement_amount (float) – How much we expect to be settled. Used for ABF deducting fees for card payments

• session (club_sessions.models.Session, optional) – club_session.session linked to this transaction

payments.views.orgs module

payments.views.orgs.get_org_fees(request, org_id)

Get the ABF fees associated with this organisation

payments.views.orgs.member_transfer_org(request, org_id)

Allows an organisation to transfer money to a member

Parameters:

• request (HTTPRequest) – standard request object

• org_id (int) – organisation doing the transfer

Returns:

HTTPResponse

payments.views.orgs.statement_csv_org(request, org_id)

Organisation statement CSV.

Parameters:

• request – standard request object

• org_id – organisation to view

Returns:

CSV

Return type:

HTTPResponse

payments.views.orgs.statement_org(request, org_id)

Organisation statement view.

Basic view of statement showing transactions in a web page.

Parameters:

• request – standard request object

• org_id – organisation to view

Returns:

HTTPResponse

payments.views.orgs.statement_org_summary_ajax(request, org_id, range)

Called by the org statement when the summary date range changes

Parameters:

• request (HTTPRequest) – standard request object

• org_id (int) – pk of the org to query

• range (str) – range to include in summary

Returns:

data for table

Return type:

HTTPResponse

payments.views.payments_api module

payments.views.payments_api.calculate_auto_topup_amount(member, amount, balance)

calculate required top up amount Generally top by the largest of amount and auto_amount, BUT if the balance after that will be low enough to require another top up then we top up by increments of the top up amount.

payments.views.payments_api.notify_member_to_member_transfer(member, other_member, amount, description)

For member to member transfers we email both members to confirm

payments.views.payments_api.payment_api_batch(member, description, amount, organisation=None, other_member=None, payment_type=None, book_internals=True, session=None, event=None)

This API is used by other parts of the system to make payments or fail. It will use existing funds or try to initiate an auto top up. Use payment_api_interactive() if you wish the user to be taken to the manual payment screen.

We accept either an organisation as the counterpart for this payment or other_member. If the calling function wishes to book their own transactions they can pass us neither parameter.

For Events, the booking of the internal transactions is done in the callback so that we can have individual transactions that are easier to map. The optional parameter book_internals handles this. If this is set to false then only the necessary Stripe transactions are executed by payment_api.

Parameters:

• payment (payment_type - description of)

• charge (amount - A positive amount is a)

• payment. (a negative amount is an incoming)

• payment

• organisation (organisation - linked)

• object (other_member - User)

• payment

• deals (book_internals - sometimes the calling module wants to book the internal) – for example, event entry may be booking a whole team of entries as part of this so we only want the stripe transaction to go through and the call back will book all of the individual deals. Default is to have us book the internals too.

• session (club_sessions.models.Session) – optional club_session.session to link payment to

• event (event.models.Event) – optional event to link payment to

Returns:

bool - success or failure

payments.views.payments_api.payment_api_interactive(request, member, description, amount, organisation=None, other_member=None, payment_type='Miscellaneous', next_url=None, route_code=None, route_payload=None, book_internals=True, session=None)

Payments API when we have an attached user. This will try to make a payment and if need be take the user to the Stripe payment screen to handle a manual payment.

For auto top up users, or users with enough money, this is a synchronous process and we will return the next_url to the user.

For manual payments, the Stripe process is asynchronous. We hand the user off to Stripe and only know if their payment worked when Stripe calls us back through the webhook. We use a route_code to know what function to call when the webhook is triggered and the route_payload is passed so the calling module knows what this refers to.

Parameters:

• request (HttpRequest) – Standard request object

• description (str) – text description of the payment

• amount (float) – A positive amount is a charge, a negative amount is an incoming payment.

• member (User) – User object related to the payment

• organisation (organisations.models.Organisation) – linked organisation

• other_member (User) – User object

• payment_type (str) – description of payment

• next_url (str) – where to take the user next

• route_code (str) – used by the callback to know which function to call upon the payment going through

• route_payload (str) – identifier to pass when making the callback

• book_internals (bool) – sometimes the calling module wants to book the internal deals (not Stripe) themselves for example, event entry may be booking a whole team of entries as part of this so we only want the stripe transaction to go through and the call back will book all of the individual deals. Default is to have us book the internals too.

• session (club_sessions.models.Session) – optional club_session.session to link payment to

Returns:

HttpResponse - either the Stripe manual payment screen or the next_url

payments.views.players module

payments.views.players.cancel_auto_top_up(request)

Cancel auto top up.

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse

payments.views.players.manual_topup(request)

Page to allow credit card top up regardless of auto status.

This page allows a member to add to their account using a credit card, they can do this even if they have already set up for auto top up.

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse

payments.views.players.member_transfer(request)

view to transfer $ to another member

This view allows a member to transfer money to another member.

Parameters:

request (HTTPRequest) – standard request object

Returns:

HTTPResponse

payments.views.players.pay_user_pending_payment(request, user_pending_payment_id)

Pay for an IOU to a club

payments.views.players.refund_stripe_transaction(request, stripe_transaction_id)

Allows a user to refund a Stripe transaction

Parameters:

• stripe_transaction_id

• request (HTTPRequest) – standard request object

Returns:

HTTPResponse

payments.views.players.setup_autotopup(request)

view to sign up to auto top up.

Creates Stripe customer if not already defined. Hands over to Stripe to process card.

Parameters:

request (HTTPRequest) – standard request object

Returns:

Our page with Stripe code embedded.

Return type:

HTTPResponse

payments.views.players.statement(request)

Member statement view.

Basic view of statement showing transactions in a web page.

Parameters:

object (request - standard request)

Returns:

HTTPResponse

payments.views.players.statement_csv(request, member_id=None)

Member statement view - csv download

Generates a CSV of the statement.

Parameters:

• request (HTTPRequest) – standard request object

• member_id (int) – id of member to view, defaults to logged in user

Returns:

CSV headed response with CSV statement data

Return type:

HTTPResponse

payments.views.players.statement_pdf(request)

Member statement view - csv download

Generates a PDF of the statement.

Parameters:

request (HTTPRequest) – standard request object

Returns:

PDF headed response with PDF statement data

Return type:

HTTPResponse

payments.views.players.stripe_autotopup_confirm(request)

User has been told by Stripe that auto top up went through.

This is called by the web page after Stripe confirms that auto top up is approved. Because this originates from the client we do not trust it, but we do move the status to Pending unless it is already Confirmed (timing issues).

For manual payments we update the transaction, but for auto top up there is no transaction so we record this on the User object.

Parameters:

request (HTTPRequest) – standard request object

Returns:

Nothing.

payments.views.players.stripe_autotopup_off(request)

Switch off auto top up

This is called by the web page when a user submits new card details to Stripe. This is the latest point that we can turn it off in case the user aborts the change.

Parameters:

request (HTTPRequest) – stasndard request object

Returns:

Nothing.

payments.views.players.stripe_create_customer(request)

calls Stripe to register a customer.

Creates a new customer entry with Stripe and sets this member’s stripe_customer_id to match the customer created. Also sets the auto_amount for the member to the system default.

Parameters:

request (HTTPRequest) – standard request object

Returns:

Nothing.

payments.views.players.stripe_webpage_confirm(request, stripe_id)

User has been told by Stripe that transaction went through.

This is called by the web page after Stripe confirms the transaction is approved. Because this originates from the client we do not trust it, but we do move the status to Pending unless it is already Confirmed (timing issues).

Parameters:

• request (HTTPRequest) – stasndard request object

• stripe_id (int) – pk of stripe transaction

Returns:

Nothing.

payments.views.players.update_auto_amount(request)

Called by the auto top up page when a user changes the amount of the auto top up.

The auto top up page has Stripe code on it so a standard form won’t work for this. Instead we use a little Ajax code on the page to handle this.

Parameters:

request (HTTPRequest) – standard request object

Returns:

“Successful”

Return type:

HTTPResponse

payments.views.players.user_pending_payment_callback(status, user_pending_payment_id)

Callback for a user_pending_payment being made

Module contents