Skip to main content

Documentation

Create Refund

Refund of a payment.

The refund is credited against a specific payment. The money is returned to the payment method that was used for the payment, and the currency is the same as what was used in the payment.

If the action of a third party is not required, this method triggers the Refund Completed Webhook. This webhook contains the same information as the response.

The following asynchronous webhooks provide information about later changes to the refund:

Note

  • The payment must be in closed status.

  • If you are running this method in the sandbox and the payment method requires the action of a third party, run Complete Refund to complete your simulation.

  • To refund a payment where the funds are collected from two or more payment methods, see Create Group Refund.

  • Some payment methods do not support refunds. See List Payment Methods by Country.

  • All wallets in the ewallets array must specify amount or all wallets must specify percent.

  • To create a full or partial refund of a payment that included FX, you must specify both the amount and currency that the customer will receive.

  • Disputed payments cannot be fully refunded.

Parameters
Request Header Parameters
Request Body Parameters

    • amount

    • The amount of the refund. Decimal.

    • currency

    • The currency of the amount received by the original payment source. Three-letter ISO 4217 code.

    • ewallets

    • An array of objects that represent wallets that the refund is charged to.

    • payment

    • ID of the payment object that the refund is charged against. String starting with payment_.

    • reason

    • Description of the reason for the refund.

Response Parameters
Code Samples

    • .NET

      • using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var metadata = new
                {
                    merchant_defined = true
                };

                var requestObj = new
                {
                    payment = "payment_fdbae3bd097c9fffd88d7c3084f02ffe",
                    metadata,
                    merchant_reference_id = "CA1234567",
                    reason = "Merchandise returned",
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/refunds", 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 = {
      payment: 'payment_93186bb9a6d7ddfbae1d80f60285d736',
      metadata: {
        merchant_defined: true
      },
      merchant_reference_id: 'CA1234567',
      reason: 'Merchandise returned'
    };
    const result = await makeRequest('POST', '/v1/refunds', 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 = [
    "payment" => "payment_d99278076db1dbf210ace0790582ac78",
    "merchant_reference_id" => "CA1234567",
    "reason" => "Merchandise returned",
    "metadata" => array(
        "merchant_defined" => true
    )
];

try {
    $object = make_request('post', '/v1/refunds', $body);
    var_dump($object);
} catch(Exception $e) {
    echo "Error: $e";
}
?>

    • Python

      • from pprint import pprint

from utilities import make_request

create_refund_body = {
    "payment": "payment_7b3d9a457f108e8078f4a1a3fedf759c",
    "amount": 10,
    "metadata": {
        "merchant_defined": True
    },
    "reason": "Uncredited discount",
    "merchant_reference_id": "CA1234567"
}
response = make_request(method='post',
                        path='/v1/refunds',
                        body=create_refund_body)
pprint(response)

  • /v1/refunds

  • Full Refund Single Seller

  • curl -X post
https://sandboxapi.rapyd.net/v1/refunds
-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'
-d '{
    "payment": "payment_0dd0ddfe830c8fa0ba35e3d7370b2348",
    "metadata": {
        "merchant_defined": true
    },
    "merchant_reference_id": "CA1234567",
    "reason": "Merchandise returned"
}
'
  • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "4f55d7dc-f07c-4816-9710-7659fa204bec"
    },
    "data": {
        "id": "refund_4a6600012aad771cb927946d8e3f051d",
        "amount": 100,
        "payment": "payment_0dd0ddfe830c8fa0ba35e3d7370b2348",
        "currency": "USD",
        "failure_reason": "",
        "metadata": {
            "merchant_defined": true
        },
        "reason": "Merchandise returned",
        "status": "Completed",
        "receipt_number": 0,
        "created_at": 1608475698,
        "updated_at": 1608475698,
        "merchant_reference_id": "CA1234567",
        "payment_created_at": 1608474689,
        "payment_method_type": "us_visa_card",
        "ewallets": [
            {
                "ewallet": "ewallet_5b440aed9dbcb74a34f2893b9839670b",
                "amount": 100
            }
        ],
        "proportional_refund": true,
        "merchant_debited_amount": null,
        "merchant_debited_currency": null,
        "fx_rate": null,
        "fixed_side": null
    }
}

  • Full Refund Multiple Sellers

  • curl -X post
