derp.payments – Payments

Payments client and typed models.

class derp.payments.PaymentsClient

Bases: object

Async wrapper around Stripe payments APIs.

__init__(config)

Parameters:

config (PaymentsConfig)

async connect()

Initialize Stripe client state.

Return type:

None

async disconnect()

Clear Stripe client state.

Return type:

None

async create_customer(*, email=None, name=None, phone=None, metadata=None)

Create a Stripe customer.

Parameters:

• email (str | None)

• name (str | None)

• phone (str | None)

• metadata (dict[str, str] | None)

Return type:

Customer

async retrieve_customer(customer_id, *, expand=None)

Retrieve a Stripe customer.

Parameters:

• customer_id (str)

• expand (list[str] | None)

Return type:

Customer

async update_customer(customer_id, *, email=None, name=None, phone=None, metadata=None)

Update a Stripe customer.

Parameters:

• customer_id (str)

• email (str | None)

• name (str | None)

• phone (str | None)

• metadata (dict[str, str] | None)

Return type:

Customer

async create_checkout_session(*, mode, success_url, cancel_url, line_items, customer_id=None, customer_email=None, client_reference_id=None, metadata=None, allow_promotion_codes=None, idempotency_key=None)

Create a Stripe checkout session.

Parameters:

• mode (CheckoutSessionMode | str)

• success_url (str)

• cancel_url (str)

• line_items (list[dict[str, str | int]])

• customer_id (str | None)

• customer_email (str | None)

• client_reference_id (str | None)

• metadata (dict[str, str] | None)

• allow_promotion_codes (bool | None)

• idempotency_key (str | None)

Return type:

CheckoutSession

async retrieve_checkout_session(session_id, *, expand=None)

Retrieve a Stripe checkout session.

Parameters:

• session_id (str)

• expand (list[str] | None)

Return type:

CheckoutSession

async expire_checkout_session(session_id)

Expire a Stripe checkout session.

Parameters:

session_id (str)

Return type:

CheckoutSession

async list_customers(*, limit=25, starting_after=None)

List Stripe customers.

Parameters:

• limit (int)

• starting_after (str | None)

Return type:

StripeListResult

async list_products(*, limit=25, starting_after=None)

List Stripe products with expanded default price.

Parameters:

• limit (int)

• starting_after (str | None)

Return type:

StripeListResult

async list_subscriptions(*, limit=25, starting_after=None)

List Stripe subscriptions across all statuses.

Parameters:

• limit (int)

• starting_after (str | None)

Return type:

StripeListResult

async list_invoices(*, limit=25, starting_after=None)

List Stripe invoices.

Parameters:

• limit (int)

• starting_after (str | None)

Return type:

StripeListResult

async list_charges(*, limit=25, starting_after=None)

List Stripe charges.

Parameters:

• limit (int)

• starting_after (str | None)

Return type:

StripeListResult

async create_account(*, type=None, country=None, email=None, metadata=None, capabilities=None, business_type=None, business_profile=None)

Create a Stripe Connect account.

Parameters:

• type (AccountType | str | None)

• country (str | None)

• email (str | None)

• metadata (dict[str, str] | None)

• capabilities (dict[str, dict[str, bool]] | None)

• business_type (str | None)

• business_profile (dict[str, Any] | None)

Return type:

Account

async retrieve_account(account_id)

Retrieve a Stripe Connect account.

Parameters:

account_id (str)

Return type:

Account

async update_account(account_id, *, metadata=None, business_profile=None)

Update a Stripe Connect account.

Parameters:

• account_id (str)

• metadata (dict[str, str] | None)

• business_profile (dict[str, Any] | None)

Return type:

Account

async delete_account(account_id)

Delete a Stripe Connect account.

Parameters:

account_id (str)

Return type:

Account

async create_account_link(*, account_id, refresh_url, return_url, type)

Create a Stripe account onboarding or update link.

Parameters:

• account_id (str)

• refresh_url (str)

• return_url (str)

• type (AccountLinkType | str)

Return type:

AccountLink

async list_accounts(*, limit=25, starting_after=None)

List Stripe Connect accounts.

Parameters:

• limit (int)

• starting_after (str | None)

Return type:

StripeListResult

async create_transfer(*, amount, currency, destination, description=None, metadata=None, transfer_group=None)

Create a Stripe transfer to a connected account.

Parameters:

