Skip to content

Refunds

RefundClient

Bases: BaseAPIClient

Provides a wrapper for paystack Refunds API

The Refunds API allows you to create and manage transaction refunds. https://paystack.com/docs/api/refund/

Source code in src/pypaystack2/sub_clients/sync_clients/refunds.py 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
class RefundClient(BaseAPIClient):
    """Provides a wrapper for paystack Refunds API

    The Refunds API allows you to create and manage transaction refunds.
    https://paystack.com/docs/api/refund/
    """

    def create(
        self,
        transaction: int | str,
        amount: int | None = None,
        currency: Currency | None = None,
        customer_note: str | None = None,
        merchant_note: str | None = None,
        alternate_model_class: type[PaystackDataModel] | None = None,
    ) -> Response[Refund] | Response[PaystackDataModel]:
        """Initiate a refund on your integration

        Args:
            transaction: Transaction reference or id
            amount: Amount ( in kobo if currency is NGN, pesewas, if currency is
                GHS, and cents, if currency is ZAR ) to be refunded to the
                customer. Amount is optional(defaults to original
                transaction amount) and cannot be more than the original
                transaction amount
            currency: Any value from the ``Currency`` enum
            customer_note: Customer reason
            merchant_note: Merchant reason
            alternate_model_class: A pydantic model class to use instead of the
                default pydantic model used by the library to present the data in
                the `Response.data`. The default behaviour of the library is to
                set  `Response.data` to `None` if it fails to serialize the data
                returned from paystack with the model provided in the library.
                Providing a pydantic model class via this parameter overrides
                the library default model with the model class you provide.
                This can come in handy when the models in the library do not
                accurately represent the data returned, and you prefer working with the
                data as a pydantic model instead of as a dict of the response returned
                by  paystack before it is serialized with pydantic models, The original
                data can be accessed via `Response.raw`.

        Returns:
            A pydantic model containing the response gotten from paystack's server.
        """

        url = self._full_url("/refund")
        payload = {"transaction": transaction}
        optional_params = [
            ("amount", amount),
            ("currency", currency),
            ("customer_note", customer_note),
            ("merchant_note", merchant_note),
        ]
        payload = add_to_payload(optional_params, payload)
        return self._handle_request(  # type: ignore
            HTTPMethod.POST,
            url,
            payload,
            response_data_model_class=alternate_model_class or Refund,
        )

    def retry_refund(
        self,
        refund_id: str | int,
        refund_account: RefundAccount,
        alternate_model_class: type[PaystackDataModel] | None = None,
    ) -> Response[Refund] | Response[PaystackDataModel]:
        """Retry a refund with a needs-attention status by providing the bank
            account details of a customer.

        Args:
            refund_id: The ID of the previously initiated refund
            refund_account: A pydantic model containing the customer's account
                details for refund.
            alternate_model_class: A pydantic model class to use instead of the
                default pydantic model used by the library to present the data in
                the `Response.data`. The default behaviour of the library is to
                set  `Response.data` to `None` if it fails to serialize the data
                returned from paystack with the model provided in the library.
                Providing a pydantic model class via this parameter overrides
                the library default model with the model class you provide.
                This can come in handy when the models in the library do not
                accurately represent the data returned, and you prefer working with the
                data as a pydantic model instead of as a dict of the response returned
                by  paystack before it is serialized with pydantic models, The original
                data can be accessed via `Response.raw`.

        Returns:
            A pydantic model containing the response gotten from paystack's server.
        """
        url = self._full_url(f"/refund/retry_with_customer_details/{refund_id}")
        payload = {"refund_account_details": refund_account.model_dump()}
        return self._handle_request(  # type: ignore
            HTTPMethod.POST,
            url,
            payload,
            response_data_model_class=alternate_model_class or Refund,
        )

    def get_refunds(
        self,
        reference: str | None = None,
        transaction: str | None = None,
        currency: Currency | None = None,
        pagination: int = 50,
        page: int = 1,
        start_date: str | None = None,
        end_date: str | None = None,
        alternate_model_class: type[PaystackDataModel] | None = None,
    ) -> Response[list[Refund]] | Response[PaystackDataModel]:
        """Fetch refunds available on your integration.

        Args:
            reference: Identifier for transaction to be refunded
            transaction: The transaction ID of the refunded transaction
            currency: Any value from the ``Currency`` enum
            pagination: Specifies how many records you want to retrieve per page.
                If not specified we use a default value of 50.
            page: Specifies exactly what refund you want to page.
                If not specified we use a default value of 1.
            start_date: A timestamp from which to start listing refund e.g. 2016-09-21
            end_date: A timestamp at which to stop listing refund e.g. 2016-09-21
            alternate_model_class: A pydantic model class to use instead of the
                default pydantic model used by the library to present the data in
                the `Response.data`. The default behaviour of the library is to
                set  `Response.data` to `None` if it fails to serialize the data
                returned from paystack with the model provided in the library.
                Providing a pydantic model class via this parameter overrides
                the library default model with the model class you provide.
                This can come in handy when the models in the library do not
                accurately represent the data returned, and you prefer working with the
                data as a pydantic model instead of as a dict of the response returned
                by  paystack before it is serialized with pydantic models, The original
                data can be accessed via `Response.raw`.

        Returns:
            A pydantic model containing the response gotten from paystack's server.
        """
        if reference:
            warnings.warn(
                "'reference' is deprecated; use 'transaction'",
                DeprecationWarning,
                stacklevel=2,
            )
            transaction = reference
        url = self._full_url(f"/refund?perPage={pagination}")
        query_params = [
            ("transaction", transaction),
            ("currency", currency),
            ("page", page),
            ("start_date", start_date),
            ("end_date", end_date),
        ]
        url = append_query_params(query_params, url)
        return self._handle_request(  # type: ignore
            HTTPMethod.GET,
            url,
            response_data_model_class=alternate_model_class or Refund,
        )

    def get_refund(
        self,
        reference: str,
        alternate_model_class: type[PaystackDataModel] | None = None,
    ) -> Response[Refund] | Response[PaystackDataModel]:
        """Get details of a refund on your integration.

        Args:
            reference: Identifier for transaction to be refunded
            alternate_model_class: A pydantic model class to use instead of the
                default pydantic model used by the library to present the data in
                the `Response.data`. The default behaviour of the library is to
                set  `Response.data` to `None` if it fails to serialize the data
                returned from paystack with the model provided in the library.
                Providing a pydantic model class via this parameter overrides
                the library default model with the model class you provide.
                This can come in handy when the models in the library do not
                accurately represent the data returned, and you prefer working with the
                data as a pydantic model instead of as a dict of the response returned
                by  paystack before it is serialized with pydantic models, The original
                data can be accessed via `Response.raw`.

        Returns:
            A pydantic model containing the response gotten from paystack's server.
        """

        url = self._full_url(f"/refund/{reference}")
        return self._handle_request(  # type: ignore
            HTTPMethod.GET,
            url,
            response_data_model_class=alternate_model_class or Refund,
        )

