# This file was auto-generated by Fern from our API Definition.

import typing
from ..core.client_wrapper import SyncClientWrapper
from .raw_client import RawPaymentsClient
from ..types.list_payments_request_sort_field import ListPaymentsRequestSortField
from ..core.request_options import RequestOptions
from ..core.pagination import SyncPager
from ..types.payment import Payment
from ..types.list_payments_response import ListPaymentsResponse
from ..core.unchecked_base_model import construct_type
from json.decoder import JSONDecodeError
from ..core.api_error import ApiError
from ..requests.money import MoneyParams
from ..requests.address import AddressParams
from ..requests.cash_payment_details import CashPaymentDetailsParams
from ..requests.external_payment_details import ExternalPaymentDetailsParams
from ..requests.customer_details import CustomerDetailsParams
from ..requests.offline_payment_details import OfflinePaymentDetailsParams
from ..types.create_payment_response import CreatePaymentResponse
from ..types.cancel_payment_by_idempotency_key_response import CancelPaymentByIdempotencyKeyResponse
from ..types.get_payment_response import GetPaymentResponse
from ..requests.payment import PaymentParams
from ..types.update_payment_response import UpdatePaymentResponse
from ..types.cancel_payment_response import CancelPaymentResponse
from ..types.complete_payment_response import CompletePaymentResponse
from ..core.client_wrapper import AsyncClientWrapper
from .raw_client import AsyncRawPaymentsClient
from ..core.pagination import AsyncPager

# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class PaymentsClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawPaymentsClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> RawPaymentsClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawPaymentsClient
        """
        return self._raw_client

    def list(
        self,
        *,
        begin_time: typing.Optional[str] = None,
        end_time: typing.Optional[str] = None,
        sort_order: typing.Optional[str] = None,
        cursor: typing.Optional[str] = None,
        location_id: typing.Optional[str] = None,
        total: typing.Optional[int] = None,
        last4: typing.Optional[str] = None,
        card_brand: typing.Optional[str] = None,
        limit: typing.Optional[int] = None,
        is_offline_payment: typing.Optional[bool] = None,
        offline_begin_time: typing.Optional[str] = None,
        offline_end_time: typing.Optional[str] = None,
        updated_at_begin_time: typing.Optional[str] = None,
        updated_at_end_time: typing.Optional[str] = None,
        sort_field: typing.Optional[ListPaymentsRequestSortField] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SyncPager[Payment]:
        """
        Retrieves a list of payments taken by the account making the request.

        Results are eventually consistent, and new payments or changes to payments might take several
        seconds to appear.

        The maximum results per page is 100.

        Parameters
        ----------
        begin_time : typing.Optional[str]
            Indicates the start of the time range to retrieve payments for, in RFC 3339 format.
            The range is determined using the `created_at` field for each Payment.
            Inclusive. Default: The current time minus one year.

        end_time : typing.Optional[str]
            Indicates the end of the time range to retrieve payments for, in RFC 3339 format.  The
            range is determined using the `created_at` field for each Payment.

            Default: The current time.

        sort_order : typing.Optional[str]
            The order in which results are listed by `ListPaymentsRequest.sort_field`:
            - `ASC` - Oldest to newest.
            - `DESC` - Newest to oldest (default).

        cursor : typing.Optional[str]
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the original query.

            For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

        location_id : typing.Optional[str]
            Limit results to the location supplied. By default, results are returned
            for the default (main) location associated with the seller.

        total : typing.Optional[int]
            The exact amount in the `total_money` for a payment.

        last4 : typing.Optional[str]
            The last four digits of a payment card.

        card_brand : typing.Optional[str]
            The brand of the payment card (for example, VISA).

        limit : typing.Optional[int]
            The maximum number of results to be returned in a single page.
            It is possible to receive fewer results than the specified limit on a given page.

            The default value of 100 is also the maximum allowed value. If the provided value is
            greater than 100, it is ignored and the default value is used instead.

            Default: `100`

        is_offline_payment : typing.Optional[bool]
            Whether the payment was taken offline or not.

        offline_begin_time : typing.Optional[str]
            Indicates the start of the time range for which to retrieve offline payments, in RFC 3339
            format for timestamps. The range is determined using the
            `offline_payment_details.client_created_at` field for each Payment. If set, payments without a
            value set in `offline_payment_details.client_created_at` will not be returned.

            Default: The current time.

        offline_end_time : typing.Optional[str]
            Indicates the end of the time range for which to retrieve offline payments, in RFC 3339
            format for timestamps. The range is determined using the
            `offline_payment_details.client_created_at` field for each Payment. If set, payments without a
            value set in `offline_payment_details.client_created_at` will not be returned.

            Default: The current time.

        updated_at_begin_time : typing.Optional[str]
            Indicates the start of the time range to retrieve payments for, in RFC 3339 format.  The
            range is determined using the `updated_at` field for each Payment.

        updated_at_end_time : typing.Optional[str]
            Indicates the end of the time range to retrieve payments for, in RFC 3339 format.  The
            range is determined using the `updated_at` field for each Payment.

        sort_field : typing.Optional[ListPaymentsRequestSortField]
            The field used to sort results by. The default is `CREATED_AT`.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SyncPager[Payment]
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        response = client.payments.list()
        for item in response:
            yield item
        # alternatively, you can paginate page-by-page
        for page in response.iter_pages():
            yield page
        """
        _response = self._raw_client._client_wrapper.httpx_client.request(
            "v2/payments",
            method="GET",
            params={
                "begin_time": begin_time,
                "end_time": end_time,
                "sort_order": sort_order,
                "cursor": cursor,
                "location_id": location_id,
                "total": total,
                "last_4": last4,
                "card_brand": card_brand,
                "limit": limit,
                "is_offline_payment": is_offline_payment,
                "offline_begin_time": offline_begin_time,
                "offline_end_time": offline_end_time,
                "updated_at_begin_time": updated_at_begin_time,
                "updated_at_end_time": updated_at_end_time,
                "sort_field": sort_field,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _parsed_response = typing.cast(
                    ListPaymentsResponse,
                    construct_type(
                        type_=ListPaymentsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                _parsed_next = _parsed_response.cursor
                _has_next = _parsed_next is not None and _parsed_next != ""
                _get_next = lambda: self.list(
                    begin_time=begin_time,
                    end_time=end_time,
                    sort_order=sort_order,
                    cursor=_parsed_next,
                    location_id=location_id,
                    total=total,
                    last4=last4,
                    card_brand=card_brand,
                    limit=limit,
                    is_offline_payment=is_offline_payment,
                    offline_begin_time=offline_begin_time,
                    offline_end_time=offline_end_time,
                    updated_at_begin_time=updated_at_begin_time,
                    updated_at_end_time=updated_at_end_time,
                    sort_field=sort_field,
                    request_options=request_options,
                )
                _items = _parsed_response.payments
                return SyncPager(has_next=_has_next, items=_items, get_next=_get_next)
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    def create(
        self,
        *,
        source_id: str,
        idempotency_key: str,
        amount_money: typing.Optional[MoneyParams] = OMIT,
        tip_money: typing.Optional[MoneyParams] = OMIT,
        app_fee_money: typing.Optional[MoneyParams] = OMIT,
        delay_duration: typing.Optional[str] = OMIT,
        delay_action: typing.Optional[str] = OMIT,
        autocomplete: typing.Optional[bool] = OMIT,
        order_id: typing.Optional[str] = OMIT,
        customer_id: typing.Optional[str] = OMIT,
        location_id: typing.Optional[str] = OMIT,
        team_member_id: typing.Optional[str] = OMIT,
        reference_id: typing.Optional[str] = OMIT,
        verification_token: typing.Optional[str] = OMIT,
        accept_partial_authorization: typing.Optional[bool] = OMIT,
        buyer_email_address: typing.Optional[str] = OMIT,
        buyer_phone_number: typing.Optional[str] = OMIT,
        billing_address: typing.Optional[AddressParams] = OMIT,
        shipping_address: typing.Optional[AddressParams] = OMIT,
        note: typing.Optional[str] = OMIT,
        statement_description_identifier: typing.Optional[str] = OMIT,
        cash_details: typing.Optional[CashPaymentDetailsParams] = OMIT,
        external_details: typing.Optional[ExternalPaymentDetailsParams] = OMIT,
        customer_details: typing.Optional[CustomerDetailsParams] = OMIT,
        offline_payment_details: typing.Optional[OfflinePaymentDetailsParams] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> CreatePaymentResponse:
        """
        Creates a payment using the provided source. You can use this endpoint
        to charge a card (credit/debit card or
        Square gift card) or record a payment that the seller received outside of Square
        (cash payment from a buyer or a payment that an external entity
        processed on behalf of the seller).

        The endpoint creates a
        `Payment` object and returns it in the response.

        Parameters
        ----------
        source_id : str
            The ID for the source of funds for this payment.
            This could be a payment token generated by the Web Payments SDK for any of its
            [supported methods](https://developer.squareup.com/docs/web-payments/overview#explore-payment-methods),
            including cards, bank transfers, Afterpay or Cash App Pay. If recording a payment
            that the seller received outside of Square, specify either "CASH" or "EXTERNAL".
            For more information, see
            [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).

        idempotency_key : str
            A unique string that identifies this `CreatePayment` request. Keys can be any valid string
            but must be unique for every `CreatePayment` request.

            Note: The number of allowed characters might be less than the stated maximum, if multi-byte
            characters are used.

            For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).

        amount_money : typing.Optional[MoneyParams]
            The amount of money to accept for this payment, not including `tip_money`.

            The amount must be specified in the smallest denomination of the applicable currency
            (for example, US dollar amounts are specified in cents). For more information, see
            [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).

            The currency code must match the currency associated with the business
            that is accepting the payment.

        tip_money : typing.Optional[MoneyParams]
            The amount designated as a tip, in addition to `amount_money`.

            The amount must be specified in the smallest denomination of the applicable currency
            (for example, US dollar amounts are specified in cents). For more information, see
            [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).

            The currency code must match the currency associated with the business
            that is accepting the payment.

        app_fee_money : typing.Optional[MoneyParams]
            The amount of money that the developer is taking as a fee
            for facilitating the payment on behalf of the seller.

            The amount cannot be more than 90% of the total amount of the payment.

            The amount must be specified in the smallest denomination of the applicable currency
            (for example, US dollar amounts are specified in cents). For more information, see
            [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).

            The fee currency code must match the currency associated with the seller
            that is accepting the payment. The application must be from a developer
            account in the same country and using the same currency code as the seller.

            For more information about the application fee scenario, see
            [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).

            To set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required.
            For more information, see [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).

        delay_duration : typing.Optional[str]
            The duration of time after the payment's creation when Square automatically
            either completes or cancels the payment depending on the `delay_action` field value.
            For more information, see
            [Time threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).

            This parameter should be specified as a time duration, in RFC 3339 format.

            Note: This feature is only supported for card payments. This parameter can only be set for a delayed
            capture payment (`autocomplete=false`).

            Default:

            - Card-present payments: "PT36H" (36 hours) from the creation time.
            - Card-not-present payments: "P7D" (7 days) from the creation time.

        delay_action : typing.Optional[str]
            The action to be applied to the payment when the `delay_duration` has elapsed. The action must be
            CANCEL or COMPLETE. For more information, see
            [Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).

            Default: CANCEL

        autocomplete : typing.Optional[bool]
            If set to `true`, this payment will be completed when possible. If
            set to `false`, this payment is held in an approved state until either
            explicitly completed (captured) or canceled (voided). For more information, see
            [Delayed capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment).

            Default: true

        order_id : typing.Optional[str]
            Associates a previously created order with this payment.

        customer_id : typing.Optional[str]
            The [Customer](entity:Customer) ID of the customer associated with the payment.

            This is required if the `source_id` refers to a card on file created using the Cards API.

        location_id : typing.Optional[str]
            The location ID to associate with the payment. If not specified, the [main location](https://developer.squareup.com/docs/locations-api#about-the-main-location) is
            used.

        team_member_id : typing.Optional[str]
            An optional [TeamMember](entity:TeamMember) ID to associate with
            this payment.

        reference_id : typing.Optional[str]
            A user-defined ID to associate with the payment.

            You can use this field to associate the payment to an entity in an external system
            (for example, you might specify an order ID that is generated by a third-party shopping cart).

        verification_token : typing.Optional[str]
            An identifying token generated by [payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer).
            Verification tokens encapsulate customer device information and 3-D Secure
            challenge results to indicate that Square has verified the buyer identity.

            For more information, see [SCA Overview](https://developer.squareup.com/docs/sca-overview).

        accept_partial_authorization : typing.Optional[bool]
            If set to `true` and charging a Square Gift Card, a payment might be returned with
            `amount_money` equal to less than what was requested. For example, a request for $20 when charging
            a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose
            to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card
            payment. This field cannot be `true` when `autocomplete = true`.

            For more information, see
            [Partial amount with Square Gift Cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card).

            Default: false

        buyer_email_address : typing.Optional[str]
            The buyer's email address.

        buyer_phone_number : typing.Optional[str]
            The buyer's phone number.
            Must follow the following format:
            1. A leading + symbol (followed by a country code)
            2. The phone number can contain spaces and the special characters `(` , `)` , `-` , and `.`.
            Alphabetical characters aren't allowed.
            3. The phone number must contain between 9 and 16 digits.

        billing_address : typing.Optional[AddressParams]
            The buyer's billing address.

        shipping_address : typing.Optional[AddressParams]
            The buyer's shipping address.

        note : typing.Optional[str]
            An optional note to be entered by the developer when creating a payment.

        statement_description_identifier : typing.Optional[str]
            Optional additional payment information to include on the customer's card statement
            as part of the statement description. This can be, for example, an invoice number, ticket number,
            or short description that uniquely identifies the purchase.

            Note that the `statement_description_identifier` might get truncated on the statement description
            to fit the required information including the Square identifier (SQ *) and name of the
            seller taking the payment.

        cash_details : typing.Optional[CashPaymentDetailsParams]
            Additional details required when recording a cash payment (`source_id` is CASH).

        external_details : typing.Optional[ExternalPaymentDetailsParams]
            Additional details required when recording an external payment (`source_id` is EXTERNAL).

        customer_details : typing.Optional[CustomerDetailsParams]
            Details about the customer making the payment.

        offline_payment_details : typing.Optional[OfflinePaymentDetailsParams]
            An optional field for specifying the offline payment details. This is intended for
            internal 1st-party callers only.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CreatePaymentResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.payments.create(
            source_id="ccof:GaJGNaZa8x4OgDJn4GB",
            idempotency_key="7b0f3ec5-086a-4871-8f13-3c81b3875218",
            amount_money={"amount": 1000, "currency": "USD"},
            app_fee_money={"amount": 10, "currency": "USD"},
            autocomplete=True,
            customer_id="W92WH6P11H4Z77CTET0RNTGFW8",
            location_id="L88917AVBK2S5",
            reference_id="123456",
            note="Brief description",
        )
        """
        response = self._raw_client.create(
            source_id=source_id,
            idempotency_key=idempotency_key,
            amount_money=amount_money,
            tip_money=tip_money,
            app_fee_money=app_fee_money,
            delay_duration=delay_duration,
            delay_action=delay_action,
            autocomplete=autocomplete,
            order_id=order_id,
            customer_id=customer_id,
            location_id=location_id,
            team_member_id=team_member_id,
            reference_id=reference_id,
            verification_token=verification_token,
            accept_partial_authorization=accept_partial_authorization,
            buyer_email_address=buyer_email_address,
            buyer_phone_number=buyer_phone_number,
            billing_address=billing_address,
            shipping_address=shipping_address,
            note=note,
            statement_description_identifier=statement_description_identifier,
            cash_details=cash_details,
            external_details=external_details,
            customer_details=customer_details,
            offline_payment_details=offline_payment_details,
            request_options=request_options,
        )
        return response.data

    def cancel_by_idempotency_key(
        self, *, idempotency_key: str, request_options: typing.Optional[RequestOptions] = None
    ) -> CancelPaymentByIdempotencyKeyResponse:
        """
        Cancels (voids) a payment identified by the idempotency key that is specified in the
        request.

        Use this method when the status of a `CreatePayment` request is unknown (for example, after you send a
        `CreatePayment` request, a network error occurs and you do not get a response). In this case, you can
        direct Square to cancel the payment using this endpoint. In the request, you provide the same
        idempotency key that you provided in your `CreatePayment` request that you want to cancel. After
        canceling the payment, you can submit your `CreatePayment` request again.

        Note that if no payment with the specified idempotency key is found, no action is taken and the endpoint
        returns successfully.

        Parameters
        ----------
        idempotency_key : str
            The `idempotency_key` identifying the payment to be canceled.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CancelPaymentByIdempotencyKeyResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.payments.cancel_by_idempotency_key(
            idempotency_key="a7e36d40-d24b-11e8-b568-0800200c9a66",
        )
        """
        response = self._raw_client.cancel_by_idempotency_key(
            idempotency_key=idempotency_key, request_options=request_options
        )
        return response.data

    def get(self, payment_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> GetPaymentResponse:
        """
        Retrieves details for a specific payment.

        Parameters
        ----------
        payment_id : str
            A unique ID for the desired payment.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetPaymentResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.payments.get(
            payment_id="payment_id",
        )
        """
        response = self._raw_client.get(payment_id, request_options=request_options)
        return response.data

    def update(
        self,
        payment_id: str,
        *,
        idempotency_key: str,
        payment: typing.Optional[PaymentParams] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UpdatePaymentResponse:
        """
        Updates a payment with the APPROVED status.
        You can update the `amount_money` and `tip_money` using this endpoint.

        Parameters
        ----------
        payment_id : str
            The ID of the payment to update.

        idempotency_key : str
            A unique string that identifies this `UpdatePayment` request. Keys can be any valid string
            but must be unique for every `UpdatePayment` request.

            For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).

        payment : typing.Optional[PaymentParams]
            The updated `Payment` object.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdatePaymentResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.payments.update(
            payment_id="payment_id",
            payment={
                "amount_money": {"amount": 1000, "currency": "USD"},
                "tip_money": {"amount": 100, "currency": "USD"},
                "version_token": "ODhwVQ35xwlzRuoZEwKXucfu7583sPTzK48c5zoGd0g6o",
            },
            idempotency_key="956f8b13-e4ec-45d6-85e8-d1d95ef0c5de",
        )
        """
        response = self._raw_client.update(
            payment_id, idempotency_key=idempotency_key, payment=payment, request_options=request_options
        )
        return response.data

    def cancel(
        self, payment_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> CancelPaymentResponse:
        """
        Cancels (voids) a payment. You can use this endpoint to cancel a payment with
        the APPROVED `status`.

        Parameters
        ----------
        payment_id : str
            The ID of the payment to cancel.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CancelPaymentResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.payments.cancel(
            payment_id="payment_id",
        )
        """
        response = self._raw_client.cancel(payment_id, request_options=request_options)
        return response.data

    def complete(
        self,
        payment_id: str,
        *,
        version_token: typing.Optional[str] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> CompletePaymentResponse:
        """
        Completes (captures) a payment.
        By default, payments are set to complete immediately after they are created.

        You can use this endpoint to complete a payment with the APPROVED `status`.

        Parameters
        ----------
        payment_id : str
            The unique ID identifying the payment to be completed.

        version_token : typing.Optional[str]
            Used for optimistic concurrency. This opaque token identifies the current `Payment`
            version that the caller expects. If the server has a different version of the Payment,
            the update fails and a response with a VERSION_MISMATCH error is returned.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CompletePaymentResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.payments.complete(
            payment_id="payment_id",
        )
        """
        response = self._raw_client.complete(payment_id, version_token=version_token, request_options=request_options)
        return response.data


class AsyncPaymentsClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawPaymentsClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> AsyncRawPaymentsClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawPaymentsClient
        """
        return self._raw_client

    async def list(
        self,
        *,
        begin_time: typing.Optional[str] = None,
        end_time: typing.Optional[str] = None,
        sort_order: typing.Optional[str] = None,
        cursor: typing.Optional[str] = None,
        location_id: typing.Optional[str] = None,
        total: typing.Optional[int] = None,
        last4: typing.Optional[str] = None,
        card_brand: typing.Optional[str] = None,
        limit: typing.Optional[int] = None,
        is_offline_payment: typing.Optional[bool] = None,
        offline_begin_time: typing.Optional[str] = None,
        offline_end_time: typing.Optional[str] = None,
        updated_at_begin_time: typing.Optional[str] = None,
        updated_at_end_time: typing.Optional[str] = None,
        sort_field: typing.Optional[ListPaymentsRequestSortField] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> AsyncPager[Payment]:
        """
        Retrieves a list of payments taken by the account making the request.

        Results are eventually consistent, and new payments or changes to payments might take several
        seconds to appear.

        The maximum results per page is 100.

        Parameters
        ----------
        begin_time : typing.Optional[str]
            Indicates the start of the time range to retrieve payments for, in RFC 3339 format.
            The range is determined using the `created_at` field for each Payment.
            Inclusive. Default: The current time minus one year.

        end_time : typing.Optional[str]
            Indicates the end of the time range to retrieve payments for, in RFC 3339 format.  The
            range is determined using the `created_at` field for each Payment.

            Default: The current time.

        sort_order : typing.Optional[str]
            The order in which results are listed by `ListPaymentsRequest.sort_field`:
            - `ASC` - Oldest to newest.
            - `DESC` - Newest to oldest (default).

        cursor : typing.Optional[str]
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the original query.

            For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

        location_id : typing.Optional[str]
            Limit results to the location supplied. By default, results are returned
            for the default (main) location associated with the seller.

        total : typing.Optional[int]
            The exact amount in the `total_money` for a payment.

        last4 : typing.Optional[str]
            The last four digits of a payment card.

        card_brand : typing.Optional[str]
            The brand of the payment card (for example, VISA).

        limit : typing.Optional[int]
            The maximum number of results to be returned in a single page.
            It is possible to receive fewer results than the specified limit on a given page.

            The default value of 100 is also the maximum allowed value. If the provided value is
            greater than 100, it is ignored and the default value is used instead.

            Default: `100`

        is_offline_payment : typing.Optional[bool]
            Whether the payment was taken offline or not.

        offline_begin_time : typing.Optional[str]
            Indicates the start of the time range for which to retrieve offline payments, in RFC 3339
            format for timestamps. The range is determined using the
            `offline_payment_details.client_created_at` field for each Payment. If set, payments without a
            value set in `offline_payment_details.client_created_at` will not be returned.

            Default: The current time.

        offline_end_time : typing.Optional[str]
            Indicates the end of the time range for which to retrieve offline payments, in RFC 3339
            format for timestamps. The range is determined using the
            `offline_payment_details.client_created_at` field for each Payment. If set, payments without a
            value set in `offline_payment_details.client_created_at` will not be returned.

            Default: The current time.

        updated_at_begin_time : typing.Optional[str]
            Indicates the start of the time range to retrieve payments for, in RFC 3339 format.  The
            range is determined using the `updated_at` field for each Payment.

        updated_at_end_time : typing.Optional[str]
            Indicates the end of the time range to retrieve payments for, in RFC 3339 format.  The
            range is determined using the `updated_at` field for each Payment.

        sort_field : typing.Optional[ListPaymentsRequestSortField]
            The field used to sort results by. The default is `CREATED_AT`.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        AsyncPager[Payment]
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            response = await client.payments.list()
            async for item in response:
                yield item
            # alternatively, you can paginate page-by-page
            async for page in response.iter_pages():
                yield page


        asyncio.run(main())
        """
        _response = await self._raw_client._client_wrapper.httpx_client.request(
            "v2/payments",
            method="GET",
            params={
                "begin_time": begin_time,
                "end_time": end_time,
                "sort_order": sort_order,
                "cursor": cursor,
                "location_id": location_id,
                "total": total,
                "last_4": last4,
                "card_brand": card_brand,
                "limit": limit,
                "is_offline_payment": is_offline_payment,
                "offline_begin_time": offline_begin_time,
                "offline_end_time": offline_end_time,
                "updated_at_begin_time": updated_at_begin_time,
                "updated_at_end_time": updated_at_end_time,
                "sort_field": sort_field,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _parsed_response = typing.cast(
                    ListPaymentsResponse,
                    construct_type(
                        type_=ListPaymentsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                _parsed_next = _parsed_response.cursor
                _has_next = _parsed_next is not None and _parsed_next != ""
                _get_next = lambda: self.list(
                    begin_time=begin_time,
                    end_time=end_time,
                    sort_order=sort_order,
                    cursor=_parsed_next,
                    location_id=location_id,
                    total=total,
                    last4=last4,
                    card_brand=card_brand,
                    limit=limit,
                    is_offline_payment=is_offline_payment,
                    offline_begin_time=offline_begin_time,
                    offline_end_time=offline_end_time,
                    updated_at_begin_time=updated_at_begin_time,
                    updated_at_end_time=updated_at_end_time,
                    sort_field=sort_field,
                    request_options=request_options,
                )
                _items = _parsed_response.payments
                return AsyncPager(has_next=_has_next, items=_items, get_next=_get_next)
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    async def create(
        self,
        *,
        source_id: str,
        idempotency_key: str,
        amount_money: typing.Optional[MoneyParams] = OMIT,
        tip_money: typing.Optional[MoneyParams] = OMIT,
        app_fee_money: typing.Optional[MoneyParams] = OMIT,
        delay_duration: typing.Optional[str] = OMIT,
        delay_action: typing.Optional[str] = OMIT,
        autocomplete: typing.Optional[bool] = OMIT,
        order_id: typing.Optional[str] = OMIT,
        customer_id: typing.Optional[str] = OMIT,
        location_id: typing.Optional[str] = OMIT,
        team_member_id: typing.Optional[str] = OMIT,
        reference_id: typing.Optional[str] = OMIT,
        verification_token: typing.Optional[str] = OMIT,
        accept_partial_authorization: typing.Optional[bool] = OMIT,
        buyer_email_address: typing.Optional[str] = OMIT,
        buyer_phone_number: typing.Optional[str] = OMIT,
        billing_address: typing.Optional[AddressParams] = OMIT,
        shipping_address: typing.Optional[AddressParams] = OMIT,
        note: typing.Optional[str] = OMIT,
        statement_description_identifier: typing.Optional[str] = OMIT,
        cash_details: typing.Optional[CashPaymentDetailsParams] = OMIT,
        external_details: typing.Optional[ExternalPaymentDetailsParams] = OMIT,
        customer_details: typing.Optional[CustomerDetailsParams] = OMIT,
        offline_payment_details: typing.Optional[OfflinePaymentDetailsParams] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> CreatePaymentResponse:
        """
        Creates a payment using the provided source. You can use this endpoint
        to charge a card (credit/debit card or
        Square gift card) or record a payment that the seller received outside of Square
        (cash payment from a buyer or a payment that an external entity
        processed on behalf of the seller).

        The endpoint creates a
        `Payment` object and returns it in the response.

        Parameters
        ----------
        source_id : str
            The ID for the source of funds for this payment.
            This could be a payment token generated by the Web Payments SDK for any of its
            [supported methods](https://developer.squareup.com/docs/web-payments/overview#explore-payment-methods),
            including cards, bank transfers, Afterpay or Cash App Pay. If recording a payment
            that the seller received outside of Square, specify either "CASH" or "EXTERNAL".
            For more information, see
            [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).

        idempotency_key : str
            A unique string that identifies this `CreatePayment` request. Keys can be any valid string
            but must be unique for every `CreatePayment` request.

            Note: The number of allowed characters might be less than the stated maximum, if multi-byte
            characters are used.

            For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).

        amount_money : typing.Optional[MoneyParams]
            The amount of money to accept for this payment, not including `tip_money`.

            The amount must be specified in the smallest denomination of the applicable currency
            (for example, US dollar amounts are specified in cents). For more information, see
            [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).

            The currency code must match the currency associated with the business
            that is accepting the payment.

        tip_money : typing.Optional[MoneyParams]
            The amount designated as a tip, in addition to `amount_money`.

            The amount must be specified in the smallest denomination of the applicable currency
            (for example, US dollar amounts are specified in cents). For more information, see
            [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).

            The currency code must match the currency associated with the business
            that is accepting the payment.

        app_fee_money : typing.Optional[MoneyParams]
            The amount of money that the developer is taking as a fee
            for facilitating the payment on behalf of the seller.

            The amount cannot be more than 90% of the total amount of the payment.

            The amount must be specified in the smallest denomination of the applicable currency
            (for example, US dollar amounts are specified in cents). For more information, see
            [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).

            The fee currency code must match the currency associated with the seller
            that is accepting the payment. The application must be from a developer
            account in the same country and using the same currency code as the seller.

            For more information about the application fee scenario, see
            [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).

            To set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required.
            For more information, see [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).

        delay_duration : typing.Optional[str]
            The duration of time after the payment's creation when Square automatically
            either completes or cancels the payment depending on the `delay_action` field value.
            For more information, see
            [Time threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).

            This parameter should be specified as a time duration, in RFC 3339 format.

            Note: This feature is only supported for card payments. This parameter can only be set for a delayed
            capture payment (`autocomplete=false`).

            Default:

            - Card-present payments: "PT36H" (36 hours) from the creation time.
            - Card-not-present payments: "P7D" (7 days) from the creation time.

        delay_action : typing.Optional[str]
            The action to be applied to the payment when the `delay_duration` has elapsed. The action must be
            CANCEL or COMPLETE. For more information, see
            [Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).

            Default: CANCEL

        autocomplete : typing.Optional[bool]
            If set to `true`, this payment will be completed when possible. If
            set to `false`, this payment is held in an approved state until either
            explicitly completed (captured) or canceled (voided). For more information, see
            [Delayed capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment).

            Default: true

        order_id : typing.Optional[str]
            Associates a previously created order with this payment.

        customer_id : typing.Optional[str]
            The [Customer](entity:Customer) ID of the customer associated with the payment.

            This is required if the `source_id` refers to a card on file created using the Cards API.

        location_id : typing.Optional[str]
            The location ID to associate with the payment. If not specified, the [main location](https://developer.squareup.com/docs/locations-api#about-the-main-location) is
            used.

        team_member_id : typing.Optional[str]
            An optional [TeamMember](entity:TeamMember) ID to associate with
            this payment.

        reference_id : typing.Optional[str]
            A user-defined ID to associate with the payment.

            You can use this field to associate the payment to an entity in an external system
            (for example, you might specify an order ID that is generated by a third-party shopping cart).

        verification_token : typing.Optional[str]
            An identifying token generated by [payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer).
            Verification tokens encapsulate customer device information and 3-D Secure
            challenge results to indicate that Square has verified the buyer identity.

            For more information, see [SCA Overview](https://developer.squareup.com/docs/sca-overview).

        accept_partial_authorization : typing.Optional[bool]
            If set to `true` and charging a Square Gift Card, a payment might be returned with
            `amount_money` equal to less than what was requested. For example, a request for $20 when charging
            a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose
            to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card
            payment. This field cannot be `true` when `autocomplete = true`.

            For more information, see
            [Partial amount with Square Gift Cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card).

            Default: false

        buyer_email_address : typing.Optional[str]
            The buyer's email address.

        buyer_phone_number : typing.Optional[str]
            The buyer's phone number.
            Must follow the following format:
            1. A leading + symbol (followed by a country code)
            2. The phone number can contain spaces and the special characters `(` , `)` , `-` , and `.`.
            Alphabetical characters aren't allowed.
            3. The phone number must contain between 9 and 16 digits.

        billing_address : typing.Optional[AddressParams]
            The buyer's billing address.

        shipping_address : typing.Optional[AddressParams]
            The buyer's shipping address.

        note : typing.Optional[str]
            An optional note to be entered by the developer when creating a payment.

        statement_description_identifier : typing.Optional[str]
            Optional additional payment information to include on the customer's card statement
            as part of the statement description. This can be, for example, an invoice number, ticket number,
            or short description that uniquely identifies the purchase.

            Note that the `statement_description_identifier` might get truncated on the statement description
            to fit the required information including the Square identifier (SQ *) and name of the
            seller taking the payment.

        cash_details : typing.Optional[CashPaymentDetailsParams]
            Additional details required when recording a cash payment (`source_id` is CASH).

        external_details : typing.Optional[ExternalPaymentDetailsParams]
            Additional details required when recording an external payment (`source_id` is EXTERNAL).

        customer_details : typing.Optional[CustomerDetailsParams]
            Details about the customer making the payment.

        offline_payment_details : typing.Optional[OfflinePaymentDetailsParams]
            An optional field for specifying the offline payment details. This is intended for
            internal 1st-party callers only.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CreatePaymentResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.payments.create(
                source_id="ccof:GaJGNaZa8x4OgDJn4GB",
                idempotency_key="7b0f3ec5-086a-4871-8f13-3c81b3875218",
                amount_money={"amount": 1000, "currency": "USD"},
                app_fee_money={"amount": 10, "currency": "USD"},
                autocomplete=True,
                customer_id="W92WH6P11H4Z77CTET0RNTGFW8",
                location_id="L88917AVBK2S5",
                reference_id="123456",
                note="Brief description",
            )


        asyncio.run(main())
        """
        response = await self._raw_client.create(
            source_id=source_id,
            idempotency_key=idempotency_key,
            amount_money=amount_money,
            tip_money=tip_money,
            app_fee_money=app_fee_money,
            delay_duration=delay_duration,
            delay_action=delay_action,
            autocomplete=autocomplete,
            order_id=order_id,
            customer_id=customer_id,
            location_id=location_id,
            team_member_id=team_member_id,
            reference_id=reference_id,
            verification_token=verification_token,
            accept_partial_authorization=accept_partial_authorization,
            buyer_email_address=buyer_email_address,
            buyer_phone_number=buyer_phone_number,
            billing_address=billing_address,
            shipping_address=shipping_address,
            note=note,
            statement_description_identifier=statement_description_identifier,
            cash_details=cash_details,
            external_details=external_details,
            customer_details=customer_details,
            offline_payment_details=offline_payment_details,
            request_options=request_options,
        )
        return response.data

    async def cancel_by_idempotency_key(
        self, *, idempotency_key: str, request_options: typing.Optional[RequestOptions] = None
    ) -> CancelPaymentByIdempotencyKeyResponse:
        """
        Cancels (voids) a payment identified by the idempotency key that is specified in the
        request.

        Use this method when the status of a `CreatePayment` request is unknown (for example, after you send a
        `CreatePayment` request, a network error occurs and you do not get a response). In this case, you can
        direct Square to cancel the payment using this endpoint. In the request, you provide the same
        idempotency key that you provided in your `CreatePayment` request that you want to cancel. After
        canceling the payment, you can submit your `CreatePayment` request again.

        Note that if no payment with the specified idempotency key is found, no action is taken and the endpoint
        returns successfully.

        Parameters
        ----------
        idempotency_key : str
            The `idempotency_key` identifying the payment to be canceled.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CancelPaymentByIdempotencyKeyResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.payments.cancel_by_idempotency_key(
                idempotency_key="a7e36d40-d24b-11e8-b568-0800200c9a66",
            )


        asyncio.run(main())
        """
        response = await self._raw_client.cancel_by_idempotency_key(
            idempotency_key=idempotency_key, request_options=request_options
        )
        return response.data

    async def get(
        self, payment_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> GetPaymentResponse:
        """
        Retrieves details for a specific payment.

        Parameters
        ----------
        payment_id : str
            A unique ID for the desired payment.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetPaymentResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.payments.get(
                payment_id="payment_id",
            )


        asyncio.run(main())
        """
        response = await self._raw_client.get(payment_id, request_options=request_options)
        return response.data

    async def update(
        self,
        payment_id: str,
        *,
        idempotency_key: str,
        payment: typing.Optional[PaymentParams] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UpdatePaymentResponse:
        """
        Updates a payment with the APPROVED status.
        You can update the `amount_money` and `tip_money` using this endpoint.

        Parameters
        ----------
        payment_id : str
            The ID of the payment to update.

        idempotency_key : str
            A unique string that identifies this `UpdatePayment` request. Keys can be any valid string
            but must be unique for every `UpdatePayment` request.

            For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).

        payment : typing.Optional[PaymentParams]
            The updated `Payment` object.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdatePaymentResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.payments.update(
                payment_id="payment_id",
                payment={
                    "amount_money": {"amount": 1000, "currency": "USD"},
                    "tip_money": {"amount": 100, "currency": "USD"},
                    "version_token": "ODhwVQ35xwlzRuoZEwKXucfu7583sPTzK48c5zoGd0g6o",
                },
                idempotency_key="956f8b13-e4ec-45d6-85e8-d1d95ef0c5de",
            )


        asyncio.run(main())
        """
        response = await self._raw_client.update(
            payment_id, idempotency_key=idempotency_key, payment=payment, request_options=request_options
        )
        return response.data

    async def cancel(
        self, payment_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> CancelPaymentResponse:
        """
        Cancels (voids) a payment. You can use this endpoint to cancel a payment with
        the APPROVED `status`.

        Parameters
        ----------
        payment_id : str
            The ID of the payment to cancel.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CancelPaymentResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.payments.cancel(
                payment_id="payment_id",
            )


        asyncio.run(main())
        """
        response = await self._raw_client.cancel(payment_id, request_options=request_options)
        return response.data

    async def complete(
        self,
        payment_id: str,
        *,
        version_token: typing.Optional[str] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> CompletePaymentResponse:
        """
        Completes (captures) a payment.
        By default, payments are set to complete immediately after they are created.

        You can use this endpoint to complete a payment with the APPROVED `status`.

        Parameters
        ----------
        payment_id : str
            The unique ID identifying the payment to be completed.

        version_token : typing.Optional[str]
            Used for optimistic concurrency. This opaque token identifies the current `Payment`
            version that the caller expects. If the server has a different version of the Payment,
            the update fails and a response with a VERSION_MISMATCH error is returned.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CompletePaymentResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.payments.complete(
                payment_id="payment_id",
            )


        asyncio.run(main())
        """
        response = await self._raw_client.complete(
            payment_id, version_token=version_token, request_options=request_options
        )
        return response.data