• amount (int)

• currency (str)

• destination (str)

• description (str | None)

• metadata (dict[str, str] | None)

• transfer_group (str | None)

Return type:

Transfer

async retrieve_transfer(transfer_id)

Retrieve a Stripe transfer.

Parameters:

transfer_id (str)

Return type:

Transfer

async list_transfers(*, limit=25, starting_after=None, destination=None, transfer_group=None)

List Stripe transfers.

Parameters:

• limit (int)

• starting_after (str | None)

• destination (str | None)

• transfer_group (str | None)

Return type:

StripeListResult

async create_payment_intent(*, amount, currency, customer_id=None, metadata=None, description=None, payment_method_types=None, capture_method=None, transfer_data=None, application_fee_amount=None, on_behalf_of=None)

Create a Stripe payment intent.

Parameters:

• amount (int)

• currency (str)

• customer_id (str | None)

• metadata (dict[str, str] | None)

• description (str | None)

• payment_method_types (list[str] | None)

• capture_method (CaptureMethod | str | None)

• transfer_data (dict[str, Any] | None)

• application_fee_amount (int | None)

• on_behalf_of (str | None)

Return type:

PaymentIntent

async retrieve_payment_intent(payment_intent_id, *, expand=None)

Retrieve a Stripe payment intent.

Parameters:

• payment_intent_id (str)

• expand (list[str] | None)

Return type:

PaymentIntent

async confirm_payment_intent(payment_intent_id, *, payment_method=None)

Confirm a Stripe payment intent.

Parameters:

• payment_intent_id (str)

• payment_method (str | None)

Return type:

PaymentIntent

async capture_payment_intent(payment_intent_id, *, amount_to_capture=None)

Capture an authorized Stripe payment intent.

Parameters:

• payment_intent_id (str)

• amount_to_capture (int | None)

Return type:

PaymentIntent

async cancel_payment_intent(payment_intent_id, *, cancellation_reason=None)

Cancel a Stripe payment intent.

Parameters:

• payment_intent_id (str)

• cancellation_reason (CancellationReason | str | None)

Return type:

PaymentIntent

async list_payment_intents(*, limit=25, starting_after=None, customer_id=None)

List Stripe payment intents.

Parameters:

• limit (int)

• starting_after (str | None)

• customer_id (str | None)

Return type:

StripeListResult

async create_refund(*, payment_intent_id=None, charge_id=None, amount=None, reason=None, metadata=None, reverse_transfer=None, refund_application_fee=None)

Create a Stripe refund.

Parameters:

• payment_intent_id (str | None)

• charge_id (str | None)

• amount (int | None)

• reason (RefundReason | str | None)

• metadata (dict[str, str] | None)

• reverse_transfer (bool | None)

• refund_application_fee (bool | None)

Return type:

Refund

async retrieve_refund(refund_id)

Retrieve a Stripe refund.

Parameters:

refund_id (str)

Return type:

Refund

async list_refunds(*, limit=25, starting_after=None, payment_intent_id=None, charge_id=None)

List Stripe refunds.

Parameters:

• limit (int)

• starting_after (str | None)

• payment_intent_id (str | None)

• charge_id (str | None)

Return type:

StripeListResult

async create_payout(*, amount, currency, description=None, metadata=None, destination=None, method=None, stripe_account=None)

Create a Stripe payout.

Parameters:

• amount (int)

• currency (str)

• description (str | None)

• metadata (dict[str, str] | None)

• destination (str | None)

• method (PayoutMethod | str | None)

• stripe_account (str | None)

Return type:

Payout

async retrieve_payout(payout_id, *, stripe_account=None)

Retrieve a Stripe payout.

Parameters:

• payout_id (str)

• stripe_account (str | None)

Return type:

Payout

async cancel_payout(payout_id, *, stripe_account=None)

Cancel a pending Stripe payout.

Parameters:

• payout_id (str)

• stripe_account (str | None)

Return type:

Payout

async list_payouts(*, limit=25, starting_after=None, stripe_account=None)

List Stripe payouts.

Parameters:

• limit (int)

• starting_after (str | None)

• stripe_account (str | None)

Return type:

StripeListResult

async retrieve_balance(*, stripe_account=None)

Retrieve Stripe account balance.

Parameters:

stripe_account (str | None)

Return type:

Balance

async verify_webhook_event(*, payload, signature, webhook_secret=None)