create(transaction, amount=None, currency=None, customer_note=None, merchant_note=None, alternate_model_class=None)

Initiate a refund on your integration

Parameters:

Name Type Description Default
transaction int | str

Transaction reference or id

 required
amount int | None

Amount ( in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR ) to be refunded to the customer. Amount is optional(defaults to original transaction amount) and cannot be more than the original transaction amount

 None
currency Currency | None

Any value from the Currency enum

 None
customer_note str | None

Customer reason

 None
merchant_note str | None

Merchant reason

 None
alternate_model_class type[PaystackDataModel] | None

A pydantic model class to use instead of the default pydantic model used by the library to present the data in the Response.data. The default behaviour of the library is to set Response.data to None if it fails to serialize the data returned from paystack with the model provided in the library. Providing a pydantic model class via this parameter overrides the library default model with the model class you provide. This can come in handy when the models in the library do not accurately represent the data returned, and you prefer working with the data as a pydantic model instead of as a dict of the response returned by paystack before it is serialized with pydantic models, The original data can be accessed via Response.raw.

 None

Returns:

Type Description
Response[Refund] | Response[PaystackDataModel]

A pydantic model containing the response gotten from paystack's server.
Source code in src/pypaystack2/sub_clients/sync_clients/refunds.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def create(
    self,
    transaction: int | str,
    amount: int | None = None,
    currency: Currency | None = None,
    customer_note: str | None = None,
    merchant_note: str | None = None,
    alternate_model_class: type[PaystackDataModel] | None = None,
) -> Response[Refund] | Response[PaystackDataModel]:
    """Initiate a refund on your integration

    Args:
        transaction: Transaction reference or id
        amount: Amount ( in kobo if currency is NGN, pesewas, if currency is
            GHS, and cents, if currency is ZAR ) to be refunded to the
            customer. Amount is optional(defaults to original
            transaction amount) and cannot be more than the original
            transaction amount
        currency: Any value from the ``Currency`` enum
        customer_note: Customer reason
        merchant_note: Merchant reason
        alternate_model_class: A pydantic model class to use instead of the
            default pydantic model used by the library to present the data in
            the `Response.data`. The default behaviour of the library is to
            set  `Response.data` to `None` if it fails to serialize the data
            returned from paystack with the model provided in the library.
            Providing a pydantic model class via this parameter overrides
            the library default model with the model class you provide.
            This can come in handy when the models in the library do not
            accurately represent the data returned, and you prefer working with the
            data as a pydantic model instead of as a dict of the response returned
            by  paystack before it is serialized with pydantic models, The original
            data can be accessed via `Response.raw`.

    Returns:
        A pydantic model containing the response gotten from paystack's server.
    """

    url = self._full_url("/refund")
    payload = {"transaction": transaction}
    optional_params = [
        ("amount", amount),
        ("currency", currency),
        ("customer_note", customer_note),
        ("merchant_note", merchant_note),
    ]
    payload = add_to_payload(optional_params, payload)
    return self._handle_request(  # type: ignore
        HTTPMethod.POST,
        url,
        payload,
        response_data_model_class=alternate_model_class or Refund,
    )

