--- title: "Update Refund" source_url: https://docs.rapyd.net/en/update-refund.html lang: en --- # Update Refund Change or modify the metadata in a `refund` object. This method triggers the [Refund Updated Webhook](https://docs.rapyd.net/en/refund-updated-webhook.md "Refund Updated Webhook"). This webhook contains the same information as the response. > **Note:** > > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Refund Errors](https://docs.rapyd.net/en/refund-errors.md "Refund Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Body Parameters - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). ### Request Path Parameters - - refund - ID of the `refund` object you want to update. String starting with **refund_**. ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Response Parameters - - amount - Amount of the refund, in units defined by `currency` in the original payment. - - created_at - Time of creation of this refund, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - currency - The currency of the amount received by the original payment source. Three-letter ISO 4217 code. - - ewallets - Array of objects that define the allocation of the refund to multiple wallets. - - ewallet - ID of the wallet, a string starting with **ewallet_**. - - amount - The amount refunded to this wallet. Relevant when `percentage` is not set. - - percentage - The percentage of this payment refunded to this wallet. Relevant when `amount` is not set. - - failure_code - Indicates the reason that the refund failed. See [Card Network Errors](https://docs.rapyd.net/en/card-network-errors.md "Card Network Errors"). - - failure_reason - Indicates the reason that the refund failed. One of the following: - **lost_or_stolen_card** - **expired_or_canceled_card** - **unknown** - Empty string - - fixed_side - Indicates which side of the transaction the FX rate is fixed for. Relevant for refunds with foreign exchange. One of the following values: - **buy** - **sell** - - fx_rate - Exchange rate for the transaction. - When `fixed_side` is **buy**, `fx_rate` is the buy rate. - When `fixed_side` is **sell**, `fx_rate` is the sell rate. Decimal number as string. Relevant to refunds with foreign exchange. - - id - ID of the `refund` object. String starting with **refund_**. - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - merchant_debited_amount - Amount debited from the merchant. Relevant to refunds with foreign exchange. - - merchant_debited_currency - Indicates the currency that is debited from the merchant. Three-letter ISO 4217 code. Relevant to refunds with foreign exchange. - - merchant_ewallet - As a Payment Facilitator (PayFac), you can create a card payment and direct the funds that the sub-merchant collects to your client wallet. Relevant to a [PayFac](https://docs.rapyd.net/en/rapyd-payfac-integration-guide.md "Rapyd PayFac Integration Guide"). - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - payment - ID of the `payment` object that the refund is credited against. String starting with **payment_**. - - payment_created_at - Time that the original payment was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - payment_method_type - The original payment method type. Use [List Payment Methods by Country](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country") for a list of supported types for a country. - - proportional_refund - Indicates whether the refund was returned in proportion to the amounts received by the wallets in the payment. Relevant to a refund for a payment split among multiple wallets. - - reason - Description of the reason for the refund, provided by the merchant. - - receipt_number - Number of the receipt for the refund, provided by the merchant. - - status - Indicates the status of the refund operation. One of the following values: - **Canceled** - The merchant canceled the refund. - **Completed** - The refund was complete. - **Error** - The refund failed since the payment object on which the refund is based is not in **closed** status. - **Rejected** - The refund was rejected by the specific payment processor for this payment. - **Pending** - The request created a refund object on the Rapyd platform, but the refund is not yet complete. For example, the refund is for a payment method that requires a customer action, such as cash, bank redirect or bank transfer. - - updated_at - Time that this refund was last updated, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). ### Code Samples - - .NET - ```csharp using System; using System.Text.Json; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string refund = "refund_f988b426b60820c5ec9d9f218a9d105b"; var metadata = new { merchant_defined = "updated" }; var requestObj = new { metadata }; string request = JsonSerializer.Serialize(requestObj); string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/refunds/{refund}", request); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ```javascript const makeRequest = require('/utilities').makeRequest; async function main() { try { const body = { metadata: { merchant_defined: 'updated' } }; const result = await makeRequest( 'POST', '/v1/refunds/refund_85638a7e05557459c9e3ba971c03bf16', body ); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); $body = [ "metadata"=> array( "merchant_defined"=> "updated" ) ]; try { $object = make_request('post', '/v1/refunds/refund_687ef65e1812fbd7a59e85b1d9e42a03', $body); var_dump($object); } catch(Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request refund = "refund_126f3f657f7014a4f21f0cb2e47e7cdc" update_refund_body = { "metadata": "updated" } response = make_request(method='post', path=f'/v1/refunds/{refund}', body=update_refund_body) pprint(response) ``` - /v1/refunds/:refund - Update Refund - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/refunds/refund_ca79cdb54e1df72662e1e1d9c77a34c1' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "metadata": { "area": "local" } }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "6fa9a8d7-9cdc-4190-8d4a-f76eeedddd4e" }, "data": { "id": "refund_ca79cdb54e1df72662e1e1d9c77a34c1", "amount": 1000, "payment": "payment_f0e0ae0b35f7d69e41d59fde0c71a3b3", "currency": "BRL", "failure_reason": "", "metadata": { "area": "local" }, "reason": "Merchandise returned", "status": "Pending", "receipt_number": 0, "created_at": 1763555341, "updated_at": 1763555371, "merchant_ewallet": null, "merchant_reference_id": "2025-11-19aaa", "payment_created_at": 1763555312, "payment_method_type": "br_pix_ewallet", "ewallets": [ { "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861", "amount": 1000 } ], "proportional_refund": true, "merchant_debited_amount": null, "merchant_debited_currency": null, "fx_rate": null, "fixed_side": null } } ``` - Bad Request - Field cannot be updated - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/refunds/refund_a09a2e16352f56a27f5937f87d0b8705' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "amount": "99" }' ``` - ```json { "status": { "error_code": "ERROR_UPDATE_REFUND_FIELD_NOT_UPDATABLE", "status": "ERROR", "message": "The request tried to update a refund, but the field cannot be updated. The request was rejected. Corrective action: Update only the 'metadata' field.", "response_code": "ERROR_UPDATE_REFUND_FIELD_NOT_UPDATABLE", "operation_id": "12164632-587b-407e-8ee3-49c41c827b15" } } ```