Verify and parse a Stripe webhook payload.

Parameters:

• payload (bytes)

• signature (str)

• webhook_secret (str | None)

Return type:

WebhookEvent

class derp.payments.PaymentsConfig

Bases: _StrictModel

Payments configuration.

api_key: str

webhook_secret: str | None

max_network_retries: int

timeout_seconds: float

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exception derp.payments.PaymentsError

Bases: Exception

Base exception for all payments errors.

__init__(message, code=None)

Parameters:

• message (str)

• code (str | None)

exception derp.payments.PaymentsProviderError

Bases: PaymentsError

Raised when Stripe returns an error.

__init__(message='Payments provider request failed', code=None)

Parameters:

• message (str)

• code (str | None)

exception derp.payments.PaymentsNotConnectedError

Bases: PaymentsError

Raised when payments client is used before connect().

__init__(message='Payments not connected. Call connect() first.')

Parameters:

message (str)

exception derp.payments.WebhookSignatureError

Bases: PaymentsError

Raised when webhook verification fails.

__init__(message='Invalid webhook signature')

Parameters:

message (str)

class derp.payments.AccountType

Bases: StrEnum

Stripe Connect account type.

STANDARD = 'standard'

EXPRESS = 'express'

CUSTOM = 'custom'

__new__(value)

class derp.payments.AccountLinkType

Bases: StrEnum

Stripe account link type.

ACCOUNT_ONBOARDING = 'account_onboarding'

ACCOUNT_UPDATE = 'account_update'

__new__(value)

class derp.payments.CaptureMethod

Bases: StrEnum

Payment intent capture method.

AUTOMATIC = 'automatic'

AUTOMATIC_ASYNC = 'automatic_async'

MANUAL = 'manual'

__new__(value)

class derp.payments.CancellationReason

Bases: StrEnum

Payment intent cancellation reason.

DUPLICATE = 'duplicate'

FRAUDULENT = 'fraudulent'

REQUESTED_BY_CUSTOMER = 'requested_by_customer'

ABANDONED = 'abandoned'

__new__(value)

class derp.payments.RefundReason

Bases: StrEnum

Refund reason.

DUPLICATE = 'duplicate'

FRAUDULENT = 'fraudulent'

REQUESTED_BY_CUSTOMER = 'requested_by_customer'

__new__(value)

class derp.payments.PayoutMethod

Bases: StrEnum

Payout method.

STANDARD = 'standard'

INSTANT = 'instant'

__new__(value)

class derp.payments.CheckoutSessionMode

Bases: StrEnum

Stripe checkout session mode.

PAYMENT = 'payment'

SUBSCRIPTION = 'subscription'

__new__(value)

class derp.payments.Customer

Bases: object

Normalized Stripe customer payload.

id: str

email: str | None

name: str | None

phone: str | None

metadata: dict[str, str]

created: int | None

raw: dict[str, Any]

__init__(id, email, name, phone, metadata, created, raw)

Parameters:

• id (str)

• email (str | None)

• name (str | None)

• phone (str | None)

• metadata (dict[str, str])

• created (int | None)

• raw (dict[str, Any])

Return type:

None

class derp.payments.CheckoutSession

Bases: object

Normalized Stripe checkout session payload.

id: str

url: str | None

mode: CheckoutSessionMode | None

customer_id: str | None

customer_email: str | None

payment_status: str | None

status: str | None

expires_at: int | None

raw: dict[str, Any]

__init__(id, url, mode, customer_id, customer_email, payment_status, status, expires_at, raw)

Parameters:

• id (str)

• url (str | None)

• mode (CheckoutSessionMode | None)

• customer_id (str | None)

• customer_email (str | None)

• payment_status (str | None)

• status (str | None)

• expires_at (int | None)

• raw (dict[str, Any])

Return type:

None

class derp.payments.StripeListResult

Bases: object

Paginated list of raw Stripe objects.

data: list[dict[str, Any]]

has_more: bool

__init__(data, has_more)

Parameters:

• data (list[dict[str, Any]])

• has_more (bool)

Return type:

None

class derp.payments.WebhookEvent

Bases: object

Normalized Stripe webhook event payload.

id: str

type: str

created: int

livemode: bool

data_object: dict[str, Any] | None

raw: dict[str, Any]

__init__(id, type, created, livemode, data_object, raw)

