Models

Models hold the bulk of the functionality included in the dj-stripe package. Each model is tied closely to its corresponding object in the stripe dashboard. Fields that are not implemented for each model have a short reason behind the decision in the docstring for each model.

Core Resources

Attributes

djstripe.models.core.FileUpload = File module-attribute

Classes

djstripe.models.core.BalanceTransaction

Bases: StripeModel

A single transaction that updates the Stripe balance.

Stripe documentation: https://stripe.com/docs/api?lang=python#balance_transaction_object

Source code in djstripe/models/core.py

class BalanceTransaction(StripeModel):
    """
    A single transaction that updates the Stripe balance.

    Stripe documentation: https://stripe.com/docs/api?lang=python#balance_transaction_object
    """

    stripe_class = stripe.BalanceTransaction

    amount = StripeQuantumCurrencyAmountField(
        help_text="Gross amount of the transaction, in cents."
    )
    available_on = StripeDateTimeField(
        help_text=(
            "The date the transaction's net funds "
            "will become available in the Stripe balance."
        )
    )
    currency = StripeCurrencyCodeField()
    exchange_rate = models.DecimalField(null=True, decimal_places=6, max_digits=8)
    fee = StripeQuantumCurrencyAmountField(
        help_text="Fee (in cents) paid for this transaction."
    )
    fee_details = JSONField()
    net = StripeQuantumCurrencyAmountField(
        help_text="Net amount of the transaction, in cents."
    )
    source = StripeIdField()
    reporting_category = StripeEnumField(
        enum=enums.BalanceTransactionReportingCategory,
        help_text=(
            "More information: https://stripe.com/docs/reports/reporting-categories"
        ),
    )
    status = StripeEnumField(enum=enums.BalanceTransactionStatus)
    type = StripeEnumField(enum=enums.BalanceTransactionType)

    def __str__(self):
        amount = get_friendly_currency_amount(self.amount / 100, self.currency)
        status = enums.BalanceTransactionStatus.humanize(self.status)
        return f"{amount} ({status})"

    def get_source_class(self):
        try:
            return apps.get_model("djstripe", self.type)
        except LookupError:
            raise

    def get_source_instance(self):
        return self.get_source_class().objects.get(id=self.source)

    def get_stripe_dashboard_url(self):
        return self.get_source_instance().get_stripe_dashboard_url()

Attributes

djstripe.models.core.BalanceTransaction.amount = StripeQuantumCurrencyAmountField(help_text='Gross amount of the transaction, in cents.') class-attribute instance-attribute

djstripe.models.core.BalanceTransaction.available_on = StripeDateTimeField(help_text="The date the transaction's net funds will become available in the Stripe balance.") class-attribute instance-attribute

djstripe.models.core.BalanceTransaction.currency = StripeCurrencyCodeField() class-attribute instance-attribute

djstripe.models.core.BalanceTransaction.exchange_rate = models.DecimalField(null=True, decimal_places=6, max_digits=8) class-attribute instance-attribute

djstripe.models.core.BalanceTransaction.fee = StripeQuantumCurrencyAmountField(help_text='Fee (in cents) paid for this transaction.') class-attribute instance-attribute

djstripe.models.core.BalanceTransaction.fee_details = JSONField() class-attribute instance-attribute

djstripe.models.core.BalanceTransaction.net = StripeQuantumCurrencyAmountField(help_text='Net amount of the transaction, in cents.') class-attribute instance-attribute

djstripe.models.core.BalanceTransaction.reporting_category = StripeEnumField(enum=enums.BalanceTransactionReportingCategory, help_text='More information: https://stripe.com/docs/reports/reporting-categories') class-attribute instance-attribute

djstripe.models.core.BalanceTransaction.source = StripeIdField() class-attribute instance-attribute

djstripe.models.core.BalanceTransaction.status = StripeEnumField(enum=enums.BalanceTransactionStatus) class-attribute instance-attribute

djstripe.models.core.BalanceTransaction.stripe_class = stripe.BalanceTransaction class-attribute instance-attribute

djstripe.models.core.BalanceTransaction.type = StripeEnumField(enum=enums.BalanceTransactionType) class-attribute instance-attribute

Functions

djstripe.models.core.BalanceTransaction.__str__()

Source code in djstripe/models/core.py

def __str__(self):
    amount = get_friendly_currency_amount(self.amount / 100, self.currency)
    status = enums.BalanceTransactionStatus.humanize(self.status)
    return f"{amount} ({status})"

djstripe.models.core.BalanceTransaction.get_source_class()

Source code in djstripe/models/core.py

def get_source_class(self):
    try:
        return apps.get_model("djstripe", self.type)
    except LookupError:
        raise

djstripe.models.core.BalanceTransaction.get_source_instance()

Source code in djstripe/models/core.py

def get_source_instance(self):
    return self.get_source_class().objects.get(id=self.source)

djstripe.models.core.BalanceTransaction.get_stripe_dashboard_url()

Source code in djstripe/models/core.py

def get_stripe_dashboard_url(self):
    return self.get_source_instance().get_stripe_dashboard_url()

djstripe.models.core.Charge

Bases: StripeModel

To charge a credit or a debit card, you create a charge object. You can retrieve and refund individual charges as well as list all charges. Charges are identified by a unique random ID.

Stripe documentation: https://stripe.com/docs/api?lang=python#charges

Source code in djstripe/models/core.py

class Charge(StripeModel):
    """
    To charge a credit or a debit card, you create a charge object. You can
    retrieve and refund individual charges as well as list all charges. Charges
    are identified by a unique random ID.

    Stripe documentation: https://stripe.com/docs/api?lang=python#charges
    """

    stripe_class = stripe.Charge
    expand_fields = ["balance_transaction"]
    stripe_dashboard_item_name = "payments"

    amount = StripeDecimalCurrencyAmountField(help_text="Amount charged (as decimal).")
    amount_captured = StripeDecimalCurrencyAmountField(
        null=True,
        help_text=(
            "Amount (as decimal) captured (can be less than the amount attribute "
            "on the charge if a partial capture was issued)."
        ),
    )
    amount_refunded = StripeDecimalCurrencyAmountField(
        help_text=(
            "Amount (as decimal) refunded (can be less than the amount attribute on "
            "the charge if a partial refund was issued)."
        )
    )
    application = models.CharField(
        max_length=255,
        blank=True,
        help_text="ID of the Connect application that created the charge.",
    )
    application_fee = StripeForeignKey(
        "ApplicationFee",
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="fee_for_charge",
        help_text="The application fee (if any) for the charge.",
    )
    application_fee_amount = StripeDecimalCurrencyAmountField(
        null=True,
        blank=True,
        help_text=(
            "The amount (as decimal) of the application fee (if any) "
            "requested for the charge."
        ),
    )
    balance_transaction = StripeForeignKey(
        "BalanceTransaction",
        on_delete=models.SET_NULL,
        null=True,
        help_text=(
            "The balance transaction that describes the impact of this charge "
            "on your account balance (not including refunds or disputes)."
        ),
    )
    billing_details = JSONField(
        null=True,
        help_text=(
            "Billing information associated with the PaymentMethod at the "
            "time of the transaction."
        ),
    )
    calculated_statement_descriptor = models.CharField(
        max_length=22,
        default="",
        help_text=(
            "The full statement descriptor that is passed to card networks, "
            "and that is displayed on your customers' credit card and bank statements. "
            "Allows you to see what the statement descriptor looks like after the "
            "static and dynamic portions are combined."
        ),
    )
    captured = models.BooleanField(
        default=False,
        help_text=(
            "If the charge was created without capturing, this boolean represents"
            " whether or not it is still uncaptured or has since been captured."
        ),
    )
    currency = StripeCurrencyCodeField(
        help_text="The currency in which the charge was made."
    )
    customer = StripeForeignKey(
        "Customer",
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="charges",
        help_text="The customer associated with this charge.",
    )

    dispute = StripeForeignKey(
        "Dispute",
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="charges",
        help_text="Details about the dispute if the charge has been disputed.",
    )
    disputed = models.BooleanField(
        default=False,
        help_text="Whether the charge has been disputed.",
    )
    failure_code = StripeEnumField(
        enum=enums.ApiErrorCode,
        default="",
        blank=True,
        help_text="Error code explaining reason for charge failure if available.",
    )
    failure_message = models.TextField(
        max_length=5000,
        default="",
        blank=True,
        help_text=(
            "Message to user further explaining reason for charge failure if available."
        ),
    )
    fraud_details = JSONField(
        help_text="Hash with information on fraud assessments for the charge.",
        null=True,
        blank=True,
    )
    invoice = StripeForeignKey(
        "Invoice",
        on_delete=models.CASCADE,
        null=True,
        related_name="charges",
        help_text="The invoice this charge is for if one exists.",
    )
    # TODO: order (requires Order model)
    on_behalf_of = StripeForeignKey(
        "Account",
        on_delete=models.CASCADE,
        null=True,
        blank=True,
        related_name="charges",
        help_text=(
            "The account (if any) the charge was made on behalf of "
            "without triggering an automatic transfer."
        ),
    )
    outcome = JSONField(
        help_text="Details about whether or not the payment was accepted, and why.",
        null=True,
        blank=True,
    )
    paid = models.BooleanField(
        default=False,
        help_text=(
            "True if the charge succeeded, "
            "or was successfully authorized for later capture, False otherwise."
        ),
    )
    payment_intent = StripeForeignKey(
        "PaymentIntent",
        null=True,
        on_delete=models.SET_NULL,
        related_name="charges",
        help_text="PaymentIntent associated with this charge, if one exists.",
    )
    payment_method = StripeForeignKey(
        "PaymentMethod",
        null=True,
        on_delete=models.SET_NULL,
        related_name="charges",
        help_text="PaymentMethod used in this charge.",
    )
    payment_method_details = JSONField(
        help_text="Details about the payment method at the time of the transaction.",
        null=True,
        blank=True,
    )
    receipt_email = models.TextField(
        max_length=800,  # yup, 800.
        default="",
        blank=True,
        help_text="The email address that the receipt for this charge was sent to.",
    )
    receipt_number = models.CharField(
        max_length=14,
        default="",
        blank=True,
        help_text=(
            "The transaction number that appears "
            "on email receipts sent for this charge."
        ),
    )
    receipt_url = models.TextField(
        max_length=5000,
        default="",
        blank=True,
        help_text=(
            "This is the URL to view the receipt for this charge. "
            "The receipt is kept up-to-date to the latest state of the charge, "
            "including any refunds. If the charge is for an Invoice, "
            "the receipt will be stylized as an Invoice receipt."
        ),
    )
    refunded = models.BooleanField(
        default=False,
        help_text=(
            "Whether or not the charge has been fully refunded. "
            "If the charge is only partially refunded, "
            "this attribute will still be false."
        ),
    )
    # TODO: review (requires Review model)
    shipping = JSONField(
        null=True, blank=True, help_text="Shipping information for the charge"
    )
    source = PaymentMethodForeignKey(
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="charges",
        help_text="The source used for this charge.",
    )
    source_transfer = StripeForeignKey(
        "Transfer",
        null=True,
        blank=True,
        on_delete=models.CASCADE,
        help_text=(
            "The transfer which created this charge. Only present if the "
            "charge came from another Stripe account."
        ),
        related_name="+",
    )
    statement_descriptor = models.CharField(
        max_length=22,
        null=True,
        blank=True,
        help_text=(
            "For card charges, use statement_descriptor_suffix instead. "
            "Otherwise, you can use this value as the complete description of a "
            "charge on your customers' statements. Must contain at least one letter, "
            "maximum 22 characters."
        ),
    )
    statement_descriptor_suffix = models.CharField(
        max_length=22,
        null=True,
        blank=True,
        help_text=(
            "Provides information about the charge that customers see on "
            "their statements. Concatenated with the prefix (shortened descriptor) "
            "or statement descriptor that's set on the account to form the "
            "complete statement descriptor. "
            "Maximum 22 characters for the concatenated descriptor."
        ),
    )
    status = StripeEnumField(
        enum=enums.ChargeStatus, help_text="The status of the payment."
    )
    transfer = StripeForeignKey(
        "Transfer",
        on_delete=models.CASCADE,
        null=True,
        blank=True,
        help_text=(
            "The transfer to the `destination` account (only applicable if "
            "the charge was created using the `destination` parameter)."
        ),
    )
    transfer_data = JSONField(
        null=True,
        blank=True,
        help_text=(
            "An optional dictionary including the account to automatically "
            "transfer to as part of a destination charge."
        ),
    )
    transfer_group = models.CharField(
        max_length=255,
        null=True,
        blank=True,
        help_text="A string that identifies this transaction as part of a group.",
    )

    objects = ChargeManager()

    def __str__(self):
        amount = get_friendly_currency_amount(self.amount, self.currency)
        return f"{amount} ({self.human_readable_status})"

    @property
    def fee(self):
        if self.balance_transaction:
            return self.balance_transaction.fee

    @property
    def human_readable_status(self) -> str:
        if not self.captured:
            return "Uncaptured"
        elif self.disputed:
            return "Disputed"
        elif self.refunded:
            return "Refunded"
        return enums.ChargeStatus.humanize(self.status)

    @property
    def fraudulent(self) -> bool:
        return (
            self.fraud_details and list(self.fraud_details.values())[0] == "fraudulent"
        )

    def _calculate_refund_amount(self, amount: Optional[Decimal]) -> int:
        """
        Returns the amount that can be refunded (in cents)
        """
        eligible_to_refund = self.amount - (self.amount_refunded or 0)
        amount_to_refund = (
            min(eligible_to_refund, amount) if amount else eligible_to_refund
        )

        return int(amount_to_refund * 100)

    def refund(
        self,
        amount: Decimal = None,
        reason: str = None,
        api_key: str = None,
        stripe_account: str = None,
    ) -> "Refund":
        """
        Initiate a refund. Returns the refund object.

        :param amount: A positive decimal amount representing how much of this charge
            to refund. If amount is not provided, then this will be a full refund.
            Can only refund up to the unrefunded amount remaining of the charge.
        :param reason: String indicating the reason for the refund.
            If set, possible values are ``duplicate``, ``fraudulent``,
            and ``requested_by_customer``. Specifying ``fraudulent`` as the reason
            when you believe the charge to be fraudulent will
            help Stripe improve their fraud detection algorithms.
        """
        api_key = api_key or self.default_api_key

        # Prefer passed in stripe_account if set.
        if not stripe_account:
            stripe_account = self._get_stripe_account_id(api_key)

        refund_obj = Refund._api_create(
            charge=self.id,
            amount=self._calculate_refund_amount(amount=amount),
            reason=reason,
            api_key=api_key,
            stripe_account=stripe_account,
        )

        return Refund.sync_from_stripe_data(
            refund_obj,
            api_key=api_key,
            stripe_version=djstripe_settings.STRIPE_API_VERSION,
        )

    def capture(self, **kwargs) -> "Charge":
        """
        Capture the payment of an existing, uncaptured, charge.
        This is the second half of the two-step payment flow, where first you
        created a charge with the capture option set to False.

        See https://stripe.com/docs/api#capture_charge
        """

        captured_charge = self.api_retrieve().capture(**kwargs)
        return self.__class__.sync_from_stripe_data(
            captured_charge, api_key=self.default_api_key
        )

    def _attach_objects_post_save_hook(
        self,
        cls,
        data,
        pending_relations=None,
        api_key=djstripe_settings.STRIPE_SECRET_KEY,
    ):
        super()._attach_objects_post_save_hook(
            cls, data, pending_relations=pending_relations, api_key=api_key
        )

        cls._stripe_object_to_refunds(
            target_cls=Refund, data=data, charge=self, api_key=api_key
        )