get_refund(reference, alternate_model_class=None)

Get details of a refund on your integration.

Parameters:

Name Type Description Default
reference str

Identifier for transaction to be refunded

 required
alternate_model_class type[PaystackDataModel] | None

A pydantic model class to use instead of the default pydantic model used by the library to present the data in the Response.data. The default behaviour of the library is to set Response.data to None if it fails to serialize the data returned from paystack with the model provided in the library. Providing a pydantic model class via this parameter overrides the library default model with the model class you provide. This can come in handy when the models in the library do not accurately represent the data returned, and you prefer working with the data as a pydantic model instead of as a dict of the response returned by paystack before it is serialized with pydantic models, The original data can be accessed via Response.raw.

 None

Returns:

Type Description
Response[Refund] | Response[PaystackDataModel]

A pydantic model containing the response gotten from paystack's server.
Source code in src/pypaystack2/sub_clients/sync_clients/refunds.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
def get_refund(
    self,
    reference: str,
    alternate_model_class: type[PaystackDataModel] | None = None,
) -> Response[Refund] | Response[PaystackDataModel]:
    """Get details of a refund on your integration.

    Args:
        reference: Identifier for transaction to be refunded
        alternate_model_class: A pydantic model class to use instead of the
            default pydantic model used by the library to present the data in
            the `Response.data`. The default behaviour of the library is to
            set  `Response.data` to `None` if it fails to serialize the data
            returned from paystack with the model provided in the library.
            Providing a pydantic model class via this parameter overrides
            the library default model with the model class you provide.
            This can come in handy when the models in the library do not
            accurately represent the data returned, and you prefer working with the
            data as a pydantic model instead of as a dict of the response returned
            by  paystack before it is serialized with pydantic models, The original
            data can be accessed via `Response.raw`.

    Returns:
        A pydantic model containing the response gotten from paystack's server.
    """

    url = self._full_url(f"/refund/{reference}")
    return self._handle_request(  # type: ignore
        HTTPMethod.GET,
        url,
        response_data_model_class=alternate_model_class or Refund,
    )

get_refunds(reference=None, transaction=None, currency=None, pagination=50, page=1, start_date=None, end_date=None, alternate_model_class=None)

Fetch refunds available on your integration.

Parameters:

Name Type Description Default
reference str | None

Identifier for transaction to be refunded

 None
transaction str | None

The transaction ID of the refunded transaction

 None
currency Currency | None

Any value from the Currency enum

 None
pagination int

Specifies how many records you want to retrieve per page. If not specified we use a default value of 50.

 50
page int

Specifies exactly what refund you want to page. If not specified we use a default value of 1.

 1
start_date str | None

A timestamp from which to start listing refund e.g. 2016-09-21

 None
end_date str | None

A timestamp at which to stop listing refund e.g. 2016-09-21

 None
alternate_model_class type[PaystackDataModel] | None

A pydantic model class to use instead of the default pydantic model used by the library to present the data in the Response.data. The default behaviour of the library is to set Response.data to None if it fails to serialize the data returned from paystack with the model provided in the library. Providing a pydantic model class via this parameter overrides the library default model with the model class you provide. This can come in handy when the models in the library do not accurately represent the data returned, and you prefer working with the data as a pydantic model instead of as a dict of the response returned by paystack before it is serialized with pydantic models, The original data can be accessed via Response.raw.

 None

Returns:

Type Description
Response[list[Refund]] | Response[PaystackDataModel]

