Billings reference

BillingClient

Bases: BaseClient

Source code in abacatepay/billings/client.py

class BillingClient(BaseClient):
    def create(self, data: Union[BillingIn | dict], **kwargs) -> Billing:
        """
        Create a new billing.

        Args:
            data (BillingIn): an instance of `abacatepay.billings.models.BillingIn` a dict \
            or the named params following the model schema.

        Keyword args:
            products (List[Product]): List of products to be billed.
            returnURL (str): The URL the user will be redirected to after the billing is completed.
            completionUrl (str): The URL the API will make a POST request after the billing is completed.
            methods (List[BILLING_METHODS]): The payment methods to be accepted. Defaults to ["PIX"].
            frequency (BILLING_KINDS): The frequency of the billing. Defaults to "ONE_TIME".
            customerId (str): The ID of the customer. If provided, the customer information won't be required.
            customer (CustomerMetadata): The customer information. If customerId is provided, this parameter is ignored.

        Returns:
            Billing: The response with the billing data.
        """
        json_data = prepare_data(data or kwargs, BillingIn)
        logger.debug('creating billing: %s', json_data)

        response = self._request(
            f"{BASE_URL}/billing/create",
            method="POST",
            json=json_data,
        )
        return Billing(**response.json()["data"])

    def list(self) -> BillingList:
        """
        List all bills.

        Returns:
            BillingList: A list of billing objects.
        """
        logger.debug(f"Listing bills with URL: {BASE_URL}/billing/list")
        response = self._request(f"{BASE_URL}/billing/list", method="GET")
        return BillingList.model_validate({'data': response.json()["data"]})

create(data, **kwargs)

Create a new billing.

Parameters:

Name	Type	Description	Default
data	BillingIn	an instance of abacatepay.billings.models.BillingIn a dict or the named params following the model schema.	required

Other Parameters:

Name	Type	Description
products	List[Product]	List of products to be billed.
returnURL	str	The URL the user will be redirected to after the billing is completed.
completionUrl	str	The URL the API will make a POST request after the billing is completed.
methods	List[BILLING_METHODS]	The payment methods to be accepted. Defaults to ["PIX"].
frequency	BILLING_KINDS	The frequency of the billing. Defaults to "ONE_TIME".
customerId	str	The ID of the customer. If provided, the customer information won't be required.
customer	CustomerMetadata	The customer information. If customerId is provided, this parameter is ignored.

Returns:

Name	Type	Description
Billing	Billing	The response with the billing data.

Source code in abacatepay/billings/client.py

def create(self, data: Union[BillingIn | dict], **kwargs) -> Billing:
    """
    Create a new billing.

    Args:
        data (BillingIn): an instance of `abacatepay.billings.models.BillingIn` a dict \
        or the named params following the model schema.

    Keyword args:
        products (List[Product]): List of products to be billed.
        returnURL (str): The URL the user will be redirected to after the billing is completed.
        completionUrl (str): The URL the API will make a POST request after the billing is completed.
        methods (List[BILLING_METHODS]): The payment methods to be accepted. Defaults to ["PIX"].
        frequency (BILLING_KINDS): The frequency of the billing. Defaults to "ONE_TIME".
        customerId (str): The ID of the customer. If provided, the customer information won't be required.
        customer (CustomerMetadata): The customer information. If customerId is provided, this parameter is ignored.

    Returns:
        Billing: The response with the billing data.
    """
    json_data = prepare_data(data or kwargs, BillingIn)
    logger.debug('creating billing: %s', json_data)

    response = self._request(
        f"{BASE_URL}/billing/create",
        method="POST",
        json=json_data,
    )
    return Billing(**response.json()["data"])

list()

List all bills.

Returns:

Name	Type	Description
BillingList	BillingList	A list of billing objects.

Source code in abacatepay/billings/client.py

def list(self) -> BillingList:
    """
    List all bills.

    Returns:
        BillingList: A list of billing objects.
    """
    logger.debug(f"Listing bills with URL: {BASE_URL}/billing/list")
    response = self._request(f"{BASE_URL}/billing/list", method="GET")
    return BillingList.model_validate({'data': response.json()["data"]})

Billing

Bases: BaseModel

Billing model

Parameters:

Name	Type	Description	Default
id	str	Unique identifier of the billing.	required
url	str	the URL which the user can complete the payment.	required
amount	int	the amount to be paid (in cents).	required
status	BILLING_STATUS	the current billing status.	required
dev_mode	bool	if it's operating in dev mode.	required
methods	List[BILLING_METHODS]	the allowed method to the billing.	required
products	List[ProductInline]	The list of products in the billing.	required
frequency	BILLING_KINDS	The billing frequency.	required
next_billing	Optional[AwareDatetime]	date and time of the next billing.	required
customer	Optional[CustomerInline]	the data of the customer that the billing belongs to.	required
created_at	AwareDatetime	The date and time when the billing was created.	required
updated_at	AwareDatetime	the date and time of the last billing update.	required
allow_cupons	bool	If the billing has allowed coupons or not.	required
coupons	List[Coupon]	the available coupons.	required
coupons_used	List[Coupon]	active coupons for this billing.	required
metadata	BillingMetadata	the billing metadata.	required