Attributes

djstripe.models.core.Charge.amount = StripeDecimalCurrencyAmountField(help_text='Amount charged (as decimal).') class-attribute instance-attribute

djstripe.models.core.Charge.amount_captured = StripeDecimalCurrencyAmountField(null=True, help_text='Amount (as decimal) captured (can be less than the amount attribute on the charge if a partial capture was issued).') class-attribute instance-attribute

djstripe.models.core.Charge.amount_refunded = StripeDecimalCurrencyAmountField(help_text='Amount (as decimal) refunded (can be less than the amount attribute on the charge if a partial refund was issued).') class-attribute instance-attribute

djstripe.models.core.Charge.application = models.CharField(max_length=255, blank=True, help_text='ID of the Connect application that created the charge.') class-attribute instance-attribute

djstripe.models.core.Charge.application_fee = StripeForeignKey('ApplicationFee', on_delete=models.SET_NULL, null=True, blank=True, related_name='fee_for_charge', help_text='The application fee (if any) for the charge.') class-attribute instance-attribute

djstripe.models.core.Charge.application_fee_amount = StripeDecimalCurrencyAmountField(null=True, blank=True, help_text='The amount (as decimal) of the application fee (if any) requested for the charge.') class-attribute instance-attribute

djstripe.models.core.Charge.balance_transaction = StripeForeignKey('BalanceTransaction', on_delete=models.SET_NULL, null=True, help_text='The balance transaction that describes the impact of this charge on your account balance (not including refunds or disputes).') class-attribute instance-attribute

djstripe.models.core.Charge.billing_details = JSONField(null=True, help_text='Billing information associated with the PaymentMethod at the time of the transaction.') class-attribute instance-attribute

djstripe.models.core.Charge.calculated_statement_descriptor = models.CharField(max_length=22, default='', help_text="The full statement descriptor that is passed to card networks, and that is displayed on your customers' credit card and bank statements. Allows you to see what the statement descriptor looks like after the static and dynamic portions are combined.") class-attribute instance-attribute

djstripe.models.core.Charge.captured = models.BooleanField(default=False, help_text='If the charge was created without capturing, this boolean represents whether or not it is still uncaptured or has since been captured.') class-attribute instance-attribute

djstripe.models.core.Charge.currency = StripeCurrencyCodeField(help_text='The currency in which the charge was made.') class-attribute instance-attribute

djstripe.models.core.Charge.customer = StripeForeignKey('Customer', on_delete=models.SET_NULL, null=True, blank=True, related_name='charges', help_text='The customer associated with this charge.') class-attribute instance-attribute

djstripe.models.core.Charge.dispute = StripeForeignKey('Dispute', on_delete=models.SET_NULL, null=True, blank=True, related_name='charges', help_text='Details about the dispute if the charge has been disputed.') class-attribute instance-attribute

djstripe.models.core.Charge.disputed = models.BooleanField(default=False, help_text='Whether the charge has been disputed.') class-attribute instance-attribute

djstripe.models.core.Charge.expand_fields = ['balance_transaction'] class-attribute instance-attribute

djstripe.models.core.Charge.failure_code = StripeEnumField(enum=enums.ApiErrorCode, default='', blank=True, help_text='Error code explaining reason for charge failure if available.') class-attribute instance-attribute

djstripe.models.core.Charge.failure_message = models.TextField(max_length=5000, default='', blank=True, help_text='Message to user further explaining reason for charge failure if available.') class-attribute instance-attribute

djstripe.models.core.Charge.fee property

djstripe.models.core.Charge.fraud_details = JSONField(help_text='Hash with information on fraud assessments for the charge.', null=True, blank=True) class-attribute instance-attribute

djstripe.models.core.Charge.fraudulent: bool property

djstripe.models.core.Charge.human_readable_status: str property

djstripe.models.core.Charge.invoice = StripeForeignKey('Invoice', on_delete=models.CASCADE, null=True, related_name='charges', help_text='The invoice this charge is for if one exists.') class-attribute instance-attribute

djstripe.models.core.Charge.objects = ChargeManager() class-attribute instance-attribute

djstripe.models.core.Charge.on_behalf_of = StripeForeignKey('Account', on_delete=models.CASCADE, null=True, blank=True, related_name='charges', help_text='The account (if any) the charge was made on behalf of without triggering an automatic transfer.') class-attribute instance-attribute

djstripe.models.core.Charge.outcome = JSONField(help_text='Details about whether or not the payment was accepted, and why.', null=True, blank=True) class-attribute instance-attribute

djstripe.models.core.Charge.paid = models.BooleanField(default=False, help_text='True if the charge succeeded, or was successfully authorized for later capture, False otherwise.') class-attribute instance-attribute

djstripe.models.core.Charge.payment_intent = StripeForeignKey('PaymentIntent', null=True, on_delete=models.SET_NULL, related_name='charges', help_text='PaymentIntent associated with this charge, if one exists.') class-attribute instance-attribute

djstripe.models.core.Charge.payment_method = StripeForeignKey('PaymentMethod', null=True, on_delete=models.SET_NULL, related_name='charges', help_text='PaymentMethod used in this charge.') class-attribute instance-attribute

djstripe.models.core.Charge.payment_method_details = JSONField(help_text='Details about the payment method at the time of the transaction.', null=True, blank=True) class-attribute instance-attribute

djstripe.models.core.Charge.receipt_email = models.TextField(max_length=800, default='', blank=True, help_text='The email address that the receipt for this charge was sent to.') class-attribute instance-attribute

djstripe.models.core.Charge.receipt_number = models.CharField(max_length=14, default='', blank=True, help_text='The transaction number that appears on email receipts sent for this charge.') class-attribute instance-attribute

djstripe.models.core.Charge.receipt_url = models.TextField(max_length=5000, default='', blank=True, help_text='This is the URL to view the receipt for this charge. The receipt is kept up-to-date to the latest state of the charge, including any refunds. If the charge is for an Invoice, the receipt will be stylized as an Invoice receipt.') class-attribute instance-attribute

djstripe.models.core.Charge.refunded = models.BooleanField(default=False, help_text='Whether or not the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.') class-attribute instance-attribute

djstripe.models.core.Charge.shipping = JSONField(null=True, blank=True, help_text='Shipping information for the charge') class-attribute instance-attribute

djstripe.models.core.Charge.source = PaymentMethodForeignKey(on_delete=models.SET_NULL, null=True, blank=True, related_name='charges', help_text='The source used for this charge.') class-attribute instance-attribute

djstripe.models.core.Charge.source_transfer = StripeForeignKey('Transfer', null=True, blank=True, on_delete=models.CASCADE, help_text='The transfer which created this charge. Only present if the charge came from another Stripe account.', related_name='+') class-attribute instance-attribute

djstripe.models.core.Charge.statement_descriptor = models.CharField(max_length=22, null=True, blank=True, help_text="For card charges, use statement_descriptor_suffix instead. Otherwise, you can use this value as the complete description of a charge on your customers' statements. Must contain at least one letter, maximum 22 characters.") class-attribute instance-attribute

djstripe.models.core.Charge.statement_descriptor_suffix = models.CharField(max_length=22, null=True, blank=True, help_text="Provides information about the charge that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that's set on the account to form the complete statement descriptor. Maximum 22 characters for the concatenated descriptor.") class-attribute instance-attribute

djstripe.models.core.Charge.status = StripeEnumField(enum=enums.ChargeStatus, help_text='The status of the payment.') class-attribute instance-attribute

djstripe.models.core.Charge.stripe_class = stripe.Charge class-attribute instance-attribute

djstripe.models.core.Charge.stripe_dashboard_item_name = 'payments' class-attribute instance-attribute

djstripe.models.core.Charge.transfer = StripeForeignKey('Transfer', on_delete=models.CASCADE, null=True, blank=True, help_text='The transfer to the `destination` account (only applicable if the charge was created using the `destination` parameter).') class-attribute instance-attribute

djstripe.models.core.Charge.transfer_data = JSONField(null=True, blank=True, help_text='An optional dictionary including the account to automatically transfer to as part of a destination charge.') class-attribute instance-attribute

djstripe.models.core.Charge.transfer_group = models.CharField(max_length=255, null=True, blank=True, help_text='A string that identifies this transaction as part of a group.') class-attribute instance-attribute

Functions

djstripe.models.core.Charge.__str__()

Source code in djstripe/models/core.py

def __str__(self):
    amount = get_friendly_currency_amount(self.amount, self.currency)
    return f"{amount} ({self.human_readable_status})"

djstripe.models.core.Charge.capture(**kwargs)

Capture the payment of an existing, uncaptured, charge. This is the second half of the two-step payment flow, where first you created a charge with the capture option set to False.

See https://stripe.com/docs/api#capture_charge

Source code in djstripe/models/core.py

def capture(self, **kwargs) -> "Charge":
    """
    Capture the payment of an existing, uncaptured, charge.
    This is the second half of the two-step payment flow, where first you
    created a charge with the capture option set to False.

    See https://stripe.com/docs/api#capture_charge
    """

    captured_charge = self.api_retrieve().capture(**kwargs)
    return self.__class__.sync_from_stripe_data(
        captured_charge, api_key=self.default_api_key
    )

djstripe.models.core.Charge.refund(amount=None, reason=None, api_key=None, stripe_account=None)

Initiate a refund. Returns the refund object.

:param amount: A positive decimal amount representing how much of this charge to refund. If amount is not provided, then this will be a full refund. Can only refund up to the unrefunded amount remaining of the charge. :param reason: String indicating the reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer. Specifying fraudulent as the reason when you believe the charge to be fraudulent will help Stripe improve their fraud detection algorithms.

