Update Refund

Change or modify the metadata in a refund object.

This method triggers the Refund Updated webhook. This webhook contains the same information as the response.

Note

Parameters

Request Body Parameters

- metadata
- A JSON object defined by the client. See Metadata.

Request Path Parameters

- refund
- ID of the refund object you want to update. String starting with refund_.

Request Header Parameters

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.
- 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_reason
- Indicates the reason that the refund failed. One of the following:
  - lost_or_stolen_card
  - expired_or_canceled_card
  - unknown
- 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.
- metadata
- A JSON object defined by the client. See 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.
- payment_method_type
- The original payment method type. Use 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:
  - 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.

Code Samples

.NET

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

const makeRequest = require('<path-to-your-utility-file>/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
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/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

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 -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 '{
    "metadata": {
      	"merchant_defined": "updated"
   	}
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "c9ff9613-bbb9-4be3-87a0-4cb434ff1f5c"
    },
    "data": {
        "id": "refund_a09a2e16352f56a27f5937f87d0b8705",
        "amount": 7.5,
        "payment": "payment_2174a4518e108f39cba6e367f40a40a6",
        "currency": "USD",
        "failure_reason": "",
        "metadata": {
            "merchant_defined": "updated"
        },
        "reason": "Refund for CK SB",
        "status": "Pending",
        "receipt_number": 0,
        "created_at": 1608567423,
        "updated_at": 1608568133,
        "merchant_reference_id": "CA1234567",
        "payment_created_at": 1608567298,
        "payment_method_type": "us_visa_card",
        "ewallets": [
            {
                "ewallet": "ewallet_5b440aed9dbcb74a34f2893b9839670b",
                "amount": 5
            },
            {
                "ewallet": "ewallet_f06ee6298f5f7671a7f21aaf66711554",
                "amount": 2.5
            }
        ],
        "proportional_refund": false,
        "merchant_debited_amount": null,
        "merchant_debited_currency": null,
        "merchant_ewallet": null,
        "fx_rate": null,
        "fixed_side": null
    }
}

Bad Request - Field cannot be updated

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"
}
'

{
    "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"
    }
}

Unauthorized

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 '{
    "metadata": {
      	"merchant_defined": "updated"
   	}
}
'

{
    "status": {
        "error_code": "UNAUTHENTICATED_API_CALL",
        "status": "ERROR",
        "message": "The request was rejected due to an authentication issue. Corrective action: Check the status of your account in the 'Account Details' page of the Client Portal.",
        "response_code": "UNAUTHENTICATED_API_CALL",
        "operation_id": "034ff9bc-e27c-405b-8f8d-437becbc2358"
    }
}

In this section:

Documentation