Parameters:

• id (str)

• type (str)

• created (int)

• livemode (bool)

• data_object (dict[str, Any] | None)

• raw (dict[str, Any])

Return type:

None

class derp.payments.Account

Bases: object

Normalized Stripe Connect account.

id: str

type: str | None

email: str | None

country: str | None

charges_enabled: bool

payouts_enabled: bool

details_submitted: bool

business_type: str | None

metadata: dict[str, str]

created: int | None

raw: dict[str, Any]

__init__(id, type, email, country, charges_enabled, payouts_enabled, details_submitted, business_type, metadata, created, raw)

Parameters:

• id (str)

• type (str | None)

• email (str | None)

• country (str | None)

• charges_enabled (bool)

• payouts_enabled (bool)

• details_submitted (bool)

• business_type (str | None)

• metadata (dict[str, str])

• created (int | None)

• raw (dict[str, Any])

Return type:

None

class derp.payments.AccountLink

Bases: object

Normalized Stripe account link.

url: str

created: int | None

expires_at: int | None

raw: dict[str, Any]

__init__(url, created, expires_at, raw)

Parameters:

• url (str)

• created (int | None)

• expires_at (int | None)

• raw (dict[str, Any])

Return type:

None

class derp.payments.Transfer

Bases: object

Normalized Stripe transfer.

id: str

amount: int

currency: str

destination: str | None

description: str | None

transfer_group: str | None

metadata: dict[str, str]

created: int | None

raw: dict[str, Any]

__init__(id, amount, currency, destination, description, transfer_group, metadata, created, raw)

Parameters:

• id (str)

• amount (int)

• currency (str)

• destination (str | None)

• description (str | None)

• transfer_group (str | None)

• metadata (dict[str, str])

• created (int | None)

• raw (dict[str, Any])

Return type:

None

class derp.payments.PaymentIntent

Bases: object

Normalized Stripe payment intent.

id: str

amount: int

currency: str

status: str | None

customer_id: str | None

description: str | None

capture_method: str | None

cancellation_reason: str | None

payment_method: str | None

metadata: dict[str, str]

created: int | None

raw: dict[str, Any]

__init__(id, amount, currency, status, customer_id, description, capture_method, cancellation_reason, payment_method, metadata, created, raw)

Parameters:

• id (str)

• amount (int)

• currency (str)

• status (str | None)

• customer_id (str | None)

• description (str | None)

• capture_method (str | None)

• cancellation_reason (str | None)

• payment_method (str | None)

• metadata (dict[str, str])

• created (int | None)

• raw (dict[str, Any])

Return type:

None

class derp.payments.Refund

Bases: object

Normalized Stripe refund.

id: str

amount: int

currency: str

status: str | None

payment_intent_id: str | None

charge_id: str | None

reason: str | None

metadata: dict[str, str]

created: int | None

raw: dict[str, Any]

__init__(id, amount, currency, status, payment_intent_id, charge_id, reason, metadata, created, raw)

Parameters:

• id (str)

• amount (int)

• currency (str)

• status (str | None)

• payment_intent_id (str | None)

• charge_id (str | None)

• reason (str | None)

• metadata (dict[str, str])

• created (int | None)

• raw (dict[str, Any])

Return type:

None

class derp.payments.Payout

Bases: object

Normalized Stripe payout.

id: str

amount: int

currency: str

status: str | None

method: str | None

description: str | None

destination: str | None

metadata: dict[str, str]

arrival_date: int | None

created: int | None

raw: dict[str, Any]

__init__(id, amount, currency, status, method, description, destination, metadata, arrival_date, created, raw)

Parameters:

• id (str)

• amount (int)

• currency (str)

• status (str | None)

• method (str | None)

• description (str | None)

• destination (str | None)

• metadata (dict[str, str])

• arrival_date (int | None)

• created (int | None)

• raw (dict[str, Any])

Return type:

None

class derp.payments.Balance

Bases: object

Normalized Stripe balance.

available: list[dict[str, Any]]

pending: list[dict[str, Any]]

connect_reserved: list[dict[str, Any]] | None

raw: dict[str, Any]

__init__(available, pending, connect_reserved, raw)

Parameters:

• available (list[dict[str, Any]])

• pending (list[dict[str, Any]])

• connect_reserved (list[dict[str, Any]] | None)

• raw (dict[str, Any])

Return type:

None