Source code in djstripe/models/core.py

def refund(
    self,
    amount: Decimal = None,
    reason: str = None,
    api_key: str = None,
    stripe_account: str = None,
) -> "Refund":
    """
    Initiate a refund. Returns the refund object.

    :param amount: A positive decimal amount representing how much of this charge
        to refund. If amount is not provided, then this will be a full refund.
        Can only refund up to the unrefunded amount remaining of the charge.
    :param reason: String indicating the reason for the refund.
        If set, possible values are ``duplicate``, ``fraudulent``,
        and ``requested_by_customer``. Specifying ``fraudulent`` as the reason
        when you believe the charge to be fraudulent will
        help Stripe improve their fraud detection algorithms.
    """
    api_key = api_key or self.default_api_key

    # Prefer passed in stripe_account if set.
    if not stripe_account:
        stripe_account = self._get_stripe_account_id(api_key)

    refund_obj = Refund._api_create(
        charge=self.id,
        amount=self._calculate_refund_amount(amount=amount),
        reason=reason,
        api_key=api_key,
        stripe_account=stripe_account,
    )

    return Refund.sync_from_stripe_data(
        refund_obj,
        api_key=api_key,
        stripe_version=djstripe_settings.STRIPE_API_VERSION,
    )

djstripe.models.core.Customer

Bases: StripeModel

Customer objects allow you to perform recurring charges and track multiple charges that are associated with the same customer.

Stripe documentation: https://stripe.com/docs/api?lang=python#customers

Source code in djstripe/models/core.py