https://sandboxapi.rapyd.net/v1/refunds
-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'
-d '{
    "payment": "payment_b492538b7092fd143b15529ae2ab0451",
    "metadata": {
        "merchant_defined": true
    },
    "merchant_reference_id": "CA123y4567",
    "reason": "Merchandise returned"
}
'

  • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "562c50e1-9299-46a9-8e42-0019af28d506"
    },
    "data": {
        "id": "refund_74cb36d94a098901bb444ddf8189675d",
        "amount": 250,
        "payment": "payment_b492538b7092fd143b15529ae2ab0451",
        "currency": "USD",
        "failure_reason": "",
        "metadata": {
            "merchant_defined": true
        },
        "reason": "Merchandise returned",
        "status": "Completed",
        "receipt_number": 0,
        "created_at": 1608476360,
        "updated_at": 1608476360,
        "merchant_reference_id": "CA123y4567",
        "payment_created_at": 1608476197,
        "payment_method_type": "us_visa_card",
        "ewallets": [
            {
                "ewallet": "ewallet_5b440aed9dbcb74a34f2893b9839670b",
                "amount": 50
            },
            {
                "ewallet": "ewallet_f06ee6298f5f7671a7f21aaf66711554",
                "amount": 200
            }
        ],
        "proportional_refund": true,
        "merchant_debited_amount": null,
        "merchant_debited_currency": null,
        "fx_rate": null,
        "fixed_side": null
    }
}

  • Partial Refund Single Seller

  • curl -X post
https://sandboxapi.rapyd.net/v1/refunds
-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'
-d '{
    "payment": "payment_b1a1463d25c8e57aa1ad987fab984b60",
    "amount": 5.00,
    "metadata": {
        "merchant_defined": true
    },
    "merchant_reference_id": "CA123o567",
    "reason": "Uncredited discount"
}
'

  • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "ea128f1f-b480-440b-adee-96da91a0ed9d"
    },
    "data": {
        "id": "refund_4d8d941a54a35eb94b34c06fce5885fb",
        "amount": 5,
        "payment": "payment_b1a1463d25c8e57aa1ad987fab984b60",
        "currency": "USD",
        "failure_reason": "",
        "metadata": {
            "merchant_defined": true
        },
        "reason": "Uncredited discount",
        "status": "Completed",
        "receipt_number": 0,
        "created_at": 1608477112,
        "updated_at": 1608477112,
        "merchant_reference_id": "CA123o567",
        "payment_created_at": 1608477065,
        "payment_method_type": "us_visa_card",
        "ewallets": [
            {
                "ewallet": "ewallet_5b440aed9dbcb74a34f2893b9839670b",
                "amount": 5
            }
        ],
        "proportional_refund": true,
        "merchant_debited_amount": null,
        "merchant_debited_currency": null,
        "fx_rate": null,
        "fixed_side": null
    }
}

  • Non-Proportional Refund Multiple Sellers

  • curl -X post
https://sandboxapi.rapyd.net/v1/refunds
-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'
-d '{
    "payment": "payment_7a98328c6da659a181c16a594dae5d3d",
    "ewallets": [
        {
            "ewallet": "ewallet_f06ee6298f5f7671a7f21aaf66711554",
            "amount": 5
        }, 
        {
            "ewallet": "ewallet_5b440aed9dbcb74a34f2893b9839670b",
            "amount": 10
        }
    ],
    "metadata": {
        "merchant_defined": true
    },
    "merchant_reference_id": "CA1234op",
    "reason": "Uncredited discount"
}
'

  • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "47606004-0d8a-4ae5-8480-f86dd7d1b45a"
    },
    "data": {
        "id": "refund_1b4c22f67ddc416e7ab7bcede3a18b64",
        "amount": 15,
        "payment": "payment_7a98328c6da659a181c16a594dae5d3d",
        "currency": "USD",
        "failure_reason": "",
        "metadata": {
            "merchant_defined": true
        },
        "reason": "Uncredited discount",
        "status": "Completed",
        "receipt_number": 0,
        "created_at": 1608559262,
        "updated_at": 1608559262,
        "merchant_reference_id": "CA1234op",
        "payment_created_at": 1608559072,
        "payment_method_type": "us_visa_card",
        "ewallets": [
            {
                "ewallet": "ewallet_5b440aed9dbcb74a34f2893b9839670b",
                "amount": 10
            },
            {
                "ewallet": "ewallet_f06ee6298f5f7671a7f21aaf66711554",
                "amount": 5
            }
        ],
        "proportional_refund": false,
        "merchant_debited_amount": null,
        "merchant_debited_currency": null,
        "fx_rate": null,
        "fixed_side": null
    }
}

  • Refund One of Multiple Sellers

  • curl -X post
https://sandboxapi.rapyd.net/v1/refunds
-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'
-d '{
    "payment": "payment_55eec03849ba630c91ac09c3149c5816",
    "ewallets": [
        {
            "ewallet": "ewallet_f06ee6298f5f7671a7f21aaf66711554",
            "amount": 5
        }
    ],
    "metadata": {
        "merchant_defined": true
    },
    "merchant_reference_id": "CW1234567",
    "reason": "Uncredited discount"
}
'

  • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "91e73090-c293-4a4a-ba13-ca7df6c5e8bf"
    },
    "data": {
        "id": "refund_94f51775d57e81d153a60e292bba85d9",
        "amount": 5,
        "payment": "payment_55eec03849ba630c91ac09c3149c5816",
        "currency": "USD",
        "failure_reason": "",
        "metadata": {
            "merchant_defined": true
        },
        "reason": "Uncredited discount",
        "status": "Completed",
        "receipt_number": 0,
        "created_at": 1608560004,
        "updated_at": 1608560004,
        "merchant_reference_id": "CW1234567",
        "payment_created_at": 1608559497,
        "payment_method_type": "us_visa_card",
        "ewallets": [
            {
                "ewallet": "ewallet_f06ee6298f5f7671a7f21aaf66711554",
                "amount": 5
            }
        ],
        "proportional_refund": false,
        "merchant_debited_amount": null,
        "merchant_debited_currency": null,
        "fx_rate": null,
        "fixed_side": null
    }
}

  • Proportional Refund Multiple Sellers

  • curl -X post
