--- title: "Create Group Refund" source_url: https://docs.rapyd.net/en/create-group-refund.html lang: en --- # Create Group Refund Refund a group payment when the `status` of the group payment is **closed**. The refund is credited against a specific group payment. The money is returned to the payment methods that were used for the payment. If the action of a third party is not required, this method triggers the **Refund Completed** webhook for each payment method. The following asynchronous webhooks provide information about later changes to the refund for each payment method: - [Refund Completed Webhook](https://docs.rapyd.net/en/refund-completed-webhook.md "Refund Completed Webhook") - [Refund Rejected Webhook](https://docs.rapyd.net/en/refund-rejected-webhook.md "Refund Rejected Webhook") ### Parameters ### 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). ### Request Body Parameters - - amount - The amount of the refund, in the currency of the group payment. Decimal. If this parameter is omitted, the entire group payment is refunded. - - group_payment - ID of the group payment that the refund is charged against. String starting with **gp_**. ### Response Parameters - - amount - Amount of the group payment, in units defined by `currency`. - - amount_to_replace - Indicates the total amount of failed payments that have not been replaced. - - cancel_reason - Reason for cancellation of the group payment. - - country - Country where the payment methods are supported. Two-letter ISO 3166-1 ALPHA-2 code. - - currency - Currency of the payments. Three-letter ISO 4217 code. - - description - Description of the group payment. - - expiration - End of the time allowed for customers to make this payment, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - id - ID of the 'group_payment' object. String starting with **gp_**. - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - payments - Array of 'payment' objects. All payments must have the same currency and must be supported in the same country. For details of the fields in the 'payment' object, see [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment"). - - reason - Reason for cancellation of the group payment. - - status - Indicates the status of the group payment operation. One of the following values: - **active** - The group payment was created and one or more payments are still open. - **canceled** - The group payment was canceled. - **closed** - All payments in the group payment are complete.Response only. ### Code Samples - - .NET - ```csharp using System; using System.Text.Json; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { var requestObj = new { group_payment = "gp_8932172b9ae44d0caa04d5d419b43739" }; string request = JsonSerializer.Serialize(requestObj); string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/refunds/group_payments", 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 = { group_payment: 'gp_b2eb53a2624345dc3701d59ccac2facd' }; const result = await makeRequest('POST', '/v1/refunds/group_payments', body); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); $body = [ "group_payment" => "gp_17a809ee91d07a58d5a35d7e2b2199b9" ]; try { $object = make_request('post', '/v1/refunds/group_payments', $body); var_dump($object); } catch(Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request group_refund_body = { "group_payment": "gp_22c833729a6a442b13ae2a3b4f745907", } response = make_request(method='post', path='/v1/refunds/group_payments', body=group_refund_body) pprint(response) ``` - /v1/refunds/group_payments - Create Refund for Group Payment - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/refunds/group_payments' \ -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 '{ "group_payment": "gp_d5c1f8d10277731181c6a1d8be8d61dc" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "3f48f258-f5d1-4f0f-894b-0616f9abf16d" }, "data": { "id": "gp_d5c1f8d10277731181c6a1d8be8d61dc", "amount": 250.26, "amount_to_replace": 0, "status": "closed", "currency": "SGD", "country": "SG", "merchant_reference_id": "2026-01-20d", "description": "", "metadata": {}, "expiration": null, "cancel_reason": null, "payments": [ { "id": "payment_342146c28d82a0d4107859443a6e7a08", "amount": 50.25, "original_amount": 50.25, "is_partial": false, "currency_code": "SGD", "country_code": "SG", "status": "CLO", "description": "", "merchant_reference_id": "", "customer_token": "cus_4e25112ac20e144ad073a614dc46934b", "payment_method": "other_e9070391b9936effa092e0afe062b9f8", "payment_method_data": { "id": "other_e9070391b9936effa092e0afe062b9f8", "type": "sg_paynow_bank", "category": "bank_transfer", "metadata": {}, "image": "", "webhook_url": "", "supporting_documentation": "", "next_action": "not_applicable", "bic_swift": "", "account_last4": "" }, "auth_code": null, "expiration": 1768908460, "captured": true, "refunded": true, "refunded_amount": 50.25, "receipt_email": "", "redirect_url": "", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "receipt_number": "", "flow_type": "", "address": null, "statement_descriptor": "Doc Team", "transaction_id": "", "created_at": 1768906660, "metadata": {}, "failure_code": "", "failure_message": "", "paid": true, "paid_at": 1768906742, "dispute": null, "refunds": null, "order": null, "outcome": null, "visual_codes": { "PayNow QR": "data:image/png;base64,iVBORw0KGgoAAAggg==" }, "textual_codes": { "Payee Name": "Doc Team" }, "instructions": [ { "name": "instructions", "steps": [ { "step1": "Please scan the QR Code with your PayNow supported app.", "step2": "Alternatively, take a screenshot of the QR code and upload it using your PayNow supported app.", "step3": "The QR code is single-use only and available for a maximum of 30 minutes. Once payment is successful, do not use the same transfer details again. It will become a duplicate payment." } ] } ], "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "ewallets": [ { "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "amount": 50.25, "percent": 100, "refunded_amount": 50.25 } ], "payment_method_options": {}, "payment_method_type": "sg_paynow_bank", "payment_method_type_category": "bank_transfer", "fx_rate": 1, "merchant_requested_currency": null, "merchant_requested_amount": null, "fixed_side": "", "payment_fees": null, "invoice": "", "escrow": null, "group_payment": "gp_d5c1f8d10277731181c6a1d8be8d61dc", "cancel_reason": null, "initiation_type": "customer_present", "mid": "", "next_action": "not_applicable", "error_code": "", "remitter_information": {}, "save_payment_method": false, "merchant_advice_code": null, "merchant_advice_message": null, "transaction_link_id": null }, { "id": "payment_da7ae98e50ed20d41fd83442ec23f4e3", "amount": 200.01, "original_amount": 200.01, "is_partial": false, "currency_code": "SGD", "country_code": "SG", "status": "CLO", "description": "", "merchant_reference_id": "", "customer_token": "cus_9f4965b9807bc1aeae67b47a0ae5b081", "payment_method": "other_947fe9d1e130e62d8a90158650660182", "payment_method_data": { "id": "other_947fe9d1e130e62d8a90158650660182", "type": "sg_paynow_bank", "category": "bank_transfer", "metadata": {}, "image": "", "webhook_url": "", "supporting_documentation": "", "next_action": "not_applicable", "bic_swift": "", "account_last4": "" }, "auth_code": null, "expiration": 1768908460, "captured": true, "refunded": true, "refunded_amount": 200.01, "receipt_email": "", "redirect_url": "", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "receipt_number": "", "flow_type": "", "address": null, "statement_descriptor": "Doc Team", "transaction_id": "", "created_at": 1768906660, "metadata": {}, "failure_code": "", "failure_message": "", "paid": true, "paid_at": 1768906710, "dispute": null, "refunds": null, "order": null, "outcome": null, "visual_codes": { "PayNow QR": "data:image/png;base64,iVBORw0KGgoAAAANSuQmCC" }, "textual_codes": { "Payee Name": "Doc Team" }, "instructions": [ { "name": "instructions", "steps": [ { "step1": "Please scan the QR Code with your PayNow supported app.", "step2": "Alternatively, take a screenshot of the QR code and upload it using your PayNow supported app.", "step3": "The QR code is single-use only and available for a maximum of 30 minutes. Once payment is successful, do not use the same transfer details again. It will become a duplicate payment." } ] } ], "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "ewallets": [ { "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "amount": 200.01, "percent": 100, "refunded_amount": 200.01 } ], "payment_method_options": {}, "payment_method_type": "sg_paynow_bank", "payment_method_type_category": "bank_transfer", "fx_rate": 1, "merchant_requested_currency": null, "merchant_requested_amount": null, "fixed_side": "", "payment_fees": null, "invoice": "", "escrow": null, "group_payment": "gp_d5c1f8d10277731181c6a1d8be8d61dc", "cancel_reason": null, "initiation_type": "customer_present", "mid": "", "next_action": "not_applicable", "error_code": "", "remitter_information": {}, "save_payment_method": false, "merchant_advice_code": null, "merchant_advice_message": null, "transaction_link_id": null } ] } } ``` - Create Partial Refund for Group Payment - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/refunds/group_payments' \ -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 '{ "group_payment": "gp_7402198d31990dde67d2aaf8c31ccbf1", "amount": 71 }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "dc67cc88-cf29-4234-ad8e-5944e52d0894" }, "data": { "id": "gp_7402198d31990dde67d2aaf8c31ccbf1", "amount": 250.26, "amount_to_replace": 0, "status": "closed", "currency": "SGD", "country": "SG", "merchant_reference_id": "2026-01-20f", "description": "", "metadata": {}, "expiration": null, "cancel_reason": null, "payments": [ { "id": "payment_5686c0b2d604ca1a75f19d98fe753c8e", "amount": 200.01, "original_amount": 200.01, "is_partial": false, "currency_code": "SGD", "country_code": "SG", "status": "CLO", "description": "", "merchant_reference_id": "", "customer_token": "cus_9f4965b9807bc1aeae67b47a0ae5b081", "payment_method": "other_a4d6be0a03a6fe820eb4ca92b726aac1", "payment_method_data": { "id": "other_a4d6be0a03a6fe820eb4ca92b726aac1", "type": "sg_paynow_bank", "category": "bank_transfer", "metadata": {}, "image": "", "webhook_url": "", "supporting_documentation": "", "next_action": "not_applicable", "bic_swift": "", "account_last4": "" }, "auth_code": null, "expiration": 1768916188, "captured": true, "refunded": true, "refunded_amount": 56.74, "receipt_email": "", "redirect_url": "", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "receipt_number": "", "flow_type": "", "address": null, "statement_descriptor": "Doc Team", "transaction_id": "", "created_at": 1768914388, "metadata": {}, "failure_code": "", "failure_message": "", "paid": true, "paid_at": 1768914439, "dispute": null, "refunds": null, "order": null, "outcome": null, "visual_codes": { "PayNow QR": "data:image/png;base64,iVBORw0KGgoAAAANSUh5ErkJggg==" }, "textual_codes": { "Payee Name": "Doc Team" }, "instructions": [ { "name": "instructions", "steps": [ { "step1": "Please scan the QR Code with your PayNow supported app.", "step2": "Alternatively, take a screenshot of the QR code and upload it using your PayNow supported app.", "step3": "The QR code is single-use only and available for a maximum of 30 minutes. Once payment is successful, do not use the same transfer details again. It will become a duplicate payment." } ] } ], "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "ewallets": [ { "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "amount": 200.01, "percent": 100, "refunded_amount": 56.74 } ], "payment_method_options": {}, "payment_method_type": "sg_paynow_bank", "payment_method_type_category": "bank_transfer", "fx_rate": 1, "merchant_requested_currency": null, "merchant_requested_amount": null, "fixed_side": "", "payment_fees": null, "invoice": "", "escrow": null, "group_payment": "gp_7402198d31990dde67d2aaf8c31ccbf1", "cancel_reason": null, "initiation_type": "customer_present", "mid": "", "next_action": "not_applicable", "error_code": "", "remitter_information": {}, "save_payment_method": false, "merchant_advice_code": null, "merchant_advice_message": null, "transaction_link_id": null }, { "id": "payment_68d07bd68de7c5e5cc439556886336de", "amount": 50.25, "original_amount": 50.25, "is_partial": false, "currency_code": "SGD", "country_code": "SG", "status": "CLO", "description": "", "merchant_reference_id": "", "customer_token": "cus_4e25112ac20e144ad073a614dc46934b", "payment_method": "other_d168691bff0b33956315da8e91751b12", "payment_method_data": { "id": "other_d168691bff0b33956315da8e91751b12", "type": "sg_paynow_bank", "category": "bank_transfer", "metadata": {}, "image": "", "webhook_url": "", "supporting_documentation": "", "next_action": "not_applicable", "bic_swift": "", "account_last4": "" }, "auth_code": null, "expiration": 1768916188, "captured": true, "refunded": true, "refunded_amount": 14.25, "receipt_email": "", "redirect_url": "", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "receipt_number": "", "flow_type": "", "address": null, "statement_descriptor": "Doc Team", "transaction_id": "", "created_at": 1768914388, "metadata": {}, "failure_code": "", "failure_message": "", "paid": true, "paid_at": 1768914509, "dispute": null, "refunds": null, "order": null, "outcome": null, "visual_codes": { "PayNow QR": "data:image/png;base64,iVBORw0KGgoAAAkSuQmCC" }, "textual_codes": { "Payee Name": "Doc Team" }, "instructions": [ { "name": "instructions", "steps": [ { "step1": "Please scan the QR Code with your PayNow supported app.", "step2": "Alternatively, take a screenshot of the QR code and upload it using your PayNow supported app.", "step3": "The QR code is single-use only and available for a maximum of 30 minutes. Once payment is successful, do not use the same transfer details again. It will become a duplicate payment." } ] } ], "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "ewallets": [ { "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "amount": 50.25, "percent": 100, "refunded_amount": 14.25 } ], "payment_method_options": {}, "payment_method_type": "sg_paynow_bank", "payment_method_type_category": "bank_transfer", "fx_rate": 1, "merchant_requested_currency": null, "merchant_requested_amount": null, "fixed_side": "", "payment_fees": null, "invoice": "", "escrow": null, "group_payment": "gp_7402198d31990dde67d2aaf8c31ccbf1", "cancel_reason": null, "initiation_type": "customer_present", "mid": "", "next_action": "not_applicable", "error_code": "", "remitter_information": {}, "save_payment_method": false, "merchant_advice_code": null, "merchant_advice_message": null, "transaction_link_id": null } ] } } ``` - Bad Request - Status Not Closed or Error - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/refunds/group_payments' \ -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 '{ "group_payment": "gp_2a342a1bd7bfabd6dc8248fb59395aa2" }' ``` - ```json { "status": { "error_code": "ERROR_GROUP_PAYMENT_CAN_NOT_BE_REFUNDED", "status": "ERROR", "message": "The request tried to create a refund on a group payment, but the statuses of the individual payments were not all 'ERR' or 'CLO'. The request was rejected. Corrective action: None. Wait until all payments are closed, or contact Client Support.", "response_code": "ERROR_GROUP_PAYMENT_CAN_NOT_BE_REFUNDED", "operation_id": "714fc202-1c4b-433b-8eb6-40a09c04ef9a" } } ``` - Bad Request - Payment Method Not Refundable - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/refunds/group_payments' \ -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 '{ "group_payment": "gp_2a342a1bd7bfabd6dc8248fb59395aa2" }' ``` - ```json { "status": { "error_code": "ERROR_REFUND_GROUP_PAYMENT", "status": "ERROR", "message": "Contact Rapyd Client Support.", "response_code": "ERROR_REFUND_GROUP_PAYMENT", "operation_id": "85392eb1-8ad3-4e3c-88f3-d6f91260991b" } } ```