A pydantic model containing the response gotten from paystack's server.
Source code in src/pypaystack2/sub_clients/sync_clients/refunds.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def get_refunds(
    self,
    reference: str | None = None,
    transaction: str | None = None,
    currency: Currency | None = None,
    pagination: int = 50,
    page: int = 1,
    start_date: str | None = None,
    end_date: str | None = None,
    alternate_model_class: type[PaystackDataModel] | None = None,
) -> Response[list[Refund]] | Response[PaystackDataModel]:
    """Fetch refunds available on your integration.

    Args:
        reference: Identifier for transaction to be refunded
        transaction: The transaction ID of the refunded transaction
        currency: Any value from the ``Currency`` enum
        pagination: Specifies how many records you want to retrieve per page.
            If not specified we use a default value of 50.
        page: Specifies exactly what refund you want to page.
            If not specified we use a default value of 1.
        start_date: A timestamp from which to start listing refund e.g. 2016-09-21
        end_date: A timestamp at which to stop listing refund e.g. 2016-09-21
        alternate_model_class: A pydantic model class to use instead of the
            default pydantic model used by the library to present the data in
            the `Response.data`. The default behaviour of the library is to
            set  `Response.data` to `None` if it fails to serialize the data
            returned from paystack with the model provided in the library.
            Providing a pydantic model class via this parameter overrides
            the library default model with the model class you provide.
            This can come in handy when the models in the library do not
            accurately represent the data returned, and you prefer working with the
            data as a pydantic model instead of as a dict of the response returned
            by  paystack before it is serialized with pydantic models, The original
            data can be accessed via `Response.raw`.

    Returns:
        A pydantic model containing the response gotten from paystack's server.
    """
    if reference:
        warnings.warn(
            "'reference' is deprecated; use 'transaction'",
            DeprecationWarning,
            stacklevel=2,
        )
        transaction = reference
    url = self._full_url(f"/refund?perPage={pagination}")
    query_params = [
        ("transaction", transaction),
        ("currency", currency),
        ("page", page),
        ("start_date", start_date),
        ("end_date", end_date),
    ]
    url = append_query_params(query_params, url)
    return self._handle_request(  # type: ignore
        HTTPMethod.GET,
        url,
        response_data_model_class=alternate_model_class or Refund,
    )

retry_refund(refund_id, refund_account, alternate_model_class=None)

Retry a refund with a needs-attention status by providing the bank account details of a customer.

Parameters:

Name Type Description Default
refund_id str | int

The ID of the previously initiated refund

 required
refund_account RefundAccount

A pydantic model containing the customer's account details for refund.

 required
alternate_model_class type[PaystackDataModel] | None

A pydantic model class to use instead of the default pydantic model used by the library to present the data in the Response.data. The default behaviour of the library is to set Response.data to None if it fails to serialize the data returned from paystack with the model provided in the library. Providing a pydantic model class via this parameter overrides the library default model with the model class you provide. This can come in handy when the models in the library do not accurately represent the data returned, and you prefer working with the data as a pydantic model instead of as a dict of the response returned by paystack before it is serialized with pydantic models, The original data can be accessed via Response.raw.

 None

Returns:

Type Description
Response[Refund] | Response[PaystackDataModel]

A pydantic model containing the response gotten from paystack's server.
Source code in src/pypaystack2/sub_clients/sync_clients/refunds.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def retry_refund(
    self,
    refund_id: str | int,
    refund_account: RefundAccount,
    alternate_model_class: type[PaystackDataModel] | None = None,
) -> Response[Refund] | Response[PaystackDataModel]:
    """Retry a refund with a needs-attention status by providing the bank
        account details of a customer.

    Args:
        refund_id: The ID of the previously initiated refund
        refund_account: A pydantic model containing the customer's account
            details for refund.
        alternate_model_class: A pydantic model class to use instead of the
            default pydantic model used by the library to present the data in
            the `Response.data`. The default behaviour of the library is to
            set  `Response.data` to `None` if it fails to serialize the data
            returned from paystack with the model provided in the library.
            Providing a pydantic model class via this parameter overrides
            the library default model with the model class you provide.
            This can come in handy when the models in the library do not
            accurately represent the data returned, and you prefer working with the
            data as a pydantic model instead of as a dict of the response returned
            by  paystack before it is serialized with pydantic models, The original
            data can be accessed via `Response.raw`.

    Returns:
        A pydantic model containing the response gotten from paystack's server.
    """
    url = self._full_url(f"/refund/retry_with_customer_details/{refund_id}")
    payload = {"refund_account_details": refund_account.model_dump()}
    return self._handle_request(  # type: ignore
        HTTPMethod.POST,
        url,
        payload,
        response_data_model_class=alternate_model_class or Refund,
    )

AsyncRefundClient