class Customer(StripeModel):
    """
    Customer objects allow you to perform recurring charges and track multiple
    charges that are associated with the same customer.

    Stripe documentation: https://stripe.com/docs/api?lang=python#customers
    """

    stripe_class = stripe.Customer
    expand_fields = ["default_source", "sources"]
    stripe_dashboard_item_name = "customers"

    address = JSONField(null=True, blank=True, help_text="The customer's address.")
    balance = StripeQuantumCurrencyAmountField(
        null=True,
        blank=True,
        default=0,
        help_text=(
            "Current balance (in cents), if any, being stored on the customer's "
            "account. "
            "If negative, the customer has credit to apply to the next invoice. "
            "If positive, the customer has an amount owed that will be added to the "
            "next invoice. The balance does not refer to any unpaid invoices; it "
            "solely takes into account amounts that have yet to be successfully "
            "applied to any invoice. This balance is only taken into account for "
            "recurring billing purposes (i.e., subscriptions, invoices, invoice items)."
        ),
    )
    currency = StripeCurrencyCodeField(
        blank=True,
        default="",
        help_text=(
            "The currency the customer can be charged in for recurring billing purposes"
        ),
    )
    default_source = PaymentMethodForeignKey(
        on_delete=models.SET_NULL, null=True, blank=True, related_name="customers"
    )
    delinquent = models.BooleanField(
        null=True,
        blank=True,
        default=False,
        help_text=(
            "Whether or not the latest charge for the customer's "
            "latest invoice has failed."
        ),
    )
    # Stripe API returns deleted customers like so:
    # {
    #   "id": "cus_KX439W5dKrpi22",
    #   "object": "customer",
    #   "deleted": true,
    # }
    deleted = models.BooleanField(
        default=False,
        null=True,
        blank=True,
        help_text=(
            "Whether the Customer instance has been deleted upstream in Stripe or not."
        ),
    )
    # <discount>
    coupon = models.ForeignKey(
        "Coupon", null=True, blank=True, on_delete=models.SET_NULL
    )
    coupon_start = StripeDateTimeField(
        null=True,
        blank=True,
        editable=False,
        help_text="If a coupon is present, the date at which it was applied.",
    )
    coupon_end = StripeDateTimeField(
        null=True,
        blank=True,
        editable=False,
        help_text=(
            "If a coupon is present and has a limited duration, "
            "the date that the discount will end."
        ),
    )
    # </discount>
    discount = JSONField(
        null=True,
        blank=True,
        help_text=(
            "Describes the current discount active on the customer, if there is one."
        ),
    )

    email = models.TextField(max_length=5000, default="", blank=True)
    invoice_prefix = models.CharField(
        default="",
        blank=True,
        max_length=255,
        help_text=(
            "The prefix for the customer used to generate unique invoice numbers."
        ),
    )
    invoice_settings = JSONField(
        null=True, blank=True, help_text="The customer's default invoice settings."
    )
    # default_payment_method is actually nested inside invoice_settings
    # this field is a convenience to provide the foreign key
    default_payment_method = StripeForeignKey(
        "PaymentMethod",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name="+",
        help_text=(
            "default payment method used for subscriptions and invoices "
            "for the customer."
        ),
    )
    name = models.TextField(
        max_length=5000,
        default="",
        blank=True,
        help_text="The customer's full name or business name.",
    )
    phone = models.TextField(
        max_length=5000,
        default="",
        blank=True,
        help_text="The customer's phone number.",
    )
    preferred_locales = JSONField(
        null=True,
        blank=True,
        help_text=(
            "The customer's preferred locales (languages), ordered by preference."
        ),
    )
    shipping = JSONField(
        null=True,
        blank=True,
        help_text="Shipping information associated with the customer.",
    )
    tax_exempt = StripeEnumField(
        enum=enums.CustomerTaxExempt,
        default="",
        help_text=(
            "Describes the customer's tax exemption status. When set to reverse, "
            'invoice and receipt PDFs include the text "Reverse charge".'
        ),
    )

    # dj-stripe fields
    subscriber = models.ForeignKey(
        djstripe_settings.get_subscriber_model_string(),
        blank=True,
        null=True,
        on_delete=models.SET_NULL,
        related_name="djstripe_customers",
    )
    date_purged = models.DateTimeField(null=True, editable=False)

    class Meta(StripeModel.Meta):
        unique_together = ("subscriber", "livemode", "djstripe_owner_account")

    def __str__(self):
        if self.subscriber:
            return str(self.subscriber)

        return self.name or self.description or self.id

    @classmethod
    def _manipulate_stripe_object_hook(cls, data):
        # stripe adds a deleted attribute if the Customer has been deleted upstream
        if data.get("deleted"):
            logger.warning(
                f"This customer ({data.get('id')}) has been deleted upstream, in Stripe"
            )

        else:
            # set "deleted" key to False (default)
            data["deleted"] = False

        discount = data.get("discount")
        if discount:
            data["coupon_start"] = discount["start"]
            data["coupon_end"] = discount["end"]

        # Populate the object id for our default_payment_method field (or set it None)
        data["default_payment_method"] = data.get("invoice_settings", {}).get(
            "default_payment_method"
        )

        return data

    @classmethod
    def get_or_create(
        cls,
        subscriber,
        livemode=djstripe_settings.STRIPE_LIVE_MODE,
        stripe_account=None,
    ):
        """
        Get or create a dj-stripe customer.

        :param subscriber: The subscriber model instance for which to get or
            create a customer.
        :type subscriber: User

        :param livemode: Whether to get the subscriber in live or test mode.
        :type livemode: bool
        """

        try:
            return cls.objects.get(subscriber=subscriber, livemode=livemode), False
        except cls.DoesNotExist:
            action = f"create:{subscriber.pk}"
            idempotency_key = djstripe_settings.get_idempotency_key(
                "customer", action, livemode
            )
            return (
                cls.create(
                    subscriber,
                    idempotency_key=idempotency_key,
                    stripe_account=stripe_account,
                ),
                True,
            )

    @classmethod
    def create(cls, subscriber, idempotency_key=None, stripe_account=None):
        metadata = {}
        subscriber_key = djstripe_settings.SUBSCRIBER_CUSTOMER_KEY
        if subscriber_key not in ("", None):
            metadata[subscriber_key] = subscriber.pk

        try:
            # if subscriber table has a get_full_name() method, use it as name
            # ref django.contrib.auth.models.User.get_full_name
            name = subscriber.get_full_name()
        except AttributeError:
            name = None

        stripe_customer = cls._api_create(
            email=subscriber.email,
            name=name,
            idempotency_key=idempotency_key,
            metadata=metadata,
            stripe_account=stripe_account,
        )
        customer, created = cls.objects.get_or_create(
            id=stripe_customer["id"],
            defaults={
                "subscriber": subscriber,
                "livemode": stripe_customer["livemode"],
                "balance": stripe_customer.get("balance", 0),
                "delinquent": stripe_customer.get("delinquent", False),
            },
        )

        return customer

    @property
    def credits(self):
        """
        The customer is considered to have credits if their balance is below 0.
        """
        return abs(min(self.balance, 0))

    @property
    def customer_payment_methods(self):
        """
        An iterable of all of the customer's payment methods
        (sources, then legacy cards)
        """
        for source in self.sources.iterator():
            yield source

        for card in self.legacy_cards.iterator():
            yield card

    @property
    def pending_charges(self):
        """
        The customer is considered to have pending charges if their balance is above 0.
        """
        return max(self.balance, 0)

    def subscribe(self, *, items=None, price=None, plan=None, **kwargs):
        """
        Subscribes this customer to all the prices or plans in the items dict (Recommended).

        :param items: A list of up to 20 subscription items, each with an attached price
        :type list:
            :param items: A dictionary of Plan (or Plan ID) or Price (or Price ID)
            :type dict:  The price or plan to which to subscribe the customer.

        :param price: The price to which to subscribe the customer.
        :type price: Price or string (price ID)

        :param plan: The plan to which to subscribe the customer.
        :type plan: Plan or string (plan ID)
        """
        from .billing import Subscription

        if (items and price) or (items and plan) or (price and plan):
            raise TypeError("Please define only one of items, price or plan arguments.")

        if items is None:
            _items = [{"price": price}]
        else:
            _items = []
            for item in items:
                price = item.get("price", "")
                plan = item.get("plan", "")
                price, kwargs = _sanitise_price(price, plan, **kwargs)
                if "price" in item:
                    _items.append({"price": price})
                if "plan" in item:
                    _items.append({"plan": price})

        stripe_subscription = Subscription._api_create(
            items=_items, customer=self.id, **kwargs
        )

        api_key = kwargs.get("api_key") or self.default_api_key
        return Subscription.sync_from_stripe_data(stripe_subscription, api_key=api_key)

    def charge(
        self,
        amount: Decimal,
        *,
        application_fee: Decimal = None,
        source: Union[str, StripeModel] = None,
        **kwargs,
    ) -> Charge:
        """
        Creates a charge for this customer.

        :param amount: The amount to charge.
        :type amount: Decimal. Precision is 2; anything more will be ignored.
        :param source: The source to use for this charge.
            Must be a source attributed to this customer. If None, the customer's
            default source is used. Can be either the id of the source or
            the source object itself.
        :type source: string, Source
        """

        if not isinstance(amount, Decimal):
            raise ValueError("You must supply a decimal value representing dollars.")

        # Convert Source to id
        if source and isinstance(source, StripeModel):
            source = source.id

        stripe_charge = Charge._api_create(
            customer=self.id,
            amount=int(amount * 100),  # Convert dollars into cents
            application_fee=(
                int(application_fee * 100) if application_fee else None
            ),  # Convert dollars into cents
            source=source,
            **kwargs,
        )

        api_key = kwargs.get("api_key") or self.default_api_key
        return Charge.sync_from_stripe_data(stripe_charge, api_key=api_key)

    def add_invoice_item(
        self,
        amount,
        currency,
        description=None,
        discountable=None,
        invoice=None,
        metadata=None,
        subscription=None,
    ):
        """
        Adds an arbitrary charge or credit to the customer's upcoming invoice.
        Different than creating a charge. Charges are separate bills that get
        processed immediately. Invoice items are appended to the customer's next
        invoice. This is extremely useful when adding surcharges to subscriptions.

        :param amount: The amount to charge.
        :type amount: Decimal. Precision is 2; anything more will be ignored.
        :param currency: 3-letter ISO code for currency
        :type currency: string
        :param description: An arbitrary string.
        :type description: string
        :param discountable: Controls whether discounts apply to this invoice item.
            Defaults to False for prorations or negative invoice items,
            and True for all other invoice items.
        :type discountable: boolean
        :param invoice: An existing invoice to add this invoice item to.
            When left blank, the invoice item will be added to the next upcoming \
             scheduled invoice. \
             Use this when adding invoice items in response to an \
             ``invoice.created`` webhook. You cannot add an invoice \
            item to an invoice that has already been paid, attempted or closed.
        :type invoice: Invoice or string (invoice ID)
        :param metadata: A set of key/value pairs useful for storing
            additional information.
        :type metadata: dict
        :param subscription: A subscription to add this invoice item to.
            When left blank, the invoice item will be be added to the next upcoming \
            scheduled invoice. When set, scheduled invoices for subscriptions other \
            than the specified subscription will ignore the invoice item. \
            Use this when you want to express that an invoice item has been accrued \
            within the context of a particular subscription.
        :type subscription: Subscription or string (subscription ID)

        .. Notes:
        .. if you're using ``Customer.add_invoice_item()`` instead of
        .. ``Customer.add_invoice_item()``, ``invoice`` and ``subscriptions``
        .. can only be strings
        """
        from .billing import InvoiceItem

        if not isinstance(amount, Decimal):
            raise ValueError("You must supply a decimal value representing dollars.")

        # Convert Invoice to id
        if invoice is not None and isinstance(invoice, StripeModel):
            invoice = invoice.id

        # Convert Subscription to id
        if subscription is not None and isinstance(subscription, StripeModel):
            subscription = subscription.id

        stripe_invoiceitem = InvoiceItem._api_create(
            amount=int(amount * 100),  # Convert dollars into cents
            currency=currency,
            customer=self.id,
            description=description,
            discountable=discountable,
            invoice=invoice,
            metadata=metadata,
            subscription=subscription,
        )

        return InvoiceItem.sync_from_stripe_data(
            stripe_invoiceitem, api_key=self.default_api_key
        )

    def add_card(self, source, set_default=True):
        """
        Adds a card to this customer's account.

        :param source: Either a token, like the ones returned by our Stripe.js, or a
            dictionary containing a user's credit card details.
            Stripe will automatically validate the card.
        :type source: string, dict
        :param set_default: Whether or not to set the source as the customer's
            default source
        :type set_default: boolean

        """
        from .payment_methods import DjstripePaymentMethod

        stripe_customer = self.api_retrieve()
        new_stripe_payment_method = stripe_customer.sources.create(source=source)

        if set_default:
            stripe_customer.default_source = new_stripe_payment_method["id"]
            stripe_customer.save()

        new_payment_method = DjstripePaymentMethod.from_stripe_object(
            new_stripe_payment_method
        )

        # Change the default source
        if set_default:
            self.default_source = new_payment_method
            self.save()

        return new_payment_method.resolve()

    def add_payment_method(self, payment_method, set_default=True):
        """
        Adds an already existing payment method to this customer's account

        :param payment_method: PaymentMethod to be attached to the customer
        :type payment_method: str, PaymentMethod
        :param set_default: If true, this will be set as the default_payment_method
        :type set_default: bool
        :rtype: PaymentMethod
        """
        from .payment_methods import PaymentMethod

        stripe_customer = self.api_retrieve()
        payment_method = PaymentMethod.attach(payment_method, stripe_customer)

        if set_default:
            stripe_customer["invoice_settings"][
                "default_payment_method"
            ] = payment_method.id
            stripe_customer.save()

            # Refresh self from the stripe customer, this should have two effects:
            # 1) sets self.default_payment_method (we rely on logic in
            # Customer._manipulate_stripe_object_hook to do this)
            # 2) updates self.invoice_settings.default_payment_methods
            self.sync_from_stripe_data(stripe_customer, api_key=self.default_api_key)
            self.refresh_from_db()

        return payment_method

    def purge(self):
        """Customers are soft deleted as deleted customers are still accessible by the
        Stripe API and sync for all RelatedModels would fail"""
        try:
            self._api_delete()
        except InvalidRequestError as exc:
            if "No such customer:" in str(exc):
                # The exception was thrown because the stripe customer was already
                # deleted on the stripe side, ignore the exception
                pass
            else:
                # The exception was raised for another reason, re-raise it
                raise

        # toggle the deleted flag on Customer to indicate it has been
        # deleted upstream in Stripe
        self.deleted = True

        if self.subscriber:
            # Delete the idempotency key used by Customer.create()
            # So re-creating a customer for this subscriber before the key expires
            # doesn't return the older Customer data
            idempotency_key_action = f"customer:create:{self.subscriber.pk}"
            IdempotencyKey.objects.filter(action=idempotency_key_action).delete()

        self.subscriber = None

        # Remove sources
        self.default_source = None
        for source in self.legacy_cards.all():
            source.remove()

        for source in self.sources.all():
            source.detach()

        self.date_purged = timezone.now()
        self.save()

    def _get_valid_subscriptions(self):
        """Get a list of this customer's valid subscriptions."""

        return [
            subscription
            for subscription in self.subscriptions.all()
            if subscription.is_valid()
        ]

    def is_subscribed_to(self, product: Union[Product, str]) -> bool:
        """
        Checks to see if this customer has an active subscription to the given product.

        :param product: The product for which to check for an active subscription.
        :type product: Product or string (product ID)

        :returns: True if there exists an active subscription, False otherwise.
        """

        if isinstance(product, StripeModel):
            product = product.id

        for subscription in self._get_valid_subscriptions():
            for item in subscription.items.all():
                if item.price and item.price.product.id == product:
                    return True
        return False

    def has_any_active_subscription(self):
        """
        Checks to see if this customer has an active subscription to any plan.

        :returns: True if there exists an active subscription, False otherwise.
        """

        return len(self._get_valid_subscriptions()) != 0

    @property
    def active_subscriptions(self):
        """
        Returns active subscriptions
        (subscriptions with an active status that end in the future).
        """
        return self.subscriptions.filter(
            status=enums.SubscriptionStatus.active,
            current_period_end__gt=timezone.now(),
        )

    @property
    def valid_subscriptions(self):
        """
        Returns this customer's valid subscriptions
        (subscriptions that aren't canceled or incomplete_expired).
        """
        return self.subscriptions.exclude(
            status__in=[
                enums.SubscriptionStatus.canceled,
                enums.SubscriptionStatus.incomplete_expired,
            ]
        )

    @property
    def subscription(self):
        """
        Shortcut to get this customer's subscription.

        :returns: None if the customer has no subscriptions, the subscription if
            the customer has a subscription.
        :raises MultipleSubscriptionException: Raised if the customer has multiple
            subscriptions.
            In this case, use ``Customer.subscriptions`` instead.
        """

        subscriptions = self.valid_subscriptions

        if subscriptions.count() > 1:
            raise MultipleSubscriptionException(
                "This customer has multiple subscriptions. Use Customer.subscriptions "
                "to access them."
            )
        else:
            return subscriptions.first()

    def send_invoice(self, **kwargs):
        """
        Pay and send the customer's latest invoice.

        :returns: True if an invoice was able to be created and paid, False otherwise
            (typically if there was nothing to invoice).
        """
        from .billing import Invoice

        try:
            invoice = Invoice._api_create(customer=self.id)
            invoice.pay(**kwargs)
            return True
        except InvalidRequestError:  # TODO: Check this for a more
            #                           specific error message.
            return False  # There was nothing to invoice

    def retry_unpaid_invoices(self, **kwargs):
        """Attempt to retry collecting payment on the customer's unpaid invoices."""

        self._sync_invoices()
        for invoice in self.invoices.filter(auto_advance=True).exclude(status="paid"):
            try:
                invoice.retry(**kwargs)  # Always retry unpaid invoices
            except InvalidRequestError as exc:
                if str(exc) != "Invoice is already paid":
                    raise

    def add_coupon(self, coupon, idempotency_key=None):
        """
        Add a coupon to a Customer.

        The coupon can be a Coupon object, or a valid Stripe Coupon ID.
        """
        if isinstance(coupon, StripeModel):
            coupon = coupon.id

        stripe_customer = self.api_retrieve()
        stripe_customer["coupon"] = coupon
        stripe_customer.save(idempotency_key=idempotency_key)
        return self.__class__.sync_from_stripe_data(
            stripe_customer, api_key=self.default_api_key
        )

    def upcoming_invoice(self, **kwargs):
        """Gets the upcoming preview invoice (singular) for this customer.

        See `Invoice.upcoming() <#djstripe.Invoice.upcoming>`__.

        The ``customer`` argument to the ``upcoming()`` call is automatically set
         by this method.
        """
        from .billing import Invoice

        kwargs["customer"] = self
        return Invoice.upcoming(**kwargs)

    def _attach_objects_post_save_hook(
        self,
        cls,
        data,
        pending_relations=None,
        api_key=djstripe_settings.STRIPE_SECRET_KEY,
    ):
        from .billing import Coupon
        from .payment_methods import DjstripePaymentMethod

        super()._attach_objects_post_save_hook(
            cls, data, pending_relations=pending_relations, api_key=api_key
        )

        save = False

        customer_sources = data.get("sources")
        sources = {}
        if customer_sources:
            # Have to create sources before we handle the default_source
            # We save all of them in the `sources` dict, so that we can find them
            # by id when we look at the default_source (we need the source type).
            for source in customer_sources["data"]:
                obj, _ = DjstripePaymentMethod._get_or_create_source(
                    source, source["object"], api_key=api_key
                )
                sources[source["id"]] = obj

        discount = data.get("discount")
        if discount:
            coupon, _created = Coupon._get_or_create_from_stripe_object(
                discount, "coupon", api_key=api_key
            )
            if coupon and coupon != self.coupon:
                self.coupon = coupon
                save = True
        elif self.coupon:
            self.coupon = None
            save = True

        if save:
            self.save()

    def _attach_objects_hook(
        self, cls, data, current_ids=None, api_key=djstripe_settings.STRIPE_SECRET_KEY
    ):
        # When we save a customer to Stripe, we add a reference to its Django PK
        # in the `django_account` key. If we find that, we re-attach that PK.
        subscriber_key = djstripe_settings.SUBSCRIBER_CUSTOMER_KEY
        if subscriber_key in ("", None):
            # Disabled. Nothing else to do.
            return

        subscriber_id = data.get("metadata", {}).get(subscriber_key)
        if subscriber_id:
            cls = djstripe_settings.get_subscriber_model()
            try:
                # We have to perform a get(), instead of just attaching the PK
                # blindly as the object may have been deleted or not exist.
                # Attempting to save that would cause an IntegrityError.
                self.subscriber = cls.objects.get(pk=subscriber_id)
            except (cls.DoesNotExist, ValueError):
                logger.warning(
                    "Could not find subscriber %r matching customer %r",
                    subscriber_id,
                    self.id,
                )
                self.subscriber = None

    # SYNC methods should be dropped in favor of the master sync infrastructure proposed
    def _sync_invoices(self, **kwargs):
        from .billing import Invoice

        api_key = kwargs.get("api_key") or self.default_api_key
        for stripe_invoice in Invoice.api_list(customer=self.id, **kwargs):
            Invoice.sync_from_stripe_data(stripe_invoice, api_key=api_key)

    def _sync_charges(self, **kwargs):
        api_key = kwargs.get("api_key") or self.default_api_key
        for stripe_charge in Charge.api_list(customer=self.id, **kwargs):
            Charge.sync_from_stripe_data(stripe_charge, api_key=api_key)

    def _sync_cards(self, **kwargs):
        from .payment_methods import Card

        api_key = kwargs.get("api_key") or self.default_api_key
        for stripe_card in Card.api_list(customer=self, **kwargs):
            Card.sync_from_stripe_data(stripe_card, api_key=api_key)

    def _sync_subscriptions(self, **kwargs):
        from .billing import Subscription

        api_key = kwargs.get("api_key") or self.default_api_key
        for stripe_subscription in Subscription.api_list(
            customer=self.id, status="all", **kwargs
        ):
            Subscription.sync_from_stripe_data(stripe_subscription, api_key=api_key)

Attributes

djstripe.models.core.Customer.active_subscriptions property

Returns active subscriptions (subscriptions with an active status that end in the future).

djstripe.models.core.Customer.address = JSONField(null=True, blank=True, help_text="The customer's address.") class-attribute instance-attribute

djstripe.models.core.Customer.balance = StripeQuantumCurrencyAmountField(null=True, blank=True, default=0, help_text="Current balance (in cents), if any, being stored on the customer's account. If negative, the customer has credit to apply to the next invoice. If positive, the customer has an amount owed that will be added to the next invoice. The balance does not refer to any unpaid invoices; it solely takes into account amounts that have yet to be successfully applied to any invoice. This balance is only taken into account for recurring billing purposes (i.e., subscriptions, invoices, invoice items).") class-attribute instance-attribute

djstripe.models.core.Customer.coupon = models.ForeignKey('Coupon', null=True, blank=True, on_delete=models.SET_NULL) class-attribute instance-attribute

djstripe.models.core.Customer.coupon_end = StripeDateTimeField(null=True, blank=True, editable=False, help_text='If a coupon is present and has a limited duration, the date that the discount will end.') class-attribute instance-attribute

