---
updatedAt: 2026-08-31T21:17:44.000Z
agentTools:
projectIndex: https://docs.myfatoorah.com/llms.txt
---
# Create Refund
Creates a total or partial refund for a successful payment.
The refund can be distributed between the Vendor and one or more Suppliers, provided that the suppliers are associated with the referenced payment.
### Refund Request Responsibility
Please make sure to send one refund request each time, to avoid duplicate partial refund requests (You need to handle this from your system front-end side).
Moreover, Kindly note that the refund request responsibility is on the vendor side not on MyFatoorah Side.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Myfatoorah Api V3"
},
"servers": [
{
"url": "https://apitest.myfatoorah.com"
}
],
"paths": {
"/v3/refunds": {
"post": {
"responses": {
"201": {
"description": "Refund Created Successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"IsSuccess": {
"type": "boolean",
"description": "Indicates if the request was successful."
},
"Message": {
"type": "string",
"description": "Response message associated with the request."
},
"ValidationErrors": {
"type": "array",
"items": {
"properties": {
"Name": {
"type": "string",
"description": "Name of the field with validation error."
},
"Error": {
"type": "string",
"description": "Description of the validation error."
}
},
"type": "object"
}
},
"Data": {
"type": "object",
"properties": {
"Refund": {
"type": "object",
"properties": {
"Id": {
"type": "string",
"description": "Unique identifier of the refund, which can be used later to inquire about the refund status."
},
"Reference": {
"type": "string",
"description": "The refund reference generated by MyFatoorah for following up with the finance team."
},
"Status": {
"type": "string",
"description": "Current status of the refund. It will initially be \"Pending\". \nYou can rely on the Refund Status Changed webhook once the refund status is updated."
},
"InvoiceId": {
"type": "string",
"description": "The InvoiceId of the refunded amount."
},
"ExternalIdentifier": {
"type": "string",
"description": "External identifier provided in the request."
},
"CreationDate": {
"type": "string",
"description": "Date and time when the refund was created."
},
"RefundDate": {
"type": "string",
"description": "Date and time when the refund was completed. This will be empty while the refund is pending. "
},
"RRN": {
"type": "string",
"description": "Refund Reference Number that the customer can use to check the refund with their bank. It will be empty initially."
},
"Comment": {
"type": "string"
},
"VendorComment": {
"type": "string",
"description": "Comment provided in the refund request."
}
},
"description": "Contains the created refund details."
},
"Amount": {
"type": "object",
"properties": {
"BaseCurrency": {
"type": "string",
"description": "Base currency of the account"
},
"ValueInBaseCurrency": {
"type": "number",
"description": "Total refund amount in the base currency."
},
"Distribution": {
"type": "object",
"properties": {
"Vendor": {
"type": "number",
"description": "Amount that will be deducted from the vendor for the refund."
},
"Suppliers": {
"type": "array",
"items": {
"properties": {
"Code": {
"type": "string",
"description": "Supplier code. "
},
"Amount": {
"type": "number",
"description": "Amount refunded by the supplier."
}
},
"type": "object"
},
"description": "Amount that will be deducted from the suppliers for the refund."
}
}
}
},
"description": "Contains the refund amount and its distribution."
},
"ReferencedInvoice": {
"type": "object",
"properties": {
"Id": {
"type": "string",
"description": "Id of the original invoice."
},
"Reference": {
"type": "string",
"description": "Reference number of the original invoice. "
},
"ExternalIdentifier": {
"type": "string",
"description": "External identifier of the original invoice. "
},
"PaymentMethod": {
"type": "string",
"description": "Payment method used for the original payment. "
},
"BaseCurrency": {
"type": "string",
"description": "The base currency of your account (e.g., KWD)."
},
"ValueInBaseCurrency": {
"type": "string",
"description": "The total value of the original invoice in base currency."
},
"RemainingValueInBaseCurrency": {
"type": "string",
"description": "The remaining amount in base currency after the refund."
}
},
"description": "Contains details of the original invoice."
}
}
}
}
},
"examples": {
"Refund for Vendor Only": {
"summary": "Refund for Vendor Only",
"value": {
"IsSuccess": true,
"Message": "Refund Created Successfully",
"ValidationErrors": null,
"Data": {
"Refund": {
"Id": "309962",
"Reference": "2026002049",
"Status": "Pending",
"InvoiceId": "7099410",
"ExternalIdentifier": "test-external",
"CreationDate": "2026-08-24T00:32:26.9845805+03:00",
"RefundDate": "",
"RRN": "",
"Comment": "",
"VendorComment": "Comment"
},
"Amount": {
"BaseCurrency": "KWD",
"ValueInBaseCurrency": 1,
"Distribution": {
"Vendor": 1,
"Suppliers": []
}
},
"ReferencedInvoice": {
"Id": "7099311",
"Reference": "2026007750",
"ExternalIdentifier": "",
"PaymentMethod": "VISA/MASTER",
"BaseCurrency": "KWD",
"ValueInBaseCurrency": "200.000",
"RemainingValueInBaseCurrency": "141.000"
}
}
}
},
"Refund for an Invoice with Suppliers": {
"summary": "Refund for an Invoice with Suppliers",
"value": {
"IsSuccess": true,
"Message": "Refund Created Successfully",
"ValidationErrors": null,
"Data": {
"Refund": {
"Id": "309964",
"Reference": "2026002051",
"Status": "Pending",
"InvoiceId": "7099439",
"ExternalIdentifier": "test-external",
"CreationDate": "2026-08-24T01:13:23.4168450+03:00",
"RefundDate": "",
"RRN": "",
"Comment": "",
"VendorComment": "Comment"
},
"Amount": {
"BaseCurrency": "KWD",
"ValueInBaseCurrency": 15,
"Distribution": {
"Vendor": 1,
"Suppliers": [
{
"Code": 2,
"Amount": 14
}
]
}
},
"ReferencedInvoice": {
"Id": "7099436",
"Reference": "2026007764",
"ExternalIdentifier": "customer-ref",
"PaymentMethod": "GooglePay",
"BaseCurrency": "KWD",
"ValueInBaseCurrency": "100.000",
"RemainingValueInBaseCurrency": "25.000"
}
}
}
}
}
}
}
}
},
"parameters": [],
"summary": "Create Refund",
"operationId": "post_v3-refunds",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"PaymentId": {
"type": "string",
"description": "The paymentId for which the refund will be created. "
},
"Amount": {
"type": "number",
"description": "The amount to be refunded"
},
"ExternalIdentifier": {
"type": "string",
"description": "External data associated with the refund, which will be received in the webhook."
},
"SupplierRefundedAmount": {
"type": "array",
"items": {
"properties": {
"Code": {
"type": "string",
"description": "The supplier code."
},
"Amount": {
"type": "number",
"description": "This is the amount that will be deducted from the supplier in the refund process. It will be part form the total amount."
}
},
"type": "object"
},
"description": "Specifies the refund amount allocated to each supplier (if a supplier participated in the payment)."
},
"Comment": {
"type": "string",
"description": "Extra comments for your reference"
},
"ServiceChargeOnCustomer": {
"type": "boolean",
"description": "Determine whether the customer will be charged for the service fees or not. Service fees are charged by MyFatoorah."
}
},
"required": [
"PaymentId",
"Amount"
]
},
"examples": {
"Refund for Vendor Only": {
"summary": "Refund for Vendor Only",
"value": {
"PaymentId": "07077099311375613873",
"ExternalIdentifier": "test-external",
"Comment": "Comment",
"Amount": 1
}
},
"Refund for an Invoice with Suppliers": {
"summary": "Refund for an Invoice with Suppliers",
"value": {
"PaymentId": "07077099436375623874",
"ExternalIdentifier": "test-external",
"Comment": "Comment",
"Amount": 15,
"SupplierRefundedAmount": [
{
"Code": 2,
"Amount": 14
}
]
}
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerToken": {
"type": "http",
"scheme": "bearer",
"x-default": "SK_KWT_vVZlnnAqu8jRByOWaRPNId4ShzEDNt256dvnjebuyzo52dXjAfRx2ixW5umjWSUx"
}
}
},
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true
},
"security": [
{
"bearerToken": []
}
]
}
```