Getting Refund List
Function: refund_list()
Purpose
This SDK function retrieves a paginated list of refund records from the system. Each refund entry contains key financial and operational information such as refund ID, status, amount, payment method, reference details, associated credit note, custom attributes, audit metadata, and pagination details. This operation is designed to support financial reporting, transaction reconciliation, and administrative oversight by providing a complete dataset of refunds stored in the platform.
Parameters
No parameters required.
Use Case
This function is commonly used in finance, billing, or reconciliation modules where users need to retrieve all refunds processed within the system. A typical scenario is when an accountant, finance officer, or automated reconciliation script needs to list all refunds to validate amounts, match them against payments or credit notes, generate refund reports, or audit financial adjustments. The SDK simplifies this by exposing a direct function that retrieves the list without requiring manual request construction or authentication handling. Both Python and PHP SDKs allow calling this list function easily, optionally supporting pagination parameters.
def refund_list():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = False
token_file_path = "shared_token.json"
file_token_mgr = FileTokenManager(token_file_path)
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(
request_token_dto=CommonData.get_request_token_dto(),
file_token_mgr=file_token_mgr
)
try:
response = exsited_sdk.refund.list()
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)Response
The function returns a structured list of refund objects along with pagination details. Each refund contains its unique identifiers, status, amount, payment method, processor, related credit note ID, custom attributes, and audit trail fields like created On and last Updated On. Pagination metadata helps the client iterate through large datasets. The SDK returns these values as structured objects or arrays, making them directly usable for UI rendering, reporting, or backend processing.
{
"refunds": [
{
"status": "STATUS_PLACEHOLDER",
"id": "REFUND_ID_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"reference": "REFERENCE_PLACEHOLDER",
"note": "NOTE_PLACEHOLDER",
"paymentMethod": "PAYMENT_METHOD_PLACEHOLDER",
"paymentProcessor": "PAYMENT_PROCESSOR_PLACEHOLDER",
"gatewayResponse": "GATEWAY_RESPONSE_PLACEHOLDER",
"creditNoteId": "CREDIT_NOTE_ID_PLACEHOLDER",
"customAttributes": [
{
"name": "CUSTOM_ATTRIBUTE_NAME_PLACEHOLDER",
"value": "CUSTOM_ATTRIBUTE_VALUE_PLACEHOLDER"
}
],
"version": "VERSION_PLACEHOLDER",
"createdBy": "CREATED_BY_PLACEHOLDER",
"createdOn": "CREATED_ON_PLACEHOLDER",
"lastUpdatedBy": "LAST_UPDATED_BY_PLACEHOLDER",
"lastUpdatedOn": "LAST_UPDATED_ON_PLACEHOLDER",
"uuid": "REFUND_UUID_PLACEHOLDER",
"date": "DATE_PLACEHOLDER"
}
],
"pagination": {
"records": RECORD_COUNT_PLACEHOLDER,
"limit": LIMIT_PLACEHOLDER,
"offset": OFFSET_PLACEHOLDER,
"previousPage": "PREVIOUS_PAGE_PLACEHOLDER",
"nextPage": "NEXT_PAGE_PLACEHOLDER"
}
}
Retrieving Refund Details
Function: refund_details()
Purpose
This function retrieves the details of a specific refund by using its unique refund ID. It provides full information about the refund, including its status, amount, payment method, credit note reference, and metadata.
Parameters
| Parameter | Type | Description |
|---|---|---|
| refund_id | String | Unique identifier of the refund to be retrieved. |
Use Case
The function is used to fetch and verify refund information for financial reconciliation or customer service purposes. It allows businesses to confirm refund status, check refunded amounts, validate payment methods, and track audit details such as who created or updated the refund record.
def refund_details():
SDKConfig.PRINT_REQUEST_DATA = False
SDKConfig.PRINT_RAW_RESPONSE = False
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
response = exsited_sdk.refund.details(id="REFUND_ID")
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)public function refundDetails()
{
$id = 'REFUND_ID';
try {
$response = $this->refundService->readDetails($id,'v3');
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}Response
The endpoint response returns complete refund details, including refund status, refund ID, amount, payment method, processor, related credit note, custom attributes, and version information. It also provides audit details such as who created and last updated the record, timestamps, and the unique UUID of the refund.
RefundDetailsDTO(
refund=RefundDataDTO(
status='STATUS',
id='REFUND_ID',
amount='NUMBER',
reference='REFUND_REFERENCE',
note='REFUND_NOTE',
paymentMethod='PAYMENT_METHOD',
paymentProcessor='PAYMENT_PROCESSOR',
gatewayResponse='EMPTY',
creditNoteId='CREDIT_NOTE_ID',
customAttributes=[
CustomAttributesDTO(
name='ATTRIBUTE_NAME',
value='EMPTY'
)
],
version='VERSION',
createdBy='CREATED_BY',
createdOn='TIMESTAMP',
lastUpdatedBy='UPDATED_BY',
lastUpdatedOn='TIMESTAMP',
uuid='UUID',
date='NULL'
)
){
"refund": {
"status": "STATUS",
"id": "REFUND_ID",
"amount": "NUMBER",
"reference": "REFUND_REFERENCE",
"note": "REFUND_NOTE",
"payment_method": "PAYMENT_METHOD",
"payment_processor": "PAYMENT_PROCESSOR",
"gateway_response": "EMPTY",
"credit_note_id": "CREDIT_NOTE_ID",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME",
"value": "EMPTY"
}
],
"version": "VERSION",
"created_by": "CREATED_BY",
"created_on": "TIMESTAMP",
"last_updated_by": "UPDATED_BY",
"last_updated_on": "TIMESTAMP",
"uuid": "UUID"
}
}Retrieving refund list of a particular account
Function : account_refund_list()
Purpose
This function retrieves the list of refunds associated with a specific account. It provides detailed information about each refund, including status, amount, payment method, linked credit notes, and audit details. The response also includes pagination data for navigating large result sets.
Parameters
| Attribute | Type | Description |
|---|---|---|
| account_id | String | Unique identifier of the account for which refunds are retrieved. |
Use Case
The function is used to fetch and review all refunds processed for a given account. It helps finance or support teams track refund transactions, verify refund details (such as method, processor, and credit note linkage), and manage historical refund records with proper pagination.
def account_refund_list():
SDKConfig.PRINT_REQUEST_DATA = False
SDKConfig.PRINT_RAW_RESPONSE = False
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
response = exsited_sdk.refund.account_refund_list(id="REFUND_ID")
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)public function accountRefundList()
{
$accountId = 'ACCOUNT_ID';
try {
$response = $this->refundService->readAccountRefunds($accountId,'v3');
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}Response
The API endpoint response includes a list of refund records with details such as refund status, ID, amount, payment information, credit note association, audit trail, and custom attributes. It also provides pagination details to navigate through refund records.
AccountRefundListDTO(
account=RefundListDTO(
refunds=[
RefundDataDTO(
status='STATUS',
id='REFUND_ID',
amount='NUMBER',
reference='EMPTY',
note='EMPTY',
paymentMethod='PAYMENT_METHOD',
paymentProcessor='PAYMENT_PROCESSOR',
gatewayResponse='EMPTY',
creditNoteId='CREDIT_NOTE_ID',
customAttributes=[
CustomAttributesDTO(
name='ATTRIBUTE_NAME',
value='EMPTY'
)
],
version='VERSION',
createdBy='CREATED_BY',
createdOn='TIMESTAMP',
lastUpdatedBy='EMPTY',
lastUpdatedOn='TIMESTAMP',
uuid='UUID',
date='NULL'
),
RefundDataDTO(
status='STATUS',
id='REFUND_ID',
amount='NUMBER',
reference='EMPTY',
note='REFUND_NOTE',
paymentMethod='PAYMENT_METHOD',
paymentProcessor='PAYMENT_PROCESSOR',
gatewayResponse='EMPTY',
creditNoteId='CREDIT_NOTE_ID',
customAttributes=[
CustomAttributesDTO(
name='ATTRIBUTE_NAME',
value='EMPTY'
)
],
version='VERSION',
createdBy='CREATED_BY',
createdOn='TIMESTAMP',
lastUpdatedBy='UPDATED_BY',
lastUpdatedOn='TIMESTAMP',
uuid='UUID',
date='NULL'
),
RefundDataDTO(
status='STATUS',
id='REFUND_ID',
amount='NUMBER',
reference='EMPTY',
note='REFUND_NOTE',
paymentMethod='PAYMENT_METHOD',
paymentProcessor='PAYMENT_PROCESSOR',
gatewayResponse='EMPTY',
creditNoteId='CREDIT_NOTE_ID',
customAttributes=[
CustomAttributesDTO(
name='ATTRIBUTE_NAME',
value='EMPTY'
)
],
version='VERSION',
createdBy='CREATED_BY',
createdOn='TIMESTAMP',
lastUpdatedBy='UPDATED_BY',
lastUpdatedOn='TIMESTAMP',
uuid='UUID',
date='NULL'
),
RefundDataDTO(
status='STATUS',
id='REFUND_ID',
amount='NUMBER',
reference='EMPTY',
note='REFUND_NOTE',
paymentMethod='PAYMENT_METHOD',
paymentProcessor='PAYMENT_PROCESSOR',
gatewayResponse='EMPTY',
creditNoteId='CREDIT_NOTE_ID',
customAttributes=[
CustomAttributesDTO(
name='ATTRIBUTE_NAME',
value='EMPTY'
)
],
version='VERSION',
createdBy='CREATED_BY',
createdOn='TIMESTAMP',
lastUpdatedBy='UPDATED_BY',
lastUpdatedOn='TIMESTAMP',
uuid='UUID',
date='NULL'
),
RefundDataDTO(
status='STATUS',
id='REFUND_ID',
amount='NUMBER',
reference='EMPTY',
note='REFUND_NOTE',
paymentMethod='PAYMENT_METHOD',
paymentProcessor='PAYMENT_PROCESSOR',
gatewayResponse='EMPTY',
creditNoteId='CREDIT_NOTE_ID',
customAttributes=[
CustomAttributesDTO(
name='ATTRIBUTE_NAME',
value='EMPTY'
)
],
version='VERSION',
createdBy='CREATED_BY',
createdOn='TIMESTAMP',
lastUpdatedBy='UPDATED_BY',
lastUpdatedOn='TIMESTAMP',
uuid='UUID',
date='NULL'
)
],
pagination=PaginationDTO(
records=NUMBER,
limit=NUMBER,
offset=NUMBER,
previousPage='EMPTY',
nextPage='NULL'
)
)
){
"account": {
"refunds": [
{
"status": "STATUS",
"id": "REFUND_ID",
"amount": "NUMBER",
"reference": "EMPTY",
"note": "REFUND_NOTE",
"payment_method": "PAYMENT_METHOD",
"payment_processor": "PAYMENT_PROCESSOR",
"gateway_response": "EMPTY",
"credit_note_id": "CREDIT_NOTE_ID",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME",
"value": "EMPTY"
}
],
"version": "VERSION",
"created_by": "CREATED_BY",
"created_on": "TIMESTAMP",
"last_updated_by": "UPDATED_BY",
"last_updated_on": "TIMESTAMP",
"uuid": "UUID"
},
{
"status": "STATUS",
"id": "REFUND_ID",
"amount": "NUMBER",
"reference": "EMPTY",
"note": "REFUND_NOTE",
"payment_method": "PAYMENT_METHOD",
"payment_processor": "PAYMENT_PROCESSOR",
"gateway_response": "EMPTY",
"credit_note_id": "CREDIT_NOTE_ID",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME",
"value": "EMPTY"
}
],
"version": "VERSION",
"created_by": "CREATED_BY",
"created_on": "TIMESTAMP",
"last_updated_by": "UPDATED_BY",
"last_updated_on": "TIMESTAMP",
"uuid": "UUID"
}
],
"pagination": {
"records": "NUMBER",
"limit": "NUMBER",
"offset": "NUMBER",
"previous_page": "URL",
"next_page": "URL"
}
}
}
Removing a Refund Record
Function : refund_delete()
Purpose
This function delete a specific refund from the system using its unique refund ID. It ensures that invalid or unnecessary refund records can be permanently removed.
Parameters
| Parameter | Type | Description |
|---|---|---|
| refund_id | String | The unique identifier of the refund to be deleted. |
Use Case
The function is used when a refund needs to be deleted, for example, if a refund was mistakenly created or is no longer applicable. By calling this function, the authenticated user can remove the refund record directly from the system, ensuring accurate and consistent financial records.
def refund_delete():
SDKConfig.PRINT_REQUEST_DATA = False
SDKConfig.PRINT_RAW_RESPONSE = False
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
response = exsited_sdk.refund.delete(id="REFUND_ID")
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)public function testDelete()
{
$id = 'REFUND_ID';
try {
$response = $this->refundService->delete($id,'v3');
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}Response
The function returns a confirmation of the deletion operation. On success, it provides a response indicating that the refund was deleted successfully, along with a 204 status code showing that no additional content is returned.
{
"success": True,
"status_code": 204
}nullCreating a refund for a specific credit note
Function : refund_create()
Purpose
This function creates a new refund against a specific credit note by providing refund details such as amount, reference, note, and payment method.
Parameters
| Parameter | Type | Description |
|---|---|---|
| credit_note_id | String | The credit note ID against which the refund is created. |
Use Case
The function is used when a refund needs to be created for a customer against a credit note. For example, if a customer has returned items or requires reimbursement, this function records the refund details and links them with the respective credit note, ensuring proper financial reconciliation.
def refund_create():
SDKConfig.PRINT_REQUEST_DATA = False
SDKConfig.PRINT_RAW_RESPONSE = False
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
request_data = RefundDetailsDTO(refund=RefundDataDTO(
date="TIMESTAMP",
amount="NUMBER",
reference="REFERENCE_ID",
note="STRING_VALUE",
paymentMethod="PAYMENT_METHOD",
paymentProcessor="PAYMENT_PROCESSOR"))
response = exsited_sdk.refund.create(cn_id='CREDIT_NOTE_ID', request_data=request_data)
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)public function testCreate()
{
$creditNotesId = 'CREDIT_NOTE_ID';
$params = [
"refund" => [
"date" => "TIMESTAMP",
"amount" => "NUMBER",
"reference" => "REFERENCE_ID",
"note" => "STRING_VALUE",
"payment_method" => "PAYMENT_METHOD",
"payment_processor" => "PAYMENT_PROCESSOR"
]
];
try {
$response = $this->refundService->create($creditNotesId, $params, 'API_VERSION');
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}Response
The SDK function response returns the details of the newly created refund, including its status, unique refund ID, amount, reference, payment method, payment processor, and metadata such as creation time and UUID. It also includes custom attributes for additional tracking and versioning information.
RefundDetailsDTO(
refund=RefundDataDTO(
status='STATUS',
id='REFUND_ID',
amount='AMOUNT',
reference='REFERENCE_ID',
note='STRING_VALUE',
paymentMethod='PAYMENT_METHOD',
paymentProcessor='PAYMENT_PROCESSOR',
gatewayResponse='GATEWAY_RESPONSE',
creditNoteId='CREDIT_NOTE_ID',
customAttributes=[
CustomAttributesDTO(
name='CUSTOM_ATTRIBUTE_NAME',
value='CUSTOM_ATTRIBUTE_VALUE'
)
],
version='VERSION',
createdBy='CREATED_BY',
createdOn='CREATED_TIMESTAMP',
lastUpdatedBy='LAST_UPDATED_BY',
lastUpdatedOn='LAST_UPDATED_TIMESTAMP',
uuid='UUID',
date='REFUND_DATE'
)
){
"refund": {
"status": "STATUS",
"id": "REFUND_ID",
"amount": "NUMBER",
"reference": "REFERENCE_ID",
"note": "EMPTY",
"payment_method": "PAYMENT_METHOD",
"payment_processor": "PAYMENT_PROCESSOR",
"gateway_response": "EMPTY",
"credit_note_id": "CREDIT_NOTE_ID",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME",
"value": "EMPTY"
}
],
"version": "VERSION",
"created_by": "CREATED_BY",
"created_on": "TIMESTAMP",
"last_updated_by": "EMPTY",
"last_updated_on": "TIMESTAMP",
"uuid": "UUID"
}
}Update Refund Details
Function : refund_update()
Purpose
This SDK function updates an existing refund record in the system. It allows modifying important refund information such as refund amount, reference number, note, payment method, and processor details. This operation is essential when correcting financial records, adding missing details, or adjusting previously entered refund information to maintain accurate and auditable financial data.
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Required. The unique identifier of the refund to be updated. |
Use Case
This function is used when a refund entry needs to be corrected or updated after creation. For example, a finance officer may need to update the refund reference to match accounting records, adjust the refund amount due to reconciliation, or modify internal notes for audit purposes. The SDK provides a straightforward way to perform this update by constructing a request data object and passing it to the update function, which automatically handles authentication and formatting.
def refund_update():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = False
token_file_path = "shared_token.json"
file_token_mgr = FileTokenManager(token_file_path)
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(
request_token_dto=CommonData.get_request_token_dto(),
file_token_mgr=file_token_mgr
)
try:
request_data = RefundDetailsDTO(refund=RefundDataDTO(
amount="10.00",
reference="REF-123",
note="NOTE",
))
response = exsited_sdk.refund.refund_update(return_id='ID', request_data=request_data)
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)Response
The function returns the full updated refund object, containing both the newly updated fields and unchanged existing data. This includes identifiers, refund amount, reference, note, payment method, processor, credit note linkage, custom attributes, version number, audit metadata, and UUID. The SDK formats the response into structured objects or arrays, making the updated data ready for immediate use in workflows, logs, dashboards, or audit processing.
{
"refund": {
"status": "STATUS_PLACEHOLDER",
"id": "REFUND_ID_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"reference": "REFERENCE_PLACEHOLDER",
"note": "NOTE_PLACEHOLDER",
"paymentMethod": "PAYMENT_METHOD_PLACEHOLDER",
"paymentProcessor": "PAYMENT_PROCESSOR_PLACEHOLDER",
"gatewayResponse": "GATEWAY_RESPONSE_PLACEHOLDER",
"creditNoteId": "CREDIT_NOTE_ID_PLACEHOLDER",
"customAttributes": [
{
"name": "CUSTOM_ATTRIBUTE_NAME_PLACEHOLDER",
"value": "CUSTOM_ATTRIBUTE_VALUE_PLACEHOLDER"
}
],
"version": "VERSION_PLACEHOLDER",
"createdBy": "CREATED_BY_PLACEHOLDER",
"createdOn": "CREATED_ON_PLACEHOLDER",
"lastUpdatedBy": "LAST_UPDATED_BY_PLACEHOLDER",
"lastUpdatedOn": "LAST_UPDATED_ON_PLACEHOLDER",
"uuid": "REFUND_UUID_PLACEHOLDER",
"date": "DATE_PLACEHOLDER"
}
}