Source code in abacatepay/billings/models.py

class Billing(BaseModel):
    """Billing model

    Args:
        id (str): Unique identifier of the billing.
        url (str): the URL which the user can complete the payment.
        amount (int): the amount to be paid (in cents).
        status (BILLING_STATUS): the current billing status.
        dev_mode (bool): if it's operating in dev mode.
        methods (List[BILLING_METHODS]): the allowed method to the billing.
        products (List[ProductInline]): The list of products in the billing.
        frequency (BILLING_KINDS): The billing frequency.
        next_billing (Optional[AwareDatetime]): date and time of the next billing.
        customer (Optional[CustomerInline]): the data of the customer that the billing belongs to.
        created_at (AwareDatetime): The date and time when the billing was created.
        updated_at (AwareDatetime): the date and time of the last billing update.
        allow_cupons (bool): If the billing has allowed coupons or not.
        coupons (List[Coupon]): the available coupons.
        coupons_used (List[Coupon]): active coupons for this billing.
        metadata (BillingMetadata): the billing metadata.
    """
    id: str
    url: str
    amount: int
    status: BILLING_STATUS
    dev_mode: bool = Field(validation_alias='devMode')
    methods: List[BILLING_METHODS]
    products: List[ProductInline]
    frequency: BILLING_KINDS
    next_billing: Optional[AwareDatetime] = Field(
        None,
        validation_alias=AliasChoices('next_billing', 'nextBilling'),
        serialization_alias='nextBilling',
    )
    customer: Optional[CustomerInline] = None
    created_at: AwareDatetime = Field(validation_alias='createdAt')
    updated_at: AwareDatetime = Field(validation_alias='updatedAt')
    coupons: List[str]
    coupons_used: List[str] = Field(validation_alias='couponsUsed')
    metadata: BillingMetadata

BillingIn

Bases: BaseModel

Represents a billing model to creation

Parameters:

Name	Type	Description	Default
frequency	BILLING_KINDS	The billing frequency. Defaults to ONE_TIME.	required
methods	List[BILLING_METHODS]	the allowed method to the billing. Defaults to ['PIX']	required
products	List[Product]	The list of products in the billing.	required
completion_url	HttpUrl	the redirect URL when the payment is completed.	required
return_url	HttpUrl	the redirect URL when the user clicks on the "back" button.	required
customer_id	Optional[CustomerID]	Unique identifier of the billing.	required
customer	CustomerMetadata	Your customer information. Defaults to {}.	required

Source code in abacatepay/billings/models.py

class BillingIn(BaseModel):
    """Represents a billing model to creation

    Args:
        frequency (BILLING_KINDS): The billing frequency. Defaults to `ONE_TIME`.
        methods (List[BILLING_METHODS]): the allowed method to the billing. Defaults to ['PIX']
        products (List[Product]): The list of products in the billing.
        completion_url (HttpUrl): the redirect URL when the payment is completed.
        return_url (HttpUrl): the redirect URL when the user clicks on the "back" button.
        customer_id (Optional[CustomerID]): Unique identifier of the billing.
        customer (CustomerMetadata): Your customer information. Defaults to {}.
    """
    frequency: BILLING_KINDS = 'ONE_TIME'
    methods: List[BILLING_METHODS] = ['PIX']
    products: List[Product]
    return_url: HttpUrl = Field(serialization_alias='returnUrl')
    completion_url: HttpUrl = Field(serialization_alias='completionUrl')
    customer_id: Optional[CustomerID] = Field(None, serialization_alias='customerId')
    customer: CustomerMetadata | dict = {}

BillingList

Bases: BaseModel

Represents a list of Billings. It can be directly iterated and supports the usage of the len function.

Parameters:

Name	Type	Description	Default
data	List[Billing]	the list object having all the billings.	required

Source code in abacatepay/billings/models.py

class BillingList(BaseModel):
    """Represents a list of Billings. It can be directly iterated and
    supports the usage of the `len` function.

    Args:
        data (List[Billing]): the list object having all the billings.
    """
    data: List[Billing]

    def __len__(self) -> int:
        return len(self.data)

    def __iter__(self) -> Iterator[Billing]:
        return self.data.__iter__()

BillingMetadata

Bases: BaseModel

model of a billing metadata

Parameters:

Name	Type	Description	Default
completion_url	str	the redirect URL when the payment is completed.	required
return_url	str	the redirect URL when the user clicks on the "back" button.	required
fee	int	the billing fee.	required

Source code in abacatepay/billings/models.py

class BillingMetadata(BaseModel):
    """model of a billing metadata

    Args:
        completion_url (str): the redirect URL when the payment is completed.
        return_url (str): the redirect URL when the user clicks on the "back" button.
        fee (int): the billing fee.
    """
    completion_url: str = Field(
        validation_alias=AliasChoices('completion_url', 'completionUrl'),
        serialization_alias='completionUrl',
    )
    return_url: str = Field(
        validation_alias=AliasChoices('return_url', 'returnUrl'),
        serialization_alias='returnUrl',
    )
    fee: int