Bases: BaseAsyncAPIClient

Provides a wrapper for paystack Refunds API

The Refunds API allows you to create and manage transaction refunds. https://paystack.com/docs/api/refund/

Source code in src/pypaystack2/sub_clients/async_clients/refunds.py 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
class AsyncRefundClient(BaseAsyncAPIClient):
    """Provides a wrapper for paystack Refunds API

    The Refunds API allows you to create and manage transaction refunds.
    https://paystack.com/docs/api/refund/
    """

    async def create(
        self,
        transaction: str,
        amount: int | None = None,
        currency: Currency | None = None,
        customer_note: str | None = None,
        merchant_note: str | None = None,
        alternate_model_class: type[PaystackDataModel] | None = None,
    ) -> Response[Refund] | Response[PaystackDataModel]:
        """Initiate a refund on your integration

        Args:
            transaction: Transaction reference or id
            amount: Amount ( in kobo if currency is NGN, pesewas, if currency is
                GHS, and cents, if currency is ZAR ) to be refunded to the
                customer. Amount is optional(defaults to original
                transaction amount) and cannot be more than the original
                transaction amount
            currency: Any value from the ``Currency`` enum
            customer_note: Customer reason
            merchant_note: Merchant reason
            alternate_model_class: A pydantic model class to use instead of the
                default pydantic model used by the library to present the data in
                the `Response.data`. The default behaviour of the library is to
                set  `Response.data` to `None` if it fails to serialize the data
                returned from paystack with the model provided in the library.
                Providing a pydantic model class via this parameter overrides
                the library default model with the model class you provide.
                This can come in handy when the models in the library do not
                accurately represent the data returned, and you prefer working with the
                data as a pydantic model instead of as a dict of the response returned
                by  paystack before it is serialized with pydantic models, The original
                data can be accessed via `Response.raw`.

        Returns:
            A pydantic model containing the response gotten from paystack's server.
        """

        url = self._full_url("/refund")
        payload = {"transaction": transaction}
        optional_params = [
            ("amount", amount),
            ("currency", currency),
            ("customer_note", customer_note),
            ("merchant_note", merchant_note),
        ]
        payload = add_to_payload(optional_params, payload)
        return await self._handle_request(  # type: ignore
            HTTPMethod.POST,
            url,
            payload,
            response_data_model_class=alternate_model_class or Refund,
        )

    async def retry_refund(
        self,
        refund_id: str | int,
        refund_account: RefundAccount,
        alternate_model_class: type[PaystackDataModel] | None = None,
    ) -> Response[Refund] | Response[PaystackDataModel]:
        """Retry a refund with a needs-attention status by providing the bank
            account details of a customer.

        Args:
            refund_id: The ID of the previously initiated refund
            refund_account: A pydantic model containing the customer's account
                details for refund.
            alternate_model_class: A pydantic model class to use instead of the
                default pydantic model used by the library to present the data in
                the `Response.data`. The default behaviour of the library is to
                set  `Response.data` to `None` if it fails to serialize the data
                returned from paystack with the model provided in the library.
                Providing a pydantic model class via this parameter overrides
                the library default model with the model class you provide.
                This can come in handy when the models in the library do not
                accurately represent the data returned, and you prefer working with the
                data as a pydantic model instead of as a dict of the response returned
                by  paystack before it is serialized with pydantic models, The original
                data can be accessed via `Response.raw`.

        Returns:
            A pydantic model containing the response gotten from paystack's server.
        """
        url = self._full_url(f"/refund/retry_with_customer_details/{refund_id}")
        payload = {"refund_account_details": refund_account.model_dump()}
        return await self._handle_request(  # type: ignore
            HTTPMethod.POST,
            url,
            payload,
            response_data_model_class=alternate_model_class or Refund,
        )

    async def get_refunds(
        self,
        reference: str | None = None,
        transaction: str | None = None,
        currency: Currency | None = None,
        pagination: int = 50,
        page: int = 1,
        start_date: str | None = None,
        end_date: str | None = None,
        alternate_model_class: type[PaystackDataModel] | None = None,
    ) -> Response[list[Refund]] | Response[PaystackDataModel]:
        """Fetch refunds available on your integration.

        Args:
            reference: Identifier for transaction to be refunded
            transaction: The transaction ID of the refunded transaction
            currency: Any value from the ``Currency`` enum
            pagination: Specifies how many records you want to retrieve per page.
                If not specified we use a default value of 50.
            page: Specifies exactly what refund you want to page.
                If not specified we use a default value of 1.
            start_date: A timestamp from which to start listing refund e.g. 2016-09-21
            end_date: A timestamp at which to stop listing refund e.g. 2016-09-21
            alternate_model_class: A pydantic model class to use instead of the
                default pydantic model used by the library to present the data in
                the `Response.data`. The default behaviour of the library is to
                set  `Response.data` to `None` if it fails to serialize the data
                returned from paystack with the model provided in the library.
                Providing a pydantic model class via this parameter overrides
                the library default model with the model class you provide.
                This can come in handy when the models in the library do not
                accurately represent the data returned, and you prefer working with the
                data as a pydantic model instead of as a dict of the response returned
                by  paystack before it is serialized with pydantic models, The original
                data can be accessed via `Response.raw`.

        Returns:
            A pydantic model containing the response gotten from paystack's server.
        """
        if reference:
            warnings.warn(
                "'reference' is deprecated; use 'transaction'",
                DeprecationWarning,
                stacklevel=2,
            )
            transaction = reference
        url = self._full_url(f"/refund?perPage={pagination}")
        query_params = [
            ("transaction", transaction),
            ("currency", currency),
            ("page", page),
            ("start_date", start_date),
            ("end_date", end_date),
        ]
        url = append_query_params(query_params, url)
        return await self._handle_request(  # type: ignore
            HTTPMethod.GET,
            url,
            response_data_model_class=alternate_model_class or Refund,
        )

    async def get_refund(
        self,
        reference: str,
        alternate_model_class: type[PaystackDataModel] | None = None,
    ) -> Response[Refund] | Response[PaystackDataModel]:
        """Get details of a refund on your integration.

        Args:
            reference: Identifier for transaction to be refunded
            alternate_model_class: A pydantic model class to use instead of the
                default pydantic model used by the library to present the data in
                the `Response.data`. The default behaviour of the library is to
                set  `Response.data` to `None` if it fails to serialize the data
                returned from paystack with the model provided in the library.
                Providing a pydantic model class via this parameter overrides
                the library default model with the model class you provide.
                This can come in handy when the models in the library do not
                accurately represent the data returned, and you prefer working with the
                data as a pydantic model instead of as a dict of the response returned
                by  paystack before it is serialized with pydantic models, The original
                data can be accessed via `Response.raw`.

        Returns:
            A pydantic model containing the response gotten from paystack's server.
        """

        url = self._full_url(f"/refund/{reference}")
        return await self._handle_request(  # type: ignore
            HTTPMethod.GET,
            url,
            response_data_model_class=alternate_model_class or Refund,
        )

