pinelabs-python 0.1.0__py3-none-any.whl

pinelabs/payouts/raw_client.py

@@ -0,0 +1,1427 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import datetime as dt
+import typing
+from json.decoder import JSONDecodeError
+
+from ..core.api_error import ApiError
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.datetime_utils import serialize_datetime
+from ..core.http_response import AsyncHttpResponse, HttpResponse
+from ..core.jsonable_encoder import encode_path_param
+from ..core.parse_error import ParsingError
+from ..core.pydantic_utilities import parse_obj_as
+from ..core.request_options import RequestOptions
+from ..core.serialization import convert_and_respect_annotation_metadata
+from ..errors.bad_request_error import BadRequestError
+from ..errors.conflict_error import ConflictError
+from ..errors.forbidden_error import ForbiddenError
+from ..errors.internal_server_error import InternalServerError
+from ..errors.not_found_error import NotFoundError
+from ..errors.unauthorized_error import UnauthorizedError
+from ..types.create_bulk_payout_response import CreateBulkPayoutResponse
+from ..types.create_payout_response import CreatePayoutResponse
+from ..types.error_response import ErrorResponse
+from ..types.get_account_balance_response import GetAccountBalanceResponse
+from ..types.get_payouts_response import GetPayoutsResponse
+from ..types.payout_amount import PayoutAmount
+from ..types.payout_detail import PayoutDetail
+from .types.create_payout_request_mode import CreatePayoutRequestMode
+from .types.list_payouts_request_mode import ListPayoutsRequestMode
+from .types.list_payouts_request_status import ListPayoutsRequestStatus
+from pydantic import ValidationError
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class RawPayoutsClient:
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._client_wrapper = client_wrapper
+
+    def create_payout(
+        self,
+        *,
+        client_reference_id: str,
+        payee_name: str,
+        amount: PayoutAmount,
+        mode: CreatePayoutRequestMode,
+        remarks: str,
+        email: typing.Optional[str] = OMIT,
+        phone: typing.Optional[str] = OMIT,
+        account_number: typing.Optional[str] = OMIT,
+        branch_code: typing.Optional[str] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> HttpResponse[CreatePayoutResponse]:
+        """
+        Creates a single payout to a beneficiary's bank account or UPI VPA.
+        Supports IMPS, NEFT, RTGS, and UPI payment modes.
+
+        For IMPS/NEFT/RTGS, provide accountNumber and branchCode.
+        For UPI, provide vpa instead.
+
+        Parameters
+        ----------
+        client_reference_id : str
+            Unique identifier to track the payout. Must not contain spaces. **Acts as the idempotency key** — duplicate requests with the same `clientReferenceId` will not create a new payout.
+
+        payee_name : str
+            Name of the beneficiary's bank account holder. Alphabets and spaces only.
+
+        amount : PayoutAmount
+
+        mode : CreatePayoutRequestMode
+            Mode of payment for the payout.
+
+        remarks : str
+            Description or reference text for the transaction. Supported characters A-Z, a-z, 0-9, hyphen, space.
+
+        email : typing.Optional[str]
+            Email address of the beneficiary.
+
+        phone : typing.Optional[str]
+            Mobile number of the beneficiary (10 numeric digits).
+
+        account_number : typing.Optional[str]
+            Beneficiary's bank account number. Mandatory for IMPS, NEFT, and RTGS.
+
+        branch_code : typing.Optional[str]
+            Beneficiary's bank IFSC code. Mandatory for IMPS, NEFT, and RTGS.
+            First 4 characters alphabets, 5th character must be 0, remaining alphanumeric.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        HttpResponse[CreatePayoutResponse]
+            Payout created and scheduled successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "payouts/v3/payments/banks",
+            method="POST",
+            json={
+                "clientReferenceId": client_reference_id,
+                "payeeName": payee_name,
+                "email": email,
+                "phone": phone,
+                "accountNumber": account_number,
+                "branchCode": branch_code,
+                "amount": convert_and_respect_annotation_metadata(
+                    object_=amount, annotation=PayoutAmount, direction="write"
+                ),
+                "mode": mode,
+                "remarks": remarks,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    CreatePayoutResponse,
+                    parse_obj_as(
+                        type_=CreatePayoutResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 409:
+                raise ConflictError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    def list_payouts(
+        self,
+        *,
+        payment_reference_id: typing.Optional[str] = None,
+        client_reference_id: typing.Optional[str] = None,
+        request_reference_id: typing.Optional[str] = None,
+        bank_transaction_reference_id: typing.Optional[str] = None,
+        mode: typing.Optional[ListPayoutsRequestMode] = None,
+        date_from: typing.Optional[dt.datetime] = None,
+        date_to: typing.Optional[dt.datetime] = None,
+        status: typing.Optional[ListPayoutsRequestStatus] = None,
+        page: typing.Optional[str] = None,
+        count: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> HttpResponse[GetPayoutsResponse]:
+        """
+        Retrieves payout details. Use paymentReferenceId or clientReferenceId
+        to fetch a specific payout, or requestReferenceId to fetch all payouts
+        associated with a single request. Supports filtering by mode, status,
+        and date range.
+
+        Parameters
+        ----------
+        payment_reference_id : typing.Optional[str]
+            Unique identifier of the payment in Pine Labs database.
+
+        client_reference_id : typing.Optional[str]
+            Unique client reference provided when creating the payout.
+
+        request_reference_id : typing.Optional[str]
+            Unique identifier of the request in Pine Labs database.
+
+        bank_transaction_reference_id : typing.Optional[str]
+            Unique Transaction Reference (UTR) from the bank.
+
+        mode : typing.Optional[ListPayoutsRequestMode]
+            Filter by payment mode.
+
+        date_from : typing.Optional[dt.datetime]
+            Fetch payouts initiated after this date (ISO 8601 UTC).
+
+        date_to : typing.Optional[dt.datetime]
+            Fetch payouts initiated before this date (ISO 8601 UTC).
+
+        status : typing.Optional[ListPayoutsRequestStatus]
+            Filter by payout status.
+
+        page : typing.Optional[str]
+            Page number (default 1).
+
+        count : typing.Optional[str]
+            Number of records per page.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        HttpResponse[GetPayoutsResponse]
+            Payout records retrieved successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "payouts/v3/payments",
+            method="GET",
+            params={
+                "paymentReferenceId": payment_reference_id,
+                "clientReferenceId": client_reference_id,
+                "requestReferenceId": request_reference_id,
+                "bankTransactionReferenceId": bank_transaction_reference_id,
+                "mode": mode,
+                "dateFrom": serialize_datetime(date_from) if date_from is not None else None,
+                "dateTo": serialize_datetime(date_to) if date_to is not None else None,
+                "status": status,
+                "page": page,
+                "count": count,
+            },
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    GetPayoutsResponse,
+                    parse_obj_as(
+                        type_=GetPayoutsResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    def get_payout_balance(
+        self, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> HttpResponse[GetAccountBalanceResponse]:
+        """
+        Retrieves the funding account balance linked to your Pine Labs Online
+        account. This API is only available when you have a funding account
+        linked to your Pine Labs Online account.
+
+        Parameters
+        ----------
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        HttpResponse[GetAccountBalanceResponse]
+            Account balance retrieved successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "payouts/v3/payments/funding-account",
+            method="GET",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    GetAccountBalanceResponse,
+                    parse_obj_as(
+                        type_=GetAccountBalanceResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    def create_bulk_payout(
+        self, *, file: bytes, request_options: typing.Optional[RequestOptions] = None
+    ) -> HttpResponse[CreateBulkPayoutResponse]:
+        """
+        Creates multiple payouts in bulk by uploading a file containing
+        beneficiary account details. The file is processed asynchronously.
+        Use the Get Payouts API with the returned requestReferenceId to
+        track individual payout statuses.
+
+        Parameters
+        ----------
+        file : bytes
+            File containing beneficiary account details for bulk payout processing.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        HttpResponse[CreateBulkPayoutResponse]
+            Bulk payout file accepted and processing initiated.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "payouts/v3/payments/banks/file",
+            method="POST",
+            data={
+                "file": file,
+            },
+            headers={
+                "content-type": "application/x-www-form-urlencoded",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    CreateBulkPayoutResponse,
+                    parse_obj_as(
+                        type_=CreateBulkPayoutResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    def update_scheduled_payout(
+        self,
+        payment_reference_id: str,
+        *,
+        schedule_at: typing.Optional[dt.datetime] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> HttpResponse[PayoutDetail]:
+        """
+        Updates the scheduled date of a payout. Only payouts with status
+        SCHEDULED can be updated. Provide the new schedule date in
+        ISO 8601 UTC format.
+
+        Parameters
+        ----------
+        payment_reference_id : str
+            Unique identifier of the payment in Pine Labs database.
+
+        schedule_at : typing.Optional[dt.datetime]
+            New scheduled time for executing the payout (ISO 8601 UTC).
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        HttpResponse[PayoutDetail]
+            Payout schedule updated successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            f"payouts/v3/payments/banks/{encode_path_param(payment_reference_id)}",
+            method="PUT",
+            json={
+                "scheduleAt": schedule_at,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    PayoutDetail,
+                    parse_obj_as(
+                        type_=PayoutDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    def cancel_scheduled_payout(
+        self, payment_reference_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> HttpResponse[PayoutDetail]:
+        """
+        Cancels a scheduled payout. Only payouts with status SCHEDULED
+        can be cancelled. Once cancelled, the payout cannot be reinstated.
+
+        Parameters
+        ----------
+        payment_reference_id : str
+            Unique identifier of the payment in Pine Labs database.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        HttpResponse[PayoutDetail]
+            Payout cancelled successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            f"payouts/v3/payments/banks/{encode_path_param(payment_reference_id)}/cancel",
+            method="PUT",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    PayoutDetail,
+                    parse_obj_as(
+                        type_=PayoutDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+
+class AsyncRawPayoutsClient:
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        self._client_wrapper = client_wrapper
+
+    async def create_payout(
+        self,
+        *,
+        client_reference_id: str,
+        payee_name: str,
+        amount: PayoutAmount,
+        mode: CreatePayoutRequestMode,
+        remarks: str,
+        email: typing.Optional[str] = OMIT,
+        phone: typing.Optional[str] = OMIT,
+        account_number: typing.Optional[str] = OMIT,
+        branch_code: typing.Optional[str] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncHttpResponse[CreatePayoutResponse]:
+        """
+        Creates a single payout to a beneficiary's bank account or UPI VPA.
+        Supports IMPS, NEFT, RTGS, and UPI payment modes.
+
+        For IMPS/NEFT/RTGS, provide accountNumber and branchCode.
+        For UPI, provide vpa instead.
+
+        Parameters
+        ----------
+        client_reference_id : str
+            Unique identifier to track the payout. Must not contain spaces. **Acts as the idempotency key** — duplicate requests with the same `clientReferenceId` will not create a new payout.
+
+        payee_name : str
+            Name of the beneficiary's bank account holder. Alphabets and spaces only.
+
+        amount : PayoutAmount
+
+        mode : CreatePayoutRequestMode
+            Mode of payment for the payout.
+
+        remarks : str
+            Description or reference text for the transaction. Supported characters A-Z, a-z, 0-9, hyphen, space.
+
+        email : typing.Optional[str]
+            Email address of the beneficiary.
+
+        phone : typing.Optional[str]
+            Mobile number of the beneficiary (10 numeric digits).
+
+        account_number : typing.Optional[str]
+            Beneficiary's bank account number. Mandatory for IMPS, NEFT, and RTGS.
+
+        branch_code : typing.Optional[str]
+            Beneficiary's bank IFSC code. Mandatory for IMPS, NEFT, and RTGS.
+            First 4 characters alphabets, 5th character must be 0, remaining alphanumeric.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncHttpResponse[CreatePayoutResponse]
+            Payout created and scheduled successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "payouts/v3/payments/banks",
+            method="POST",
+            json={
+                "clientReferenceId": client_reference_id,
+                "payeeName": payee_name,
+                "email": email,
+                "phone": phone,
+                "accountNumber": account_number,
+                "branchCode": branch_code,
+                "amount": convert_and_respect_annotation_metadata(
+                    object_=amount, annotation=PayoutAmount, direction="write"
+                ),
+                "mode": mode,
+                "remarks": remarks,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    CreatePayoutResponse,
+                    parse_obj_as(
+                        type_=CreatePayoutResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 409:
+                raise ConflictError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def list_payouts(
+        self,
+        *,
+        payment_reference_id: typing.Optional[str] = None,
+        client_reference_id: typing.Optional[str] = None,
+        request_reference_id: typing.Optional[str] = None,
+        bank_transaction_reference_id: typing.Optional[str] = None,
+        mode: typing.Optional[ListPayoutsRequestMode] = None,
+        date_from: typing.Optional[dt.datetime] = None,
+        date_to: typing.Optional[dt.datetime] = None,
+        status: typing.Optional[ListPayoutsRequestStatus] = None,
+        page: typing.Optional[str] = None,
+        count: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncHttpResponse[GetPayoutsResponse]:
+        """
+        Retrieves payout details. Use paymentReferenceId or clientReferenceId
+        to fetch a specific payout, or requestReferenceId to fetch all payouts
+        associated with a single request. Supports filtering by mode, status,
+        and date range.
+
+        Parameters
+        ----------
+        payment_reference_id : typing.Optional[str]
+            Unique identifier of the payment in Pine Labs database.
+
+        client_reference_id : typing.Optional[str]
+            Unique client reference provided when creating the payout.
+
+        request_reference_id : typing.Optional[str]
+            Unique identifier of the request in Pine Labs database.
+
+        bank_transaction_reference_id : typing.Optional[str]
+            Unique Transaction Reference (UTR) from the bank.
+
+        mode : typing.Optional[ListPayoutsRequestMode]
+            Filter by payment mode.
+
+        date_from : typing.Optional[dt.datetime]
+            Fetch payouts initiated after this date (ISO 8601 UTC).
+
+        date_to : typing.Optional[dt.datetime]
+            Fetch payouts initiated before this date (ISO 8601 UTC).
+
+        status : typing.Optional[ListPayoutsRequestStatus]
+            Filter by payout status.
+
+        page : typing.Optional[str]
+            Page number (default 1).
+
+        count : typing.Optional[str]
+            Number of records per page.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncHttpResponse[GetPayoutsResponse]
+            Payout records retrieved successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "payouts/v3/payments",
+            method="GET",
+            params={
+                "paymentReferenceId": payment_reference_id,
+                "clientReferenceId": client_reference_id,
+                "requestReferenceId": request_reference_id,
+                "bankTransactionReferenceId": bank_transaction_reference_id,
+                "mode": mode,
+                "dateFrom": serialize_datetime(date_from) if date_from is not None else None,
+                "dateTo": serialize_datetime(date_to) if date_to is not None else None,
+                "status": status,
+                "page": page,
+                "count": count,
+            },
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    GetPayoutsResponse,
+                    parse_obj_as(
+                        type_=GetPayoutsResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def get_payout_balance(
+        self, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> AsyncHttpResponse[GetAccountBalanceResponse]:
+        """
+        Retrieves the funding account balance linked to your Pine Labs Online
+        account. This API is only available when you have a funding account
+        linked to your Pine Labs Online account.
+
+        Parameters
+        ----------
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncHttpResponse[GetAccountBalanceResponse]
+            Account balance retrieved successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "payouts/v3/payments/funding-account",
+            method="GET",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    GetAccountBalanceResponse,
+                    parse_obj_as(
+                        type_=GetAccountBalanceResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def create_bulk_payout(
+        self, *, file: bytes, request_options: typing.Optional[RequestOptions] = None
+    ) -> AsyncHttpResponse[CreateBulkPayoutResponse]:
+        """
+        Creates multiple payouts in bulk by uploading a file containing
+        beneficiary account details. The file is processed asynchronously.
+        Use the Get Payouts API with the returned requestReferenceId to
+        track individual payout statuses.
+
+        Parameters
+        ----------
+        file : bytes
+            File containing beneficiary account details for bulk payout processing.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncHttpResponse[CreateBulkPayoutResponse]
+            Bulk payout file accepted and processing initiated.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "payouts/v3/payments/banks/file",
+            method="POST",
+            data={
+                "file": file,
+            },
+            headers={
+                "content-type": "application/x-www-form-urlencoded",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    CreateBulkPayoutResponse,
+                    parse_obj_as(
+                        type_=CreateBulkPayoutResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def update_scheduled_payout(
+        self,
+        payment_reference_id: str,
+        *,
+        schedule_at: typing.Optional[dt.datetime] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncHttpResponse[PayoutDetail]:
+        """
+        Updates the scheduled date of a payout. Only payouts with status
+        SCHEDULED can be updated. Provide the new schedule date in
+        ISO 8601 UTC format.
+
+        Parameters
+        ----------
+        payment_reference_id : str
+            Unique identifier of the payment in Pine Labs database.
+
+        schedule_at : typing.Optional[dt.datetime]
+            New scheduled time for executing the payout (ISO 8601 UTC).
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncHttpResponse[PayoutDetail]
+            Payout schedule updated successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            f"payouts/v3/payments/banks/{encode_path_param(payment_reference_id)}",
+            method="PUT",
+            json={
+                "scheduleAt": schedule_at,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    PayoutDetail,
+                    parse_obj_as(
+                        type_=PayoutDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def cancel_scheduled_payout(
+        self, payment_reference_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> AsyncHttpResponse[PayoutDetail]:
+        """
+        Cancels a scheduled payout. Only payouts with status SCHEDULED
+        can be cancelled. Once cancelled, the payout cannot be reinstated.
+
+        Parameters
+        ----------
+        payment_reference_id : str
+            Unique identifier of the payment in Pine Labs database.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncHttpResponse[PayoutDetail]
+            Payout cancelled successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            f"payouts/v3/payments/banks/{encode_path_param(payment_reference_id)}/cancel",
+            method="PUT",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    PayoutDetail,
+                    parse_obj_as(
+                        type_=PayoutDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)