djstripe.models.core.Customer.coupon_start = StripeDateTimeField(null=True, blank=True, editable=False, help_text='If a coupon is present, the date at which it was applied.') class-attribute instance-attribute

djstripe.models.core.Customer.credits property

The customer is considered to have credits if their balance is below 0.

djstripe.models.core.Customer.currency = StripeCurrencyCodeField(blank=True, default='', help_text='The currency the customer can be charged in for recurring billing purposes') class-attribute instance-attribute

djstripe.models.core.Customer.customer_payment_methods property

An iterable of all of the customer's payment methods (sources, then legacy cards)

djstripe.models.core.Customer.date_purged = models.DateTimeField(null=True, editable=False) class-attribute instance-attribute

djstripe.models.core.Customer.default_payment_method = StripeForeignKey('PaymentMethod', null=True, blank=True, on_delete=models.SET_NULL, related_name='+', help_text='default payment method used for subscriptions and invoices for the customer.') class-attribute instance-attribute

djstripe.models.core.Customer.default_source = PaymentMethodForeignKey(on_delete=models.SET_NULL, null=True, blank=True, related_name='customers') class-attribute instance-attribute

djstripe.models.core.Customer.deleted = models.BooleanField(default=False, null=True, blank=True, help_text='Whether the Customer instance has been deleted upstream in Stripe or not.') class-attribute instance-attribute

djstripe.models.core.Customer.delinquent = models.BooleanField(null=True, blank=True, default=False, help_text="Whether or not the latest charge for the customer's latest invoice has failed.") class-attribute instance-attribute

djstripe.models.core.Customer.discount = JSONField(null=True, blank=True, help_text='Describes the current discount active on the customer, if there is one.') class-attribute instance-attribute

djstripe.models.core.Customer.email = models.TextField(max_length=5000, default='', blank=True) class-attribute instance-attribute

djstripe.models.core.Customer.expand_fields = ['default_source', 'sources'] class-attribute instance-attribute

djstripe.models.core.Customer.invoice_prefix = models.CharField(default='', blank=True, max_length=255, help_text='The prefix for the customer used to generate unique invoice numbers.') class-attribute instance-attribute

djstripe.models.core.Customer.invoice_settings = JSONField(null=True, blank=True, help_text="The customer's default invoice settings.") class-attribute instance-attribute

djstripe.models.core.Customer.name = models.TextField(max_length=5000, default='', blank=True, help_text="The customer's full name or business name.") class-attribute instance-attribute

djstripe.models.core.Customer.pending_charges property

The customer is considered to have pending charges if their balance is above 0.

djstripe.models.core.Customer.phone = models.TextField(max_length=5000, default='', blank=True, help_text="The customer's phone number.") class-attribute instance-attribute

djstripe.models.core.Customer.preferred_locales = JSONField(null=True, blank=True, help_text="The customer's preferred locales (languages), ordered by preference.") class-attribute instance-attribute

djstripe.models.core.Customer.shipping = JSONField(null=True, blank=True, help_text='Shipping information associated with the customer.') class-attribute instance-attribute

djstripe.models.core.Customer.stripe_class = stripe.Customer class-attribute instance-attribute

djstripe.models.core.Customer.stripe_dashboard_item_name = 'customers' class-attribute instance-attribute

djstripe.models.core.Customer.subscriber = models.ForeignKey(djstripe_settings.get_subscriber_model_string(), blank=True, null=True, on_delete=models.SET_NULL, related_name='djstripe_customers') class-attribute instance-attribute

djstripe.models.core.Customer.subscription property

Shortcut to get this customer's subscription.

:returns: None if the customer has no subscriptions, the subscription if the customer has a subscription. :raises MultipleSubscriptionException: Raised if the customer has multiple subscriptions. In this case, use Customer.subscriptions instead.

djstripe.models.core.Customer.tax_exempt = StripeEnumField(enum=enums.CustomerTaxExempt, default='', help_text='Describes the customer\'s tax exemption status. When set to reverse, invoice and receipt PDFs include the text "Reverse charge".') class-attribute instance-attribute

djstripe.models.core.Customer.valid_subscriptions property

Returns this customer's valid subscriptions (subscriptions that aren't canceled or incomplete_expired).

Classes

djstripe.models.core.Customer.Meta

Bases: Meta

Source code in djstripe/models/core.py

class Meta(StripeModel.Meta):
    unique_together = ("subscriber", "livemode", "djstripe_owner_account")

Attributes

djstripe.models.core.Customer.Meta.unique_together = ('subscriber', 'livemode', 'djstripe_owner_account') class-attribute instance-attribute

Functions

djstripe.models.core.Customer.__str__()

Source code in djstripe/models/core.py

def __str__(self):
    if self.subscriber:
        return str(self.subscriber)

    return self.name or self.description or self.id

djstripe.models.core.Customer.add_card(source, set_default=True)

Adds a card to this customer's account.

:param source: Either a token, like the ones returned by our Stripe.js, or a dictionary containing a user's credit card details. Stripe will automatically validate the card. :type source: string, dict :param set_default: Whether or not to set the source as the customer's default source :type set_default: boolean

Source code in djstripe/models/core.py

def add_card(self, source, set_default=True):
    """
    Adds a card to this customer's account.

    :param source: Either a token, like the ones returned by our Stripe.js, or a
        dictionary containing a user's credit card details.
        Stripe will automatically validate the card.
    :type source: string, dict
    :param set_default: Whether or not to set the source as the customer's
        default source
    :type set_default: boolean

    """
    from .payment_methods import DjstripePaymentMethod

    stripe_customer = self.api_retrieve()
    new_stripe_payment_method = stripe_customer.sources.create(source=source)

    if set_default:
        stripe_customer.default_source = new_stripe_payment_method["id"]
        stripe_customer.save()

    new_payment_method = DjstripePaymentMethod.from_stripe_object(
        new_stripe_payment_method
    )

    # Change the default source
    if set_default:
        self.default_source = new_payment_method
        self.save()

    return new_payment_method.resolve()

djstripe.models.core.Customer.add_coupon(coupon, idempotency_key=None)

Add a coupon to a Customer.

The coupon can be a Coupon object, or a valid Stripe Coupon ID.

Source code in djstripe/models/core.py

def add_coupon(self, coupon, idempotency_key=None):
    """
    Add a coupon to a Customer.

    The coupon can be a Coupon object, or a valid Stripe Coupon ID.
    """
    if isinstance(coupon, StripeModel):
        coupon = coupon.id

    stripe_customer = self.api_retrieve()
    stripe_customer["coupon"] = coupon
    stripe_customer.save(idempotency_key=idempotency_key)
    return self.__class__.sync_from_stripe_data(
        stripe_customer, api_key=self.default_api_key
    )

djstripe.models.core.Customer.add_invoice_item(amount, currency, description=None, discountable=None, invoice=None, metadata=None, subscription=None)

Adds an arbitrary charge or credit to the customer's upcoming invoice. Different than creating a charge. Charges are separate bills that get processed immediately. Invoice items are appended to the customer's next invoice. This is extremely useful when adding surcharges to subscriptions.

:param amount: The amount to charge. :type amount: Decimal. Precision is 2; anything more will be ignored. :param currency: 3-letter ISO code for currency :type currency: string :param description: An arbitrary string. :type description: string :param discountable: Controls whether discounts apply to this invoice item. Defaults to False for prorations or negative invoice items, and True for all other invoice items. :type discountable: boolean :param invoice: An existing invoice to add this invoice item to. When left blank, the invoice item will be added to the next upcoming scheduled invoice. Use this when adding invoice items in response to an invoice.created webhook. You cannot add an invoice item to an invoice that has already been paid, attempted or closed. :type invoice: Invoice or string (invoice ID) :param metadata: A set of key/value pairs useful for storing additional information. :type metadata: dict :param subscription: A subscription to add this invoice item to. When left blank, the invoice item will be be added to the next upcoming scheduled invoice. When set, scheduled invoices for subscriptions other than the specified subscription will ignore the invoice item. Use this when you want to express that an invoice item has been accrued within the context of a particular subscription. :type subscription: Subscription or string (subscription ID)

.. Notes: .. if you're using Customer.add_invoice_item() instead of .. Customer.add_invoice_item(), invoice and subscriptions .. can only be strings

Source code in djstripe/models/core.py

def add_invoice_item(
    self,
    amount,
    currency,
    description=None,
    discountable=None,
    invoice=None,
    metadata=None,
    subscription=None,
):
    """
    Adds an arbitrary charge or credit to the customer's upcoming invoice.
    Different than creating a charge. Charges are separate bills that get
    processed immediately. Invoice items are appended to the customer's next
    invoice. This is extremely useful when adding surcharges to subscriptions.

    :param amount: The amount to charge.
    :type amount: Decimal. Precision is 2; anything more will be ignored.
    :param currency: 3-letter ISO code for currency
    :type currency: string
    :param description: An arbitrary string.
    :type description: string
    :param discountable: Controls whether discounts apply to this invoice item.
        Defaults to False for prorations or negative invoice items,
        and True for all other invoice items.
    :type discountable: boolean
    :param invoice: An existing invoice to add this invoice item to.
        When left blank, the invoice item will be added to the next upcoming \
         scheduled invoice. \
         Use this when adding invoice items in response to an \
         ``invoice.created`` webhook. You cannot add an invoice \
        item to an invoice that has already been paid, attempted or closed.
    :type invoice: Invoice or string (invoice ID)
    :param metadata: A set of key/value pairs useful for storing
        additional information.
    :type metadata: dict
    :param subscription: A subscription to add this invoice item to.
        When left blank, the invoice item will be be added to the next upcoming \
        scheduled invoice. When set, scheduled invoices for subscriptions other \
        than the specified subscription will ignore the invoice item. \
        Use this when you want to express that an invoice item has been accrued \
        within the context of a particular subscription.
    :type subscription: Subscription or string (subscription ID)

    .. Notes:
    .. if you're using ``Customer.add_invoice_item()`` instead of
    .. ``Customer.add_invoice_item()``, ``invoice`` and ``subscriptions``
    .. can only be strings
    """
    from .billing import InvoiceItem

    if not isinstance(amount, Decimal):
        raise ValueError("You must supply a decimal value representing dollars.")

    # Convert Invoice to id
    if invoice is not None and isinstance(invoice, StripeModel):
        invoice = invoice.id

    # Convert Subscription to id
    if subscription is not None and isinstance(subscription, StripeModel):
        subscription = subscription.id

    stripe_invoiceitem = InvoiceItem._api_create(
        amount=int(amount * 100),  # Convert dollars into cents
        currency=currency,
        customer=self.id,
        description=description,
        discountable=discountable,
        invoice=invoice,
        metadata=metadata,
        subscription=subscription,
    )

    return InvoiceItem.sync_from_stripe_data(
        stripe_invoiceitem, api_key=self.default_api_key
    )

djstripe.models.core.Customer.add_payment_method(payment_method, set_default=True)

Adds an already existing payment method to this customer's account

:param payment_method: PaymentMethod to be attached to the customer :type payment_method: str, PaymentMethod :param set_default: If true, this will be set as the default_payment_method :type set_default: bool :rtype: PaymentMethod

Source code in djstripe/models/core.py

def add_payment_method(self, payment_method, set_default=True):
    """
    Adds an already existing payment method to this customer's account

    :param payment_method: PaymentMethod to be attached to the customer
    :type payment_method: str, PaymentMethod
    :param set_default: If true, this will be set as the default_payment_method
    :type set_default: bool
    :rtype: PaymentMethod
    """
    from .payment_methods import PaymentMethod

    stripe_customer = self.api_retrieve()
    payment_method = PaymentMethod.attach(payment_method, stripe_customer)

    if set_default:
        stripe_customer["invoice_settings"][
            "default_payment_method"
        ] = payment_method.id
        stripe_customer.save()

        # Refresh self from the stripe customer, this should have two effects:
        # 1) sets self.default_payment_method (we rely on logic in
        # Customer._manipulate_stripe_object_hook to do this)
        # 2) updates self.invoice_settings.default_payment_methods
        self.sync_from_stripe_data(stripe_customer, api_key=self.default_api_key)
        self.refresh_from_db()

    return payment_method

djstripe.models.core.Customer.charge(amount, *, application_fee=None, source=None, **kwargs)

Creates a charge for this customer.

:param amount: The amount to charge. :type amount: Decimal. Precision is 2; anything more will be ignored. :param source: The source to use for this charge. Must be a source attributed to this customer. If None, the customer's default source is used. Can be either the id of the source or the source object itself. :type source: string, Source

Source code in djstripe/models/core.py