create(transaction, amount=None, currency=None, customer_note=None, merchant_note=None, alternate_model_class=None) async

Initiate a refund on your integration

Parameters:

Name Type Description Default
transaction str

Transaction reference or id

 required
amount int | None

Amount ( in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR ) to be refunded to the customer. Amount is optional(defaults to original transaction amount) and cannot be more than the original transaction amount

 None
currency Currency | None

Any value from the Currency enum

 None
customer_note str | None

Customer reason

 None
merchant_note str | None

Merchant reason

 None
alternate_model_class type[PaystackDataModel] | None

A pydantic model class to use instead of the default pydantic model used by the library to present the data in the Response.data. The default behaviour of the library is to set Response.data to None if it fails to serialize the data returned from paystack with the model provided in the library. Providing a pydantic model class via this parameter overrides the library default model with the model class you provide. This can come in handy when the models in the library do not accurately represent the data returned, and you prefer working with the data as a pydantic model instead of as a dict of the response returned by paystack before it is serialized with pydantic models, The original data can be accessed via Response.raw.

 None

Returns:

Type Description
Response[Refund] | Response[PaystackDataModel]

A pydantic model containing the response gotten from paystack's server.
Source code in src/pypaystack2/sub_clients/async_clients/refunds.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
async def create(
    self,
    transaction: str,
    amount: int | None = None,
    currency: Currency | None = None,
    customer_note: str | None = None,
    merchant_note: str | None = None,
    alternate_model_class: type[PaystackDataModel] | None = None,
) -> Response[Refund] | Response[PaystackDataModel]:
    """Initiate a refund on your integration

    Args:
        transaction: Transaction reference or id
        amount: Amount ( in kobo if currency is NGN, pesewas, if currency is
            GHS, and cents, if currency is ZAR ) to be refunded to the
            customer. Amount is optional(defaults to original
            transaction amount) and cannot be more than the original
            transaction amount
        currency: Any value from the ``Currency`` enum
        customer_note: Customer reason
        merchant_note: Merchant reason
        alternate_model_class: A pydantic model class to use instead of the
            default pydantic model used by the library to present the data in
            the `Response.data`. The default behaviour of the library is to
            set  `Response.data` to `None` if it fails to serialize the data
            returned from paystack with the model provided in the library.
            Providing a pydantic model class via this parameter overrides
            the library default model with the model class you provide.
            This can come in handy when the models in the library do not
            accurately represent the data returned, and you prefer working with the
            data as a pydantic model instead of as a dict of the response returned
            by  paystack before it is serialized with pydantic models, The original
            data can be accessed via `Response.raw`.

    Returns:
        A pydantic model containing the response gotten from paystack's server.
    """

    url = self._full_url("/refund")
    payload = {"transaction": transaction}
    optional_params = [
        ("amount", amount),
        ("currency", currency),
        ("customer_note", customer_note),
        ("merchant_note", merchant_note),
    ]
    payload = add_to_payload(optional_params, payload)
    return await self._handle_request(  # type: ignore
        HTTPMethod.POST,
        url,
        payload,
        response_data_model_class=alternate_model_class or Refund,
    )