https://sandboxapi.rapyd.net/v1/refunds
-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'
-d '{
    "payment": "payment_03410aab01ed7af34f30c2107bbd9bd5",
    "amount": 10.00,
    "metadata": {
        "merchant_defined": true
    },
    "merchant_reference_id": "REFUND-08OCT",
    "reason": "Uncredited discount"
}
'

  • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "7bc64fe3-a17d-423c-8567-ba6846a416cb"
    },
    "data": {
        "id": "refund_3c4e0a1b6b8738b04fb1b6785e75aa48",
        "amount": 10,
        "payment": "payment_03410aab01ed7af34f30c2107bbd9bd5",
        "currency": "USD",
        "failure_reason": "",
        "metadata": {
            "merchant_defined": true
        },
        "reason": "Uncredited discount",
        "status": "Completed",
        "receipt_number": 0,
        "created_at": 1608561483,
        "updated_at": 1608561483,
        "merchant_reference_id": "REFUND-08OCT",
        "payment_created_at": 1608561441,
        "payment_method_type": "us_visa_card",
        "ewallets": [
            {
                "ewallet": "ewallet_5b440aed9dbcb74a34f2893b9839670b",
                "amount": 2
            },
            {
                "ewallet": "ewallet_f06ee6298f5f7671a7f21aaf66711554",
                "amount": 8
            }
        ],
        "proportional_refund": true,
        "merchant_debited_amount": null,
        "merchant_debited_currency": null,
        "fx_rate": null,
        "fixed_side": null
    }
}

  • Refund from Multiple Sellers by Percentage

  • curl -X post
https://sandboxapi.rapyd.net/v1/refunds
-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'
-d '{
    "payment": "payment_2174a4518e108f39cba6e367f40a40a6",
    "ewallets": [
        {
            "ewallet": "ewallet_f06ee6298f5f7671a7f21aaf66711554",
            "percent": 1
        },
        {
            "ewallet": "ewallet_5b440aed9dbcb74a34f2893b9839670b",
            "percent": 2
        }
    ],
    "metadata": {
        "merchant_defined": true
    },
    "proportional_refund": true,
    "reason": "Refund for CK SB",
    "merchant_reference_id": "CA1234567"
}
'

  • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "540eadf7-a777-4b93-9153-5f840092859d"
    },
    "data": {
        "id": "refund_a09a2e16352f56a27f5937f87d0b8705",
        "amount": 7.5,
        "payment": "payment_2174a4518e108f39cba6e367f40a40a6",
        "currency": "USD",
        "failure_reason": "",
        "metadata": {
            "merchant_defined": true
        },
        "reason": "Refund for CK SB",
        "status": "Completed",
        "receipt_number": 0,
        "created_at": 1608567423,
        "updated_at": 1608567423,
        "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,
        "fx_rate": null,
        "fixed_side": null
    }
}

  • Refund of FX Payment

  • curl -X post
https://sandboxapi.rapyd.net/v1/refunds
-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'
-d '{
    "payment": "payment_84c5a05e4c66a6a4f71a21a1226b5375",
    "amount": 496,
    "currency": "EUR",
    "metadata": {
        "merchant_defined": true
    },
    "reason": "returned merchandise",
    "merchant_reference_id": "DB1234567"
}
'

  • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "83dba0c5-d7d2-44c0-b4ca-661e097b33c9"
    },
    "data": {
        "id": "refund_30cdc1684e49845433ecfd839301f540",
        "amount": 496,
        "payment": "payment_84c5a05e4c66a6a4f71a21a1226b5375",
        "currency": "EUR",
        "failure_reason": "",
        "metadata": {
            "merchant_defined": true
        },
        "reason": "returned merchandise",
        "status": "Completed",
        "receipt_number": 0,
        "created_at": 1673418649,
        "updated_at": 1673418649,
        "merchant_reference_id": "DB1234567",
        "payment_created_at": 1673357755,
        "payment_method_type": "de_visa_card",
        "ewallets": [
            {
                "ewallet": "ewallet_3801e782955b29955445586a2405a5db",
                "amount": 30068.22
            }
        ],
        "proportional_refund": true,
        "merchant_debited_amount": 30068.22,
        "merchant_debited_currency": "PHP",
        "fx_rate": 0.01649582,
        "fixed_side": "buy"
    }
}
In this section:

The number of seconds elapsed since the beginning of the Unix epoch, which was 00:00:00 GMT on January 1, 1970. 10-digit integer.