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
ewalletsarray must specifyamountor all wallets must specifypercent.To create a full or partial refund of a payment that included FX, you must specify both the
amountandcurrencythat the customer will receive.Disputed payments cannot be fully refunded.
The code samples include successful requests (200), bad requests (400), and an unauthorized request (401). For a list of all error messages that appear due to bad requests, see Refund Errors and General Errors.
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
paymentobject that the refund is charged against. String starting with payment_.
reason
Description of the reason for the refund.
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, "merchant_ewallet": 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, "merchant_ewallet": 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, "merchant_ewallet": 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, "merchant_ewallet": 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, "merchant_ewallet": 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, "merchant_ewallet": 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, "merchant_ewallet": 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", "merchant_ewallet": null, "fx_rate": 0.01649582, "fixed_side": "buy" } }
Bad Request - Refund amount exceeds payment amount
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' --data-raw '{ "payment": "payment_20e5eb2c568be3ade1412c2a6ea5c234", "amount": 101, "metadata": { "merchant_defined": true }, "merchant_reference_id": "CA1234567", "reason": "Merchandise returned" } '{ "status": { "error_code": "ERROR_REFUND_AMOUNT_EXCEEDS_PAYMENT_AMOUNT", "status": "ERROR", "message": "The request tried to create a refund of payment that was collected to one or more wallets, but the amount of all refunds against this payment exceeded the amount of the payment. The request was rejected. Corrective action: None. Determine why an attempt was made to refund more money than was collected originally.", "response_code": "ERROR_REFUND_AMOUNT_EXCEEDS_PAYMENT_AMOUNT", "operation_id": "4a51bc0a-632e-4839-9588-7030dba77b7f" } }
Bad Request - Invalid amount
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' --data-raw '{ "payment": "payment_20e5eb2c568be3ade1412c2a6ea5c234", "amount": "101$", "metadata": { "merchant_defined": true }, "merchant_reference_id": "CA1234567", "reason": "Merchandise returned" } '{ "status": { "error_code": "INVALID_AMOUNT", "status": "ERROR", "message": "The request attempted an operation that requires an amount, but the amount was not found, was not a valid number or was out of bounds. The request was rejected. Corrective action: Use the correct amount.", "response_code": "INVALID_AMOUNT", "operation_id": "c18d4469-cb35-487a-a8af-6b8604cf1dc2" } }
Unauthorized
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": "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" } }