get_refund(reference, alternate_model_class=None) async

Get details of a refund on your integration.

Parameters:

Name Type Description Default
reference str

Identifier for transaction to be refunded

 required
alternate_model_class type[PaystackDataModel] | None

A pydantic model class to use instead of the default pydantic model used by the library to present the data in the Response.data. The default behaviour of the library is to set Response.data to None if it fails to serialize the data returned from paystack with the model provided in the library. Providing a pydantic model class via this parameter overrides the library default model with the model class you provide. This can come in handy when the models in the library do not accurately represent the data returned, and you prefer working with the data as a pydantic model instead of as a dict of the response returned by paystack before it is serialized with pydantic models, The original data can be accessed via Response.raw.

 None

Returns:

Type Description
Response[Refund] | Response[PaystackDataModel]

A pydantic model containing the response gotten from paystack's server.
Source code in src/pypaystack2/sub_clients/async_clients/refunds.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
async def get_refund(
    self,
    reference: str,
    alternate_model_class: type[PaystackDataModel] | None = None,
) -> Response[Refund] | Response[PaystackDataModel]:
    """Get details of a refund on your integration.

    Args:
        reference: Identifier for transaction to be refunded
        alternate_model_class: A pydantic model class to use instead of the
            default pydantic model used by the library to present the data in
            the `Response.data`. The default behaviour of the library is to
            set  `Response.data` to `None` if it fails to serialize the data
            returned from paystack with the model provided in the library.
            Providing a pydantic model class via this parameter overrides
            the library default model with the model class you provide.
            This can come in handy when the models in the library do not
            accurately represent the data returned, and you prefer working with the
            data as a pydantic model instead of as a dict of the response returned
            by  paystack before it is serialized with pydantic models, The original
            data can be accessed via `Response.raw`.

    Returns:
        A pydantic model containing the response gotten from paystack's server.
    """

    url = self._full_url(f"/refund/{reference}")
    return await self._handle_request(  # type: ignore
        HTTPMethod.GET,
        url,
        response_data_model_class=alternate_model_class or Refund,
    )

get_refunds(reference=None, transaction=None, currency=None, pagination=50, page=1, start_date=None, end_date=None, alternate_model_class=None) async

Fetch refunds available on your integration.

Parameters:

Name Type Description Default
reference str | None

Identifier for transaction to be refunded

 None
transaction str | None

The transaction ID of the refunded transaction

 None
currency Currency | None

Any value from the Currency enum

 None
pagination int

Specifies how many records you want to retrieve per page. If not specified we use a default value of 50.

 50
page int

Specifies exactly what refund you want to page. If not specified we use a default value of 1.

 1
start_date str | None

A timestamp from which to start listing refund e.g. 2016-09-21

 None
end_date str | None

A timestamp at which to stop listing refund e.g. 2016-09-21

 None
alternate_model_class type[PaystackDataModel] | None

A pydantic model class to use instead of the default pydantic model used by the library to present the data in the Response.data. The default behaviour of the library is to set Response.data to None if it fails to serialize the data returned from paystack with the model provided in the library. Providing a pydantic model class via this parameter overrides the library default model with the model class you provide. This can come in handy when the models in the library do not accurately represent the data returned, and you prefer working with the data as a pydantic model instead of as a dict of the response returned by paystack before it is serialized with pydantic models, The original data can be accessed via Response.raw.

 None

Returns:

Type Description
Response[list[Refund]] | Response[PaystackDataModel]