def charge(
    self,
    amount: Decimal,
    *,
    application_fee: Decimal = None,
    source: Union[str, StripeModel] = None,
    **kwargs,
) -> Charge:
    """
    Creates a charge for this customer.

    :param amount: The amount to charge.
    :type amount: Decimal. Precision is 2; anything more will be ignored.
    :param source: The source to use for this charge.
        Must be a source attributed to this customer. If None, the customer's
        default source is used. Can be either the id of the source or
        the source object itself.
    :type source: string, Source
    """

    if not isinstance(amount, Decimal):
        raise ValueError("You must supply a decimal value representing dollars.")

    # Convert Source to id
    if source and isinstance(source, StripeModel):
        source = source.id

    stripe_charge = Charge._api_create(
        customer=self.id,
        amount=int(amount * 100),  # Convert dollars into cents
        application_fee=(
            int(application_fee * 100) if application_fee else None
        ),  # Convert dollars into cents
        source=source,
        **kwargs,
    )

    api_key = kwargs.get("api_key") or self.default_api_key
    return Charge.sync_from_stripe_data(stripe_charge, api_key=api_key)

djstripe.models.core.Customer.create(subscriber, idempotency_key=None, stripe_account=None) classmethod

Source code in djstripe/models/core.py

@classmethod
def create(cls, subscriber, idempotency_key=None, stripe_account=None):
    metadata = {}
    subscriber_key = djstripe_settings.SUBSCRIBER_CUSTOMER_KEY
    if subscriber_key not in ("", None):
        metadata[subscriber_key] = subscriber.pk

    try:
        # if subscriber table has a get_full_name() method, use it as name
        # ref django.contrib.auth.models.User.get_full_name
        name = subscriber.get_full_name()
    except AttributeError:
        name = None

    stripe_customer = cls._api_create(
        email=subscriber.email,
        name=name,
        idempotency_key=idempotency_key,
        metadata=metadata,
        stripe_account=stripe_account,
    )
    customer, created = cls.objects.get_or_create(
        id=stripe_customer["id"],
        defaults={
            "subscriber": subscriber,
            "livemode": stripe_customer["livemode"],
            "balance": stripe_customer.get("balance", 0),
            "delinquent": stripe_customer.get("delinquent", False),
        },
    )

    return customer

djstripe.models.core.Customer.get_or_create(subscriber, livemode=djstripe_settings.STRIPE_LIVE_MODE, stripe_account=None) classmethod

Get or create a dj-stripe customer.

:param subscriber: The subscriber model instance for which to get or create a customer. :type subscriber: User

:param livemode: Whether to get the subscriber in live or test mode. :type livemode: bool

Source code in djstripe/models/core.py

@classmethod
def get_or_create(
    cls,
    subscriber,
    livemode=djstripe_settings.STRIPE_LIVE_MODE,
    stripe_account=None,
):
    """
    Get or create a dj-stripe customer.

    :param subscriber: The subscriber model instance for which to get or
        create a customer.
    :type subscriber: User

    :param livemode: Whether to get the subscriber in live or test mode.
    :type livemode: bool
    """

    try:
        return cls.objects.get(subscriber=subscriber, livemode=livemode), False
    except cls.DoesNotExist:
        action = f"create:{subscriber.pk}"
        idempotency_key = djstripe_settings.get_idempotency_key(
            "customer", action, livemode
        )
        return (
            cls.create(
                subscriber,
                idempotency_key=idempotency_key,
                stripe_account=stripe_account,
            ),
            True,
        )

djstripe.models.core.Customer.has_any_active_subscription()

Checks to see if this customer has an active subscription to any plan.

:returns: True if there exists an active subscription, False otherwise.

Source code in djstripe/models/core.py

def has_any_active_subscription(self):
    """
    Checks to see if this customer has an active subscription to any plan.

    :returns: True if there exists an active subscription, False otherwise.
    """

    return len(self._get_valid_subscriptions()) != 0

djstripe.models.core.Customer.is_subscribed_to(product)

Checks to see if this customer has an active subscription to the given product.

:param product: The product for which to check for an active subscription. :type product: Product or string (product ID)

:returns: True if there exists an active subscription, False otherwise.

Source code in djstripe/models/core.py

def is_subscribed_to(self, product: Union[Product, str]) -> bool:
    """
    Checks to see if this customer has an active subscription to the given product.

    :param product: The product for which to check for an active subscription.
    :type product: Product or string (product ID)

    :returns: True if there exists an active subscription, False otherwise.
    """

    if isinstance(product, StripeModel):
        product = product.id

    for subscription in self._get_valid_subscriptions():
        for item in subscription.items.all():
            if item.price and item.price.product.id == product:
                return True
    return False

djstripe.models.core.Customer.purge()

Customers are soft deleted as deleted customers are still accessible by the Stripe API and sync for all RelatedModels would fail

Source code in djstripe/models/core.py

def purge(self):
    """Customers are soft deleted as deleted customers are still accessible by the
    Stripe API and sync for all RelatedModels would fail"""
    try:
        self._api_delete()
    except InvalidRequestError as exc:
        if "No such customer:" in str(exc):
            # The exception was thrown because the stripe customer was already
            # deleted on the stripe side, ignore the exception
            pass
        else:
            # The exception was raised for another reason, re-raise it
            raise

    # toggle the deleted flag on Customer to indicate it has been
    # deleted upstream in Stripe
    self.deleted = True

    if self.subscriber:
        # Delete the idempotency key used by Customer.create()
        # So re-creating a customer for this subscriber before the key expires
        # doesn't return the older Customer data
        idempotency_key_action = f"customer:create:{self.subscriber.pk}"
        IdempotencyKey.objects.filter(action=idempotency_key_action).delete()

    self.subscriber = None

    # Remove sources
    self.default_source = None
    for source in self.legacy_cards.all():
        source.remove()

    for source in self.sources.all():
        source.detach()

    self.date_purged = timezone.now()
    self.save()

djstripe.models.core.Customer.retry_unpaid_invoices(**kwargs)

Attempt to retry collecting payment on the customer's unpaid invoices.

Source code in djstripe/models/core.py

def retry_unpaid_invoices(self, **kwargs):
    """Attempt to retry collecting payment on the customer's unpaid invoices."""

    self._sync_invoices()
    for invoice in self.invoices.filter(auto_advance=True).exclude(status="paid"):
        try:
            invoice.retry(**kwargs)  # Always retry unpaid invoices
        except InvalidRequestError as exc:
            if str(exc) != "Invoice is already paid":
                raise

djstripe.models.core.Customer.send_invoice(**kwargs)

Pay and send the customer's latest invoice.

:returns: True if an invoice was able to be created and paid, False otherwise (typically if there was nothing to invoice).

Source code in djstripe/models/core.py

def send_invoice(self, **kwargs):
    """
    Pay and send the customer's latest invoice.

    :returns: True if an invoice was able to be created and paid, False otherwise
        (typically if there was nothing to invoice).
    """
    from .billing import Invoice

    try:
        invoice = Invoice._api_create(customer=self.id)
        invoice.pay(**kwargs)
        return True
    except InvalidRequestError:  # TODO: Check this for a more
        #                           specific error message.
        return False  # There was nothing to invoice

djstripe.models.core.Customer.subscribe(*, items=None, price=None, plan=None, **kwargs)

Subscribes this customer to all the prices or plans in the items dict (Recommended).

:param items: A list of up to 20 subscription items, each with an attached price :type list: :param items: A dictionary of Plan (or Plan ID) or Price (or Price ID) :type dict: The price or plan to which to subscribe the customer.

:param price: The price to which to subscribe the customer. :type price: Price or string (price ID)

:param plan: The plan to which to subscribe the customer. :type plan: Plan or string (plan ID)

Source code in djstripe/models/core.py

def subscribe(self, *, items=None, price=None, plan=None, **kwargs):
    """
    Subscribes this customer to all the prices or plans in the items dict (Recommended).

    :param items: A list of up to 20 subscription items, each with an attached price
    :type list:
        :param items: A dictionary of Plan (or Plan ID) or Price (or Price ID)
        :type dict:  The price or plan to which to subscribe the customer.

    :param price: The price to which to subscribe the customer.
    :type price: Price or string (price ID)

    :param plan: The plan to which to subscribe the customer.
    :type plan: Plan or string (plan ID)
    """
    from .billing import Subscription

    if (items and price) or (items and plan) or (price and plan):
        raise TypeError("Please define only one of items, price or plan arguments.")

    if items is None:
        _items = [{"price": price}]
    else:
        _items = []
        for item in items:
            price = item.get("price", "")
            plan = item.get("plan", "")
            price, kwargs = _sanitise_price(price, plan, **kwargs)
            if "price" in item:
                _items.append({"price": price})
            if "plan" in item:
                _items.append({"plan": price})

    stripe_subscription = Subscription._api_create(
        items=_items, customer=self.id, **kwargs
    )

    api_key = kwargs.get("api_key") or self.default_api_key
    return Subscription.sync_from_stripe_data(stripe_subscription, api_key=api_key)

djstripe.models.core.Customer.upcoming_invoice(**kwargs)

Gets the upcoming preview invoice (singular) for this customer.

See Invoice.upcoming() <#djstripe.Invoice.upcoming>__.

The customer argument to the upcoming() call is automatically set by this method.

Source code in djstripe/models/core.py

def upcoming_invoice(self, **kwargs):
    """Gets the upcoming preview invoice (singular) for this customer.

    See `Invoice.upcoming() <#djstripe.Invoice.upcoming>`__.

    The ``customer`` argument to the ``upcoming()`` call is automatically set
     by this method.
    """
    from .billing import Invoice

    kwargs["customer"] = self
    return Invoice.upcoming(**kwargs)

djstripe.models.core.Dispute

Bases: StripeModel

A dispute occurs when a customer questions your charge with their card issuer. When this happens, you're given the opportunity to respond to the dispute with evidence that shows that the charge is legitimate

Stripe documentation: https://stripe.com/docs/api?lang=python#disputes

Source code in djstripe/models/core.py

class Dispute(StripeModel):
    """
    A dispute occurs when a customer questions your charge with their
    card issuer. When this happens, you're given the opportunity to
    respond to the dispute with evidence that shows that the charge is legitimate

    Stripe documentation: https://stripe.com/docs/api?lang=python#disputes
    """

    stripe_class = stripe.Dispute
    stripe_dashboard_item_name = "payments"

    amount = StripeQuantumCurrencyAmountField(
        help_text=(
            "Disputed amount (in cents). Usually the amount of the charge, "
            "but can differ "
            "(usually because of currency fluctuation or because only part of "
            "the order is disputed)."
        )
    )
    balance_transaction = StripeForeignKey(
        "BalanceTransaction",
        null=True,
        on_delete=models.CASCADE,
        related_name="disputes",
        help_text=(
            "Balance transaction that describes the impact on your account balance."
        ),
    )
    balance_transactions = JSONField(
        default=list,
        help_text=(
            "List of 0, 1 or 2 Balance Transactions that show funds withdrawn and"
            " reinstated to your Stripe account as a result of this dispute."
        ),
    )
    # charge is nullable to avoid infinite sync as Charge model has a dispute field as well
    charge = StripeForeignKey(
        "Charge",
        null=True,
        on_delete=models.CASCADE,
        related_name="disputes",
        help_text="The charge that was disputed",
    )
    currency = StripeCurrencyCodeField()
    evidence = JSONField(help_text="Evidence provided to respond to a dispute.")
    evidence_details = JSONField(help_text="Information about the evidence submission.")
    is_charge_refundable = models.BooleanField(
        help_text=(
            "If true, it is still possible to refund the disputed payment. "
            "Once the payment has been fully refunded, no further funds will "
            "be withdrawn from your Stripe account as a result of this dispute."
        )
    )
    payment_intent = StripeForeignKey(
        "PaymentIntent",
        null=True,
        on_delete=models.CASCADE,
        related_name="disputes",
        help_text="The PaymentIntent that was disputed",
    )
    reason = StripeEnumField(enum=enums.DisputeReason)
    status = StripeEnumField(enum=enums.DisputeStatus)

    def __str__(self):
        amount = get_friendly_currency_amount(self.amount / 100, self.currency)
        status = enums.DisputeStatus.humanize(self.status)
        return f"{amount} ({status}) "

    def get_stripe_dashboard_url(self) -> str:
        """Get the stripe dashboard url for this object."""
        return (
            f"{self._get_base_stripe_dashboard_url()}"
            f"{self.stripe_dashboard_item_name}/{self.payment_intent.id}"
        )

    def _attach_objects_post_save_hook(
        self,
        cls,
        data,
        pending_relations=None,
        api_key=djstripe_settings.STRIPE_SECRET_KEY,
    ):
        super()._attach_objects_post_save_hook(
            cls, data, pending_relations=pending_relations, api_key=api_key
        )

        # Retrieve and save files from the dispute.evidence object.
        # todo find a better way of retrieving and syncing File Type fields from Dispute object
        for field in (
            "cancellation_policy",
            "customer_communication",
            "customer_signature",
            "duplicate_charge_documentation",
            "receipt",
            "refund_policy",
            "service_documentation",
            "shipping_documentation",
            "uncategorized_file",
        ):
            file_upload_id = self.evidence.get(field, None)
            if file_upload_id:
                try:
                    File.sync_from_stripe_data(
                        File(id=file_upload_id).api_retrieve(api_key=api_key),
                        api_key=api_key,
                    )
                except stripe.error.PermissionError:
                    # No permission to retrieve the data with the key
                    # Log a warning message
                    logger.warning(
                        "No permission to retrieve the File Evidence Object."
                    )
                except stripe.error.InvalidRequestError:
                    raise

        # iterate and sync every balance transaction
        for stripe_balance_transaction in self.balance_transactions:
            BalanceTransaction.sync_from_stripe_data(
                stripe_balance_transaction, api_key=api_key
            )

