> ## Documentation Index > Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Refund > Use this API to initiate refunds. ## OpenAPI ````yaml /openapi/payments/v2022-09-01.yaml post /orders/{order_id}/refunds openapi: 3.0.0 info: version: '2022-09-01' title: Cashfree Payment Gateway APIs license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html contact: email: developers@cashfree.com name: API Support url: https://discord.com/invite/QdZkNSxXsB description: >- Cashfree's Payment Gateway APIs provide developers with a streamlined pathway to integrate advanced payment processing capabilities into their applications, platforms and websites. servers: - url: https://sandbox.cashfree.com/pg description: Sandbox server - url: https://api.cashfree.com/pg description: Production server security: [] tags: - name: Orders description: Collection of APIs to handle orders. - name: Payments description: Collection of APIs to handle payments. - name: Refunds description: Collection of APIs to handle refunds. - name: Settlements description: Collection of APIs to handle settlements. - name: Payment Links description: Collection of APIs to handle payment links. - name: Token Vault description: >- Collection of APIs to use Cashfree's token Vault. This helps you save cards and tokenize them in a PCI complaint manner. We support creation of network tokens which can be used across acquiring banks - name: softPOS description: Collection of APIs to manage softPOS' agent and order - name: Offers description: Collection of APIs to handle offers - name: Eligibility description: >- Collection of APIs to check eligibile entities - payment methods, offer, affordibility - name: Settlement Reconciliation description: Collection of APIs to handle settlements - name: PG Reconciliation description: Collection of APIs to handle reconciliation paths: /orders/{order_id}/refunds: post: tags: - Refunds summary: Create Refund description: Use this API to initiate refunds. operationId: PGOrderCreateRefund parameters: - $ref: '#/components/parameters/apiVersionHeader' - $ref: '#/components/parameters/xRequestIDHeader' - $ref: '#/components/parameters/xIdempotencyKeyHeader' - $ref: '#/components/parameters/orderIDParam' requestBody: $ref: '#/components/requestBodies/OrderCreateRefundRequest' responses: '200': description: Refund created content: application/json: schema: allOf: - $ref: '#/components/schemas/RefundEntity' examples: refunds_entity_example: $ref: '#/components/examples/refunds_entity_example' headers: x-api-version: $ref: '#/components/headers/x-api-version' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-retry: $ref: '#/components/headers/x-ratelimit-retry' x-ratelimit-type: $ref: '#/components/headers/x-ratelimit-type' x-request-id: $ref: '#/components/headers/x-request-id' x-idempotency-key: $ref: '#/components/headers/x-idempotency-key' x-idempotency-replayed: $ref: '#/components/headers/x-idempotency-replayed' '400': $ref: '#/components/responses/Response400' '401': $ref: '#/components/responses/Response401' '404': $ref: '#/components/responses/Response404' '409': $ref: '#/components/responses/Response409' '422': $ref: '#/components/responses/Response422' '429': $ref: '#/components/responses/Response429' '500': $ref: '#/components/responses/Response500' '502': $ref: '#/components/responses/Response502' deprecated: false security: - XClientID: [] XClientSecret: [] - XClientID: [] XPartnerAPIKey: [] - XClientID: [] XClientSignatureHeader: [] - XPartnerMerchantID: [] XPartnerAPIKey: [] components: parameters: apiVersionHeader: in: header name: x-api-version required: true description: API version to be used. Format is in YYYY-MM-DD schema: type: string description: API version to be used default: '2022-09-01' example: '2022-09-01' xRequestIDHeader: in: header name: x-request-id description: >- Request id for the API call. Can be used to resolve tech issues. Communicate this in your tech related queries to cashfree required: false schema: type: string example: 4dfb9780-46fe-11ee-be56-0242ac120002 xIdempotencyKeyHeader: in: header name: x-idempotency-key required: false description: > Idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors. Currently supported on all POST calls that uses x-client-id & x-client-secret. To use enable, pass x-idempotency-key in the request header. The value of this header must be unique to each operation you are trying to do. One example can be to use the same order_id that you pass while creating orders schema: type: string format: UUID example: 47bf8872-46fe-11ee-be56-0242ac120002 orderIDParam: name: order_id in: path required: true description: The id which uniquely identifies your order schema: type: string example: your-order-id requestBodies: OrderCreateRefundRequest: description: Request Body to Create Refunds required: true content: application/json: schema: $ref: '#/components/schemas/OrderCreateRefundRequest' schemas: RefundEntity: title: RefundEntity description: The refund entity type: object example: cf_payment_id: 918812 cf_refund_id: refund_1553338 refund_id: REF-123 order_id: c6G-QMcbm1848 entity: refund refund_amount: 100.81 refund_currency: INR refund_note: 'Refund for order #123' refund_status: SUCCESS refund_type: MERCHANT_INITIATED refund_splits: [] status_description: In Progress refund_arn: RF12312 metadata: option: myotpion created_at: '2021-07-25T08:57:52+05:30' processed_at: '2021-07-25T12:57:52+05:30' refund_charge: 0 refund_mode: STANDARD properties: cf_payment_id: type: integer format: int64 description: Cashfree Payments ID of the payment for which refund is initiated cf_refund_id: type: string description: Cashfree Payments ID for a refund order_id: type: string description: Merchant’s order Id of the order for which refund is initiated refund_id: type: string description: Merchant’s refund ID of the refund entity: type: string enum: - refund description: Type of object refund_amount: type: number description: Amount that is refunded refund_currency: type: string description: Currency of the refund amount refund_note: type: string description: Note added by merchant for the refund refund_status: type: string enum: - SUCCESS - PENDING - CANCELLED - ONHOLD description: >- This can be one of ["SUCCESS", "PENDING", "CANCELLED", "ONHOLD", "FAILED"] refund_arn: type: string description: The bank reference number for refund refund_charge: type: number description: Charges in INR for processing refund status_description: type: string description: Description of refund status metadata: nullable: true type: object description: >- Key-value pair that can be used to store additional information about the entity. Maximum 5 key-value pairs refund_splits: type: array items: $ref: '#/components/schemas/VendorSplit' refund_type: type: string enum: - PAYMENT_AUTO_REFUND - MERCHANT_INITIATED - UNRECONCILED_AUTO_REFUND description: >- This can be one of ["PAYMENT_AUTO_REFUND", "MERCHANT_INITIATED", "UNRECONCILED_AUTO_REFUND"] refund_mode: type: string enum: - STANDARD - INSTANT description: Method or speed of processing refund created_at: type: string description: Time of refund creation processed_at: type: string description: Time when refund was processed successfully refund_speed: $ref: '#/components/schemas/RefundSpeed' OrderCreateRefundRequest: title: OrderCreateRefundRequest description: create refund request object example: refund_amount: 1 refund_id: refund_00912 refund_note: refund note for reference refund_speed: STANDARD type: object properties: refund_amount: type: number format: double description: >- Amount to be refunded. Should be lesser than or equal to the transaction amount. (Decimals allowed) refund_id: type: string description: >- An unique ID to associate the refund with. Provie alphanumeric values minLength: 3 maxLength: 40 refund_note: type: string description: A refund note for your reference. minLength: 3 maxLength: 100 refund_speed: type: string enum: - STANDARD - INSTANT description: >- Speed at which the refund is processed. It's an optional field with default being STANDARD refund_splits: type: array items: $ref: '#/components/schemas/VendorSplit' required: - refund_amount - refund_id VendorSplit: title: VendorSplit description: >- Use to split order when cashfree's Easy Split is enabled for your account. type: object example: vendor_id: Vendor01 amount: 100.12 description: order amount should be more than equal to 100.12 properties: vendor_id: type: string description: Vendor id created in Cashfree system amount: type: number description: Amount which will be associated with this vendor percentage: type: number description: Percentage of order amount which shall get added to vendor account RefundSpeed: title: RefundSpeed description: How fast refund has to be proecessed type: object example: requested: STANDARD accepted: STANDARD processed: STANDARD message: Error message, if any properties: requested: type: string description: Requested speed of refund. accepted: type: string description: Accepted speed of refund. processed: type: string description: Processed speed of refund. message: type: string description: Error message, if any for refund_speed request BadRequestError: title: BadRequestError description: Invalid request received from client example: message: bad URL, please check API documentation code: request_failed type: invalid_request_error type: object properties: message: type: string code: type: string type: type: string enum: - invalid_request_error AuthenticationError: title: AuthenticationError description: Error if api keys are wrong example: message: authentication Failed code: request_failed type: authentication_error type: object properties: message: type: string code: type: string type: type: string description: authentication_error ApiError404: title: ApiError404 description: Error when resource requested is not found example: message: something is not found code: somethind_not_found type: invalid_request_error type: object properties: message: type: string code: type: string type: type: string enum: - invalid_request_error description: invalid_request_error ApiError409: title: ApiError409 description: duplicate request example: message: order with same id is already present code: order_already_exists type: invalid_request_error type: object properties: message: type: string code: type: string type: type: string enum: - invalid_request_error description: invalid_request_error IdempotencyError: title: IdempotencyError description: >- Error when idempotency fails. Different request body with the same idempotent key example: message: something is not found code: request_invalid type: idempotency_error type: object properties: message: type: string code: type: string type: type: string enum: - idempotency_error description: idempotency_error RateLimitError: title: RateLimitError description: Error when rate limit is breached for your api example: message: Too many requests from IP. Check headers code: request_failed type: rate_limit_error type: object properties: message: type: string code: type: string type: type: string enum: - rate_limit_error description: rate_limit_error ApiError: title: ApiError description: Error at cashfree's server example: message: internal Server Error code: internal_error type: api_error type: object properties: message: type: string code: type: string type: type: string enum: - api_error description: api_error ApiError502: title: ApiError502 description: Error when there is error at partner bank example: message: something is not found code: bank_processing_failure type: api_error type: object properties: message: type: string code: type: string description: > `bank_processing_failure` will be returned here to denote failure at bank. type: type: string enum: - api_error description: api_error examples: refunds_entity_example: summary: Refund Entity description: complete refund object value: - cf_payment_id: 918812 cf_refund_id: refund_1553338 refund_id: REF-123 order_id: c6G-QMcbm1848 entity: refund refund_amount: 100.81 refund_currency: INR refund_note: 'Refund for order #123' refund_status: SUCCESS refund_type: MERCHANT_INITIATED refund_splits: [] status_description: In Progress refund_arn: RF12312 metadata: null created_at: '2021-07-25T08:57:52+05:30' processed_at: '2021-07-25T12:57:52+05:30' refund_charge: 0 refund_mode: STANDARD headers: x-api-version: schema: type: string format: YYYY-MM-DD enum: - '2022-09-01' description: >- This header has the version of the API. The current version is `2022-09-01`. x-ratelimit-limit: schema: type: integer example: 200 description: Ratelimit set for your account for this API per minute x-ratelimit-remaining: schema: type: integer example: 2 description: >- Rate limit remaning for your account for this API in the next minute. Uses sliding window x-ratelimit-retry: schema: type: integer example: 4 description: | Contains number of seconds to wait if rate limit is breached - Is 0 if withing the limit - Is between 1 and 59 if breached x-ratelimit-type: schema: type: string enum: - app_id - ip example: ip description: > either ip or app_id - `ip` if making a call from the browser. True for api where you don't need `x-client-id` and `x-client-secret` - `app_id` for authenticated api calls i.e using `x-client-id` and `x-client-secret` x-request-id: schema: type: string example: some-req-id description: >- Request id for your api call. Is blank or null if no `x-request-id` is sent during the request x-idempotency-key: schema: type: string example: some-idem-id description: Idempotency key used during the request. Applicable for POST only x-idempotency-replayed: schema: type: string format: boolean example: 'true' description: |- In conjunction with `x-idempotency-key` this means - `true` if the response was replayed - `false` if the response has not been replayed responses: Response400: description: Bad request error content: application/json: schema: $ref: '#/components/schemas/BadRequestError' headers: x-api-version: $ref: '#/components/headers/x-api-version' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-retry: $ref: '#/components/headers/x-ratelimit-retry' x-ratelimit-type: $ref: '#/components/headers/x-ratelimit-type' x-request-id: $ref: '#/components/headers/x-request-id' x-idempotency-key: $ref: '#/components/headers/x-idempotency-key' x-idempotency-replayed: $ref: '#/components/headers/x-idempotency-replayed' Response401: description: Authentication Error content: application/json: schema: $ref: '#/components/schemas/AuthenticationError' headers: x-api-version: $ref: '#/components/headers/x-api-version' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-retry: $ref: '#/components/headers/x-ratelimit-retry' x-ratelimit-type: $ref: '#/components/headers/x-ratelimit-type' x-request-id: $ref: '#/components/headers/x-request-id' x-idempotency-key: $ref: '#/components/headers/x-idempotency-key' x-idempotency-replayed: $ref: '#/components/headers/x-idempotency-replayed' Response404: description: Resource Not found content: application/json: schema: $ref: '#/components/schemas/ApiError404' headers: x-api-version: $ref: '#/components/headers/x-api-version' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-retry: $ref: '#/components/headers/x-ratelimit-retry' x-ratelimit-type: $ref: '#/components/headers/x-ratelimit-type' x-request-id: $ref: '#/components/headers/x-request-id' x-idempotency-key: $ref: '#/components/headers/x-idempotency-key' x-idempotency-replayed: $ref: '#/components/headers/x-idempotency-replayed' Response409: description: Resource already present content: application/json: schema: $ref: '#/components/schemas/ApiError409' headers: x-api-version: $ref: '#/components/headers/x-api-version' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-retry: $ref: '#/components/headers/x-ratelimit-retry' x-ratelimit-type: $ref: '#/components/headers/x-ratelimit-type' x-request-id: $ref: '#/components/headers/x-request-id' x-idempotency-key: $ref: '#/components/headers/x-idempotency-key' x-idempotency-replayed: $ref: '#/components/headers/x-idempotency-replayed' Response422: description: Idempotency error content: application/json: schema: $ref: '#/components/schemas/IdempotencyError' headers: x-api-version: $ref: '#/components/headers/x-api-version' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-retry: $ref: '#/components/headers/x-ratelimit-retry' x-ratelimit-type: $ref: '#/components/headers/x-ratelimit-type' x-request-id: $ref: '#/components/headers/x-request-id' x-idempotency-key: $ref: '#/components/headers/x-idempotency-key' x-idempotency-replayed: $ref: '#/components/headers/x-idempotency-replayed' Response429: description: Rate Limit Error content: application/json: schema: $ref: '#/components/schemas/RateLimitError' headers: x-api-version: $ref: '#/components/headers/x-api-version' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-retry: $ref: '#/components/headers/x-ratelimit-retry' x-ratelimit-type: $ref: '#/components/headers/x-ratelimit-type' x-request-id: $ref: '#/components/headers/x-request-id' x-idempotency-key: $ref: '#/components/headers/x-idempotency-key' x-idempotency-replayed: $ref: '#/components/headers/x-idempotency-replayed' Response500: description: API related Error content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: x-api-version: $ref: '#/components/headers/x-api-version' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-retry: $ref: '#/components/headers/x-ratelimit-retry' x-ratelimit-type: $ref: '#/components/headers/x-ratelimit-type' x-request-id: $ref: '#/components/headers/x-request-id' x-idempotency-key: $ref: '#/components/headers/x-idempotency-key' x-idempotency-replayed: $ref: '#/components/headers/x-idempotency-replayed' Response502: description: Bank related Error content: application/json: schema: $ref: '#/components/schemas/ApiError502' headers: x-api-version: $ref: '#/components/headers/x-api-version' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-retry: $ref: '#/components/headers/x-ratelimit-retry' x-ratelimit-type: $ref: '#/components/headers/x-ratelimit-type' x-request-id: $ref: '#/components/headers/x-request-id' x-idempotency-key: $ref: '#/components/headers/x-idempotency-key' x-idempotency-replayed: $ref: '#/components/headers/x-idempotency-replayed' securitySchemes: XClientID: type: apiKey in: header name: x-client-id description: >- Client app ID. You can find your app id in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login/pg/developers/api-keys?env=prod). XClientSecret: type: apiKey in: header name: x-client-secret description: >- Client secret key. You can find your secret in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login/pg/developers/api-keys?env=prod). XPartnerAPIKey: type: apiKey in: header name: x-partner-apikey description: >- If you are partner and you are making an api call on behalf of a merchant XClientSignatureHeader: type: apiKey in: header name: x-client-signature description: >- Use this if you do not want to pass the secret key and instead want to use signature XPartnerMerchantID: type: apiKey in: header name: x-partner-merchantid description: >- If you are partner use this to specify the merchant id if you don't have the merchant client app id ````