A pydantic model containing the response gotten from paystack's server.
Source code in src/pypaystack2/sub_clients/async_clients/refunds.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
async def get_refunds(
    self,
    reference: str | None = None,
    transaction: str | None = None,
    currency: Currency | None = None,
    pagination: int = 50,
    page: int = 1,
    start_date: str | None = None,
    end_date: str | None = None,
    alternate_model_class: type[PaystackDataModel] | None = None,
) -> Response[list[Refund]] | Response[PaystackDataModel]:
    """Fetch refunds available on your integration.

    Args:
        reference: Identifier for transaction to be refunded
        transaction: The transaction ID of the refunded transaction
        currency: Any value from the ``Currency`` enum
        pagination: Specifies how many records you want to retrieve per page.
            If not specified we use a default value of 50.
        page: Specifies exactly what refund you want to page.
            If not specified we use a default value of 1.
        start_date: A timestamp from which to start listing refund e.g. 2016-09-21
        end_date: A timestamp at which to stop listing refund e.g. 2016-09-21
        alternate_model_class: A pydantic model class to use instead of the
            default pydantic model used by the library to present the data in
            the `Response.data`. The default behaviour of the library is to
            set  `Response.data` to `None` if it fails to serialize the data
            returned from paystack with the model provided in the library.
            Providing a pydantic model class via this parameter overrides
            the library default model with the model class you provide.
            This can come in handy when the models in the library do not
            accurately represent the data returned, and you prefer working with the
            data as a pydantic model instead of as a dict of the response returned
            by  paystack before it is serialized with pydantic models, The original
            data can be accessed via `Response.raw`.

    Returns:
        A pydantic model containing the response gotten from paystack's server.
    """
    if reference:
        warnings.warn(
            "'reference' is deprecated; use 'transaction'",
            DeprecationWarning,
            stacklevel=2,
        )
        transaction = reference
    url = self._full_url(f"/refund?perPage={pagination}")
    query_params = [
        ("transaction", transaction),
        ("currency", currency),
        ("page", page),
        ("start_date", start_date),
        ("end_date", end_date),
    ]
    url = append_query_params(query_params, url)
    return await self._handle_request(  # type: ignore
        HTTPMethod.GET,
        url,
        response_data_model_class=alternate_model_class or Refund,
    )

retry_refund(refund_id, refund_account, alternate_model_class=None) async

Retry a refund with a needs-attention status by providing the bank account details of a customer.

Parameters:

Name Type Description Default
refund_id str | int

The ID of the previously initiated refund

 required
refund_account RefundAccount

A pydantic model containing the customer's account details for refund.

 required
alternate_model_class type[PaystackDataModel] | None

A pydantic model class to use instead of the default pydantic model used by the library to present the data in the Response.data. The default behaviour of the library is to set Response.data to None if it fails to serialize the data returned from paystack with the model provided in the library. Providing a pydantic model class via this parameter overrides the library default model with the model class you provide. This can come in handy when the models in the library do not accurately represent the data returned, and you prefer working with the data as a pydantic model instead of as a dict of the response returned by paystack before it is serialized with pydantic models, The original data can be accessed via Response.raw.

 None

Returns:

Type Description
Response[Refund] | Response[PaystackDataModel]

A pydantic model containing the response gotten from paystack's server.
Source code in src/pypaystack2/sub_clients/async_clients/refunds.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
async def retry_refund(
    self,
    refund_id: str | int,
    refund_account: RefundAccount,
    alternate_model_class: type[PaystackDataModel] | None = None,
) -> Response[Refund] | Response[PaystackDataModel]:
    """Retry a refund with a needs-attention status by providing the bank
        account details of a customer.

    Args:
        refund_id: The ID of the previously initiated refund
        refund_account: A pydantic model containing the customer's account
            details for refund.
        alternate_model_class: A pydantic model class to use instead of the
            default pydantic model used by the library to present the data in
            the `Response.data`. The default behaviour of the library is to
            set  `Response.data` to `None` if it fails to serialize the data
            returned from paystack with the model provided in the library.
            Providing a pydantic model class via this parameter overrides
            the library default model with the model class you provide.
            This can come in handy when the models in the library do not
            accurately represent the data returned, and you prefer working with the
            data as a pydantic model instead of as a dict of the response returned
            by  paystack before it is serialized with pydantic models, The original
            data can be accessed via `Response.raw`.

    Returns:
        A pydantic model containing the response gotten from paystack's server.
    """
    url = self._full_url(f"/refund/retry_with_customer_details/{refund_id}")
    payload = {"refund_account_details": refund_account.model_dump()}
    return await self._handle_request(  # type: ignore
        HTTPMethod.POST,
        url,
        payload,
        response_data_model_class=alternate_model_class or Refund,
    )