django_program.sponsors.services

Bulk purchase service for sponsor voucher checkout flows.

Orchestrates the lifecycle of a sponsor’s bulk voucher purchase: creating the purchase record, initiating a Stripe Checkout Session, fulfilling the order with generated voucher codes after payment, and handling the webhook callback.

Classes

BulkPurchaseService

Stateless service for sponsor bulk voucher purchase operations.

Exceptions

BulkPurchaseError

Raised when a bulk purchase operation fails.

exception django_program.sponsors.services.BulkPurchaseError

Bases: Exception

Raised when a bulk purchase operation fails.

class django_program.sponsors.services.BulkPurchaseService

Bases: object

Stateless service for sponsor bulk voucher purchase operations.

Manages the full purchase lifecycle from creation through Stripe Checkout to voucher code generation upon successful payment.

static create_checkout_session(bulk_purchase, success_url, cancel_url)

Create a Stripe Checkout Session for the bulk purchase total.

Uses the conference’s Stripe credentials to create a Checkout Session in payment mode. Stores the session ID on the BulkPurchase record and transitions the status to PROCESSING.

Parameters:

• bulk_purchase (BulkPurchase) – The bulk purchase to create a session for.

• success_url (str) – URL Stripe redirects to after successful payment.

• cancel_url (str) – URL Stripe redirects to if the user cancels.

Return type:

str

Returns:

The Stripe Checkout Session URL for redirecting the user.

Raises:

• BulkPurchaseError – If the purchase is not in PENDING state or has a zero total.

• ValueError – If the conference has no Stripe secret key.

static fulfill_bulk_purchase(bulk_purchase)

Generate voucher codes for a paid bulk purchase.

Idempotent: returns an empty list if the purchase is already fulfilled (status is PAID and vouchers have been generated). Generates codes using the voucher service’s generate_voucher_codes() and creates BulkPurchaseVoucher links.

Parameters:

bulk_purchase (BulkPurchase) – The bulk purchase to fulfill.

Return type:

list[Voucher]

Returns:

List of newly created Voucher instances, or an empty list if already fulfilled.

Raises:

BulkPurchaseError – If the purchase is in a state that cannot be fulfilled (e.g. PENDING, FAILED, REFUNDED).

static handle_checkout_webhook(session_id)

Handle a Stripe checkout.session.completed event for bulk purchases.

Looks up the BulkPurchase by its stored checkout session ID, extracts the payment intent ID from the session data, and fulfills the purchase by generating voucher codes.

Parameters:

session_id (str) – The Stripe Checkout Session ID from the webhook event.

Return type:

BulkPurchase | None

Returns:

The fulfilled BulkPurchase, or None if no matching purchase was found (the event may belong to a regular registration checkout).

static refund_bulk_purchase(bulk_purchase)

Mark a bulk purchase as REFUNDED and deactivate all linked vouchers.

Called when a charge.refunded webhook identifies a payment intent belonging to a bulk purchase. Transitions the purchase to REFUNDED and sets is_active=False on every voucher generated for it.

Parameters:

bulk_purchase (BulkPurchase) – The bulk purchase to refund.

Return type:

None

static mark_failed(bulk_purchase)

Transition a bulk purchase to FAILED state.

Used when a checkout session expires or the payment is declined. Only transitions from PENDING or PROCESSING to avoid overwriting a purchase that has already been fulfilled (PAID) or refunded.

Parameters:

bulk_purchase (BulkPurchase) – The bulk purchase to mark as failed.

Return type:

None