Attributes

djstripe.models.core.Dispute.amount = StripeQuantumCurrencyAmountField(help_text='Disputed amount (in cents). Usually the amount of the charge, but can differ (usually because of currency fluctuation or because only part of the order is disputed).') class-attribute instance-attribute

djstripe.models.core.Dispute.balance_transaction = StripeForeignKey('BalanceTransaction', null=True, on_delete=models.CASCADE, related_name='disputes', help_text='Balance transaction that describes the impact on your account balance.') class-attribute instance-attribute

djstripe.models.core.Dispute.balance_transactions = JSONField(default=list, help_text='List of 0, 1 or 2 Balance Transactions that show funds withdrawn and reinstated to your Stripe account as a result of this dispute.') class-attribute instance-attribute

djstripe.models.core.Dispute.charge = StripeForeignKey('Charge', null=True, on_delete=models.CASCADE, related_name='disputes', help_text='The charge that was disputed') class-attribute instance-attribute

djstripe.models.core.Dispute.currency = StripeCurrencyCodeField() class-attribute instance-attribute

djstripe.models.core.Dispute.evidence = JSONField(help_text='Evidence provided to respond to a dispute.') class-attribute instance-attribute

djstripe.models.core.Dispute.evidence_details = JSONField(help_text='Information about the evidence submission.') class-attribute instance-attribute

djstripe.models.core.Dispute.is_charge_refundable = models.BooleanField(help_text='If true, it is still possible to refund the disputed payment. Once the payment has been fully refunded, no further funds will be withdrawn from your Stripe account as a result of this dispute.') class-attribute instance-attribute

djstripe.models.core.Dispute.payment_intent = StripeForeignKey('PaymentIntent', null=True, on_delete=models.CASCADE, related_name='disputes', help_text='The PaymentIntent that was disputed') class-attribute instance-attribute

djstripe.models.core.Dispute.reason = StripeEnumField(enum=enums.DisputeReason) class-attribute instance-attribute

djstripe.models.core.Dispute.status = StripeEnumField(enum=enums.DisputeStatus) class-attribute instance-attribute

djstripe.models.core.Dispute.stripe_class = stripe.Dispute class-attribute instance-attribute

djstripe.models.core.Dispute.stripe_dashboard_item_name = 'payments' class-attribute instance-attribute

Functions

djstripe.models.core.Dispute.__str__()

Source code in djstripe/models/core.py

def __str__(self):
    amount = get_friendly_currency_amount(self.amount / 100, self.currency)
    status = enums.DisputeStatus.humanize(self.status)
    return f"{amount} ({status}) "

djstripe.models.core.Dispute.get_stripe_dashboard_url()

Get the stripe dashboard url for this object.

Source code in djstripe/models/core.py

def get_stripe_dashboard_url(self) -> str:
    """Get the stripe dashboard url for this object."""
    return (
        f"{self._get_base_stripe_dashboard_url()}"
        f"{self.stripe_dashboard_item_name}/{self.payment_intent.id}"
    )

djstripe.models.core.Event

Bases: StripeModel

Events are Stripe's way of letting you know when something interesting happens in your account. When an interesting event occurs, a new Event object is created and POSTed to the configured webhook URL if the Event type matches.

Stripe documentation: https://stripe.com/docs/api/events?lang=python

Source code in djstripe/models/core.py

class Event(StripeModel):
    """
    Events are Stripe's way of letting you know when something interesting
    happens in your account.
    When an interesting event occurs, a new Event object is created and POSTed
    to the configured webhook URL if the Event type matches.

    Stripe documentation: https://stripe.com/docs/api/events?lang=python
    """

    stripe_class = stripe.Event
    stripe_dashboard_item_name = "events"

    api_version = models.CharField(
        max_length=64,
        blank=True,
        help_text=(
            "the API version at which the event data was "
            "rendered. Blank for old entries only, all new entries will have this value"
        ),
    )
    data = JSONField(
        help_text=(
            "data received at webhook. data should be considered to be garbage "
            "until validity check is run and valid flag is set"
        )
    )
    request_id = models.CharField(
        max_length=50,
        help_text=(
            "Information about the request that triggered this event, "
            "for traceability purposes. If empty string then this is an old entry "
            "without that data. If Null then this is not an old entry, but a Stripe "
            "'automated' event with no associated request."
        ),
        default="",
        blank=True,
    )
    idempotency_key = models.TextField(default="", blank=True)
    type = models.CharField(max_length=250, help_text="Stripe's event description code")

    def __str__(self):
        return f"type={self.type}, id={self.id}"

    def _attach_objects_hook(
        self, cls, data, current_ids=None, api_key=djstripe_settings.STRIPE_SECRET_KEY
    ):
        if self.api_version is None:
            # as of api version 2017-02-14, the account.application.deauthorized
            # event sends None as api_version.
            # If we receive that, store an empty string instead.
            # Remove this hack if this gets fixed upstream.
            self.api_version = ""

        request_obj = data.get("request", None)
        if isinstance(request_obj, dict):
            # Format as of 2017-05-25
            self.request_id = request_obj.get("id") or ""
            self.idempotency_key = request_obj.get("idempotency_key") or ""
        else:
            # Format before 2017-05-25
            self.request_id = request_obj or ""

    @classmethod
    def process(cls, data, api_key=djstripe_settings.STRIPE_SECRET_KEY):
        qs = cls.objects.filter(id=data["id"])
        if qs.exists():
            return qs.first()

        # Rollback any DB operations in the case of failure so
        # we will retry creating and processing the event the
        # next time the webhook fires.
        with transaction.atomic():
            # process the event and create an Event Object
            ret = cls._create_from_stripe_object(data, api_key=api_key)
            ret.invoke_webhook_handlers()
            return ret

    def invoke_webhook_handlers(self):
        """
        Invokes any webhook handlers that have been registered for this event
        based on event type or event sub-type.

        See event handlers registered in the ``djstripe.event_handlers`` module
        (or handlers registered in djstripe plugins or contrib packages).
        """

        webhooks.call_handlers(event=self)

        signal = WEBHOOK_SIGNALS.get(self.type)
        if signal:
            return signal.send(sender=Event, event=self)

    @cached_property
    def parts(self):
        """Gets the event category/verb as a list of parts."""
        return str(self.type).split(".")

    @cached_property
    def category(self):
        """Gets the event category string (e.g. 'customer')."""
        return self.parts[0]

    @cached_property
    def verb(self):
        """Gets the event past-tense verb string (e.g. 'updated')."""
        return ".".join(self.parts[1:])

    @property
    def customer(self):
        data = self.data["object"]
        if data["object"] == "customer":
            customer_id = get_id_from_stripe_data(data.get("id"))
        else:
            customer_id = get_id_from_stripe_data(data.get("customer"))

        if customer_id:
            return Customer._get_or_retrieve(
                id=customer_id,
                stripe_account=getattr(self.djstripe_owner_account, "id", None),
                api_key=self.default_api_key,
            )

Attributes

djstripe.models.core.Event.api_version = models.CharField(max_length=64, blank=True, help_text='the API version at which the event data was rendered. Blank for old entries only, all new entries will have this value') class-attribute instance-attribute

djstripe.models.core.Event.customer property

djstripe.models.core.Event.data = JSONField(help_text='data received at webhook. data should be considered to be garbage until validity check is run and valid flag is set') class-attribute instance-attribute

djstripe.models.core.Event.idempotency_key = models.TextField(default='', blank=True) class-attribute instance-attribute

djstripe.models.core.Event.request_id = models.CharField(max_length=50, help_text="Information about the request that triggered this event, for traceability purposes. If empty string then this is an old entry without that data. If Null then this is not an old entry, but a Stripe 'automated' event with no associated request.", default='', blank=True) class-attribute instance-attribute

djstripe.models.core.Event.stripe_class = stripe.Event class-attribute instance-attribute

djstripe.models.core.Event.stripe_dashboard_item_name = 'events' class-attribute instance-attribute

djstripe.models.core.Event.type = models.CharField(max_length=250, help_text="Stripe's event description code") class-attribute instance-attribute

Functions

djstripe.models.core.Event.__str__()

Source code in djstripe/models/core.py

def __str__(self):
    return f"type={self.type}, id={self.id}"

djstripe.models.core.Event.category()

Gets the event category string (e.g. 'customer').

Source code in djstripe/models/core.py

@cached_property
def category(self):
    """Gets the event category string (e.g. 'customer')."""
    return self.parts[0]

djstripe.models.core.Event.invoke_webhook_handlers()

Invokes any webhook handlers that have been registered for this event based on event type or event sub-type.

See event handlers registered in the djstripe.event_handlers module (or handlers registered in djstripe plugins or contrib packages).

Source code in djstripe/models/core.py

def invoke_webhook_handlers(self):
    """
    Invokes any webhook handlers that have been registered for this event
    based on event type or event sub-type.

    See event handlers registered in the ``djstripe.event_handlers`` module
    (or handlers registered in djstripe plugins or contrib packages).
    """

    webhooks.call_handlers(event=self)

    signal = WEBHOOK_SIGNALS.get(self.type)
    if signal:
        return signal.send(sender=Event, event=self)

djstripe.models.core.Event.parts()

Gets the event category/verb as a list of parts.

Source code in djstripe/models/core.py

@cached_property
def parts(self):
    """Gets the event category/verb as a list of parts."""
    return str(self.type).split(".")

djstripe.models.core.Event.process(data, api_key=djstripe_settings.STRIPE_SECRET_KEY) classmethod

Source code in djstripe/models/core.py

@classmethod
def process(cls, data, api_key=djstripe_settings.STRIPE_SECRET_KEY):
    qs = cls.objects.filter(id=data["id"])
    if qs.exists():
        return qs.first()

    # Rollback any DB operations in the case of failure so
    # we will retry creating and processing the event the
    # next time the webhook fires.
    with transaction.atomic():
        # process the event and create an Event Object
        ret = cls._create_from_stripe_object(data, api_key=api_key)
        ret.invoke_webhook_handlers()
        return ret

djstripe.models.core.Event.verb()

Gets the event past-tense verb string (e.g. 'updated').

Source code in djstripe/models/core.py

@cached_property
def verb(self):
    """Gets the event past-tense verb string (e.g. 'updated')."""
    return ".".join(self.parts[1:])

djstripe.models.core.File

Bases: StripeModel

This is an object representing a file hosted on Stripe's servers. The file may have been uploaded by yourself using the create file request (for example, when uploading dispute evidence) or it may have been created by Stripe (for example, the results of a Sigma scheduled query).

Stripe documentation: https://stripe.com/docs/api/files?lang=python

Source code in djstripe/models/core.py

class File(StripeModel):
    """
    This is an object representing a file hosted on Stripe's servers.
    The file may have been uploaded by yourself using the create file request
    (for example, when uploading dispute evidence) or it may have been created by
    Stripe (for example, the results of a Sigma scheduled query).

    Stripe documentation: https://stripe.com/docs/api/files?lang=python
    """

    stripe_class = stripe.File

    filename = models.CharField(
        max_length=255,
        help_text="A filename for the file, suitable for saving to a filesystem.",
    )
    purpose = StripeEnumField(
        enum=enums.FilePurpose, help_text="The purpose of the uploaded file."
    )
    size = models.IntegerField(help_text="The size in bytes of the file upload object.")
    type = StripeEnumField(
        enum=enums.FileType, help_text="The type of the file returned."
    )
    url = models.CharField(
        max_length=200,
        help_text="A read-only URL where the uploaded file can be accessed.",
    )

    @classmethod
    def is_valid_object(cls, data):
        return data and data.get("object") in ("file", "file_upload")

    def __str__(self):
        return f"{self.filename}, {enums.FilePurpose.humanize(self.purpose)}"

Attributes

djstripe.models.core.File.filename = models.CharField(max_length=255, help_text='A filename for the file, suitable for saving to a filesystem.') class-attribute instance-attribute

djstripe.models.core.File.purpose = StripeEnumField(enum=enums.FilePurpose, help_text='The purpose of the uploaded file.') class-attribute instance-attribute

djstripe.models.core.File.size = models.IntegerField(help_text='The size in bytes of the file upload object.') class-attribute instance-attribute

djstripe.models.core.File.stripe_class = stripe.File class-attribute instance-attribute

djstripe.models.core.File.type = StripeEnumField(enum=enums.FileType, help_text='The type of the file returned.') class-attribute instance-attribute

djstripe.models.core.File.url = models.CharField(max_length=200, help_text='A read-only URL where the uploaded file can be accessed.') class-attribute instance-attribute

Functions

djstripe.models.core.File.__str__()

Source code in djstripe/models/core.py

def __str__(self):
    return f"{self.filename}, {enums.FilePurpose.humanize(self.purpose)}"

djstripe.models.core.File.is_valid_object(data) classmethod

Source code in djstripe/models/core.py

@classmethod
def is_valid_object(cls, data):
    return data and data.get("object") in ("file", "file_upload")

djstripe.models.core.FileLink

Bases: StripeModel

To share the contents of a File object with non-Stripe users, you can create a FileLink. FileLinks contain a URL that can be used to retrieve the contents of the file without authentication.

Stripe documentation: https://stripe.com/docs/api/file_links?lang=python

Source code in djstripe/models/core.py

class FileLink(StripeModel):
    """
    To share the contents of a File object with non-Stripe users,
    you can create a FileLink. FileLinks contain a URL that can be used
    to retrieve the contents of the file without authentication.

    Stripe documentation: https://stripe.com/docs/api/file_links?lang=python
    """

    stripe_class = stripe.FileLink

    expires_at = StripeDateTimeField(
        null=True, blank=True, help_text="Time at which the link expires."
    )
    file = StripeForeignKey("File", on_delete=models.CASCADE)
    url = models.URLField(help_text="The publicly accessible URL to download the file.")

    def __str__(self):
        return f"{self.file.filename}, {self.url}"

Attributes

djstripe.models.core.FileLink.expires_at = StripeDateTimeField(null=True, blank=True, help_text='Time at which the link expires.') class-attribute instance-attribute

djstripe.models.core.FileLink.file = StripeForeignKey('File', on_delete=models.CASCADE) class-attribute instance-attribute

djstripe.models.core.FileLink.stripe_class = stripe.FileLink class-attribute instance-attribute

djstripe.models.core.FileLink.url = models.URLField(help_text='The publicly accessible URL to download the file.') class-attribute instance-attribute

Functions

djstripe.models.core.FileLink.__str__()

Source code in djstripe/models/core.py

def __str__(self):
    return f"{self.file.filename}, {self.url}"

djstripe.models.core.Mandate

Bases: StripeModel

A Mandate is a record of the permission a customer has given you to debit their payment method.

https://stripe.com/docs/api/mandates

Source code in djstripe/models/core.py

class Mandate(StripeModel):
    """
    A Mandate is a record of the permission a customer has given you to debit their payment method.

    https://stripe.com/docs/api/mandates
    """

    stripe_class = stripe.Mandate

    customer_acceptance = JSONField(
        help_text="Details about the customer's acceptance of the mandate."
    )
    payment_method = StripeForeignKey("paymentmethod", on_delete=models.CASCADE)
    payment_method_details = JSONField(
        help_text="Additional mandate information specific to the payment method type."
    )
    status = StripeEnumField(
        enum=enums.MandateStatus,
        help_text=(
            "The status of the mandate, which indicates whether it can be used to"
            " initiate a payment."
        ),
    )
    type = StripeEnumField(
        enum=enums.MandateType,
        help_text=(
            "The status of the mandate, which indicates whether it can be used to"
            " initiate a payment."
        ),
    )
    multi_use = JSONField(
        null=True,
        blank=True,
        help_text=(
            "If this is a `multi_use` mandate, this hash contains details about the"
            " mandate."
        ),
    )
    single_use = JSONField(
        null=True,
        blank=True,
        help_text=(
            "If this is a `single_use` mandate, this hash contains details about the"
            " mandate."
        ),
    )

Attributes

djstripe.models.core.Mandate.customer_acceptance = JSONField(help_text="Details about the customer's acceptance of the mandate.") class-attribute instance-attribute

djstripe.models.core.Mandate.multi_use = JSONField(null=True, blank=True, help_text='If this is a `multi_use` mandate, this hash contains details about the mandate.') class-attribute instance-attribute

djstripe.models.core.Mandate.payment_method = StripeForeignKey('paymentmethod', on_delete=models.CASCADE) class-attribute instance-attribute

djstripe.models.core.Mandate.payment_method_details = JSONField(help_text='Additional mandate information specific to the payment method type.') class-attribute instance-attribute

djstripe.models.core.Mandate.single_use = JSONField(null=True, blank=True, help_text='If this is a `single_use` mandate, this hash contains details about the mandate.') class-attribute instance-attribute

djstripe.models.core.Mandate.status = StripeEnumField(enum=enums.MandateStatus, help_text='The status of the mandate, which indicates whether it can be used to initiate a payment.') class-attribute instance-attribute

djstripe.models.core.Mandate.stripe_class = stripe.Mandate class-attribute instance-attribute

djstripe.models.core.Mandate.type = StripeEnumField(enum=enums.MandateType, help_text='The status of the mandate, which indicates whether it can be used to initiate a payment.') class-attribute instance-attribute

djstripe.models.core.PaymentIntent

Bases: StripeModel

A PaymentIntent guides you through the process of collecting a payment from your customer. We recommend that you create exactly one PaymentIntent for each order or customer session in your system. You can reference the PaymentIntent later to see the history of payment attempts for a particular session.

A PaymentIntent transitions through multiple statuses throughout its lifetime as it interfaces with Stripe.js to perform authentication flows and ultimately creates at most one successful charge.

Stripe documentation: https://stripe.com/docs/api?lang=python#payment_intents

Source code in djstripe/models/core.py

class PaymentIntent(StripeModel):
    """
    A PaymentIntent guides you through the process of collecting a payment
    from your customer. We recommend that you create exactly one PaymentIntent for each order
    or customer session in your system. You can reference the PaymentIntent later to
    see the history of payment attempts for a particular session.

    A PaymentIntent transitions through multiple statuses throughout its lifetime as
    it interfaces with Stripe.js to perform authentication flows and ultimately
    creates at most one successful charge.

    Stripe documentation: https://stripe.com/docs/api?lang=python#payment_intents
    """

    stripe_class = stripe.PaymentIntent
    stripe_dashboard_item_name = "payments"

    amount = StripeQuantumCurrencyAmountField(
        help_text="Amount (in cents) intended to be collected by this PaymentIntent."
    )
    amount_capturable = StripeQuantumCurrencyAmountField(
        help_text="Amount (in cents) that can be captured from this PaymentIntent."
    )
    amount_received = StripeQuantumCurrencyAmountField(
        help_text="Amount (in cents) that was collected by this PaymentIntent."
    )
    # application
    # application_fee_amount
    canceled_at = StripeDateTimeField(
        null=True,
        blank=True,
        default=None,
        help_text=(
            "Populated when status is canceled, this is the time at which the "
            "PaymentIntent was canceled. Measured in seconds since the Unix epoch."
        ),
    )

    cancellation_reason = StripeEnumField(
        enum=enums.PaymentIntentCancellationReason,
        blank=True,
        help_text=(
            "Reason for cancellation of this PaymentIntent, either user-provided "
            "(duplicate, fraudulent, requested_by_customer, or abandoned) or "
            "generated by Stripe internally (failed_invoice, void_invoice, "
            "or automatic)."
        ),
    )
    capture_method = StripeEnumField(
        enum=enums.CaptureMethod,
        help_text="Capture method of this PaymentIntent, one of automatic or manual.",
    )
    client_secret = models.TextField(
        max_length=5000,
        help_text=(
            "The client secret of this PaymentIntent. "
            "Used for client-side retrieval using a publishable key."
        ),
    )
    confirmation_method = StripeEnumField(
        enum=enums.ConfirmationMethod,
        help_text=(
            "Confirmation method of this PaymentIntent, one of manual or automatic."
        ),
    )
    currency = StripeCurrencyCodeField()
    customer = StripeForeignKey(
        "Customer",
        null=True,
        on_delete=models.CASCADE,
        help_text="Customer this PaymentIntent is for if one exists.",
    )
    description = models.TextField(
        max_length=1000,
        default="",
        blank=True,
        help_text=(
            "An arbitrary string attached to the object. "
            "Often useful for displaying to users."
        ),
    )
    last_payment_error = JSONField(
        null=True,
        blank=True,
        help_text=(
            "The payment error encountered in the previous PaymentIntent confirmation."
        ),
    )
    next_action = JSONField(
        null=True,
        blank=True,
        help_text=(
            "If present, this property tells you what actions you need to take "
            "in order for your customer to fulfill a payment using the provided source."
        ),
    )
    on_behalf_of = StripeForeignKey(
        "Account",
        on_delete=models.CASCADE,
        null=True,
        blank=True,
        help_text=(
            "The account (if any) for which the funds of the "
            "PaymentIntent are intended."
        ),
        related_name="payment_intents",
    )
    payment_method = StripeForeignKey(
        "PaymentMethod",
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        help_text="Payment method used in this PaymentIntent.",
    )
    payment_method_types = JSONField(
        help_text=(
            "The list of payment method types (e.g. card) that this "
            "PaymentIntent is allowed to use."
        )
    )
    receipt_email = models.CharField(
        blank=True,
        max_length=255,
        help_text=(
            "Email address that the receipt for the resulting payment will be sent to."
        ),
    )
    # TODO: Add `review` field after we add Review model.
    setup_future_usage = StripeEnumField(
        enum=enums.IntentUsage,
        null=True,
        blank=True,
        help_text=(
            "Indicates that you intend to make future payments with this "
            "PaymentIntent's payment method. "
            "If present, the payment method used with this PaymentIntent can "
            "be attached to a Customer, even after the transaction completes. "
            "Use `on_session` if you intend to only reuse the payment method "
            "when your customer is present in your checkout flow. Use `off_session` "
            "if your customer may or may not be in your checkout flow. "
            "Stripe uses `setup_future_usage` to dynamically optimize "
            "your payment flow and comply with regional legislation and network rules. "
            "For example, if your customer is impacted by SCA, using `off_session` "
            "will ensure that they are authenticated while processing this "
            "PaymentIntent. You will then be able to make later off-session payments "
            "for this customer."
        ),
    )
    shipping = JSONField(
        null=True, blank=True, help_text="Shipping information for this PaymentIntent."
    )
    statement_descriptor = models.CharField(
        max_length=22,
        blank=True,
        help_text=(
            "For non-card charges, you can use this value as the complete description "
            "that appears on your customers' statements. Must contain at least one "
            "letter, maximum 22 characters."
        ),
    )
    status = StripeEnumField(
        enum=enums.PaymentIntentStatus,
        help_text=(
            "Status of this PaymentIntent, one of requires_payment_method, "
            "requires_confirmation, requires_action, processing, requires_capture, "
            "canceled, or succeeded. "
            "You can read more about PaymentIntent statuses here."
        ),
    )
    transfer_data = JSONField(
        null=True,
        blank=True,
        help_text=(
            "The data with which to automatically create a Transfer when the payment "
            "is finalized. "
            "See the PaymentIntents Connect usage guide for details."
        ),
    )
    transfer_group = models.CharField(
        blank=True,
        max_length=255,
        help_text=(
            "A string that identifies the resulting payment as part of a group. "
            "See the PaymentIntents Connect usage guide for details."
        ),
    )

    def __str__(self):
        account = self.on_behalf_of
        customer = self.customer
        amount = get_friendly_currency_amount(self.amount / 100, self.currency)
        status = enums.PaymentIntentStatus.humanize(self.status)

        if account and customer:
            return f"{amount} ({status}) for {account} by {customer}"
        if account:
            return f"{amount} for {account}. {status}"
        if customer:
            return f"{amount} by {customer}. {status}"

        return f"{amount} ({status})"

    def update(self, api_key=None, **kwargs):
        """
        Call the stripe API's modify operation for thi