--- title: "Create Group Payment" source_url: https://docs.rapyd.net/en/create-group-payment.html lang: en --- # Create Group Payment Create a payment from multiple payment sources. Each payment in the group payment must be from a different payment method. This method triggers the [Payment Succeeded Webhook](https://docs.rapyd.net/en/payment-succeeded-webhook.md "Payment Succeeded Webhook") for each payment method. This webhook contains the same information as the Create Group Payment response for the relevant payment method. If all payments use a **card** payment method with `capture` set to **true**, the following additional webhooks are sent: - **Payment Completed** - For a payment method that does not require 3DS authentication, this webhook is sent together with the response. For a payment method that requires 3DS authentication, this webhook is sent following 3DS authentication. - **Group Payment Completed** - If 3DS authentication is not required for any of the payment methods, this webhook is sent together with the response. Otherwise, it is sent when 3DS authentication is complete. The following webhooks provide information about later changes to the group payment: - [Group Payment Completed Webhook](https://docs.rapyd.net/en/group-payment-completed-webhook.md "Group Payment Completed Webhook") - Asynchronous webhooks relating to each individual payment. > **Note:** > > - Clients who have PCI clearance can use this method to collect money from a card. > - Before you create a payment with the token for a payment method, verify that the value of `is_tokenizable` is **true**. See the response to [List Payment Methods by Country](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country"). > - A **card** payment that requires 3DS authentication must be authenticated within 15 minutes. > - To simulate completion of a **card** payment that requires 3DS authentication, see [Simulating 3DS Authentication](https://docs.rapyd.net/en/simulating-3ds-authentication.md "Simulating 3DS Authentication"). > - 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") > - [Group Payment Errors](https://docs.rapyd.net/en/group-payment-errors.md "Group Payment 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 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 - - description - Description of the group payment transaction. - - 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. For details about the fields in the 'payment' object, see [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment"). ### 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 { string payment = "gp_7e2b7abee522ba5089eb98c7482991ea"; string result = RapydApiRequestSample.Utilities.MakeRequest("DELETE", $"/v1/payments/group_payments/{payment}"); 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: true }, merchant_reference_id: '12345689', payments: [ { payment_method: { type: 'us_discover_card', fields: { number: '4111111111111111', expiration_month: '11', expiration_year: '21', cvv: '123', name: 'Jane Doe', address: '123 Main Street, Anytown' }, metadata: null }, amount: 50, currency: 'USD', ewallets: [ { ewallet: 'ewallet_89099803a1e923a3e1fe9fc8f656b425' } ] }, { payment_method: { type: 'us_mastercard_card', fields: { number: '4111111111111111', expiration_month: '11', expiration_year: '21', cvv: '123', name: 'John Doe', address: '123 Main Street, Anytown' }, metadata: null }, amount: 200, currency: 'USD', ewallets: [ { ewallet: 'ewallet_89099803a1e923a3e1fe9fc8f656b425' } ] } ] }; const result = await makeRequest('POST', '/v1/payments/group_payments', body); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); try { $body = [ "merchant_reference_id" => "12345689", "payments" => [ array( "payment_method" => array( "type" => "us_discover_card", "fields" => array( "number" => "4111111111111111", "expiration_month" => "11", "expiration_year" => "21", "cvv" => "123", "name" => "Jane Doe", "address" => "123 Main Street, Anytown" ), "metadata" => null ), "amount" => 50, "currency" => "USD", "ewallets" => [ array( "ewallet" => "ewallet_4f8009d08b7b41e5d3b356494101d83b" ) ] ), ] ]; $object = make_request('post', '/v1/payments/group_payments/gp_64abd30667647f83395945ddc24c70b3'); var_dump($object); } catch(Exception $e) { echo "Error => $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request group_payment_body = { "metadata": { "user_defined": "silver" }, "merchant_reference_id": "12345689", "payments": [{ "amount": 50, "currency": "USD", "payment_method": { "type": "us_visa_card", "fields": { "number": "4111111111111111", "expiration_month": "11", "expiration_year": "21", "cvv": "123", "name": "John Doe", "address": "123 Main Street, Anytown, NY" } }, "ewallets": [{ "ewallet": "ewallet_452c8cd682f347b4abee9bbee04eac03" } ] }, { "amount": 200, "currency": "USD", "payment_method": { "type": "us_visa_card", "fields": { "number": "4111111111111111", "expiration_month": "11", "expiration_year": "21", "cvv": "123", "name": "John Doe", "address": "123 Main Street, Anytown, NY" } }, "ewallets": [{ "ewallet": "ewallet_7424264d34c77c8b1096bac6afd54482" } ] }] } response = make_request(method='post', path='/v1/payments/group_payments', body=group_payment_body) pprint(response) ``` - /v1/payments/group_payments - Create Group Payment - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payments/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 '{ "merchant_reference_id": "2026-01-20a", "payments": [ { "payment_method": { "type": "sg_fast_bank", "fields": {} }, "customer": "cus_4e25112ac20e144ad073a614dc46934b", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "amount": 50.25, "currency": "SGD", }, { "payment_method": { "type": "sg_paynow_bank", "fields": {} }, "customer": "cus_9f4965b9807bc1aeae67b47a0ae5b081", "amount": 200.01, "currency": "SGD", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", } ] }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "0ac1b507-9994-4275-b393-b5c202efa511" }, "data": { "id": "gp_2a342a1bd7bfabd6dc8248fb59395aa2", "amount": 250.26, "amount_to_replace": 0, "status": "active", "currency": "SGD", "country": "SG", "merchant_reference_id": "2026-01-20a", "description": "", "metadata": {}, "expiration": null, "cancel_reason": null, "payments": [ { "id": "payment_892158b5d495e0c0084c2ff7a147570a", "amount": 0, "original_amount": 50.25, "is_partial": false, "currency_code": "SGD", "country_code": "SG", "status": "ACT", "description": "", "merchant_reference_id": "", "customer_token": "cus_4e25112ac20e144ad073a614dc46934b", "payment_method": "other_77db8714d84347522c96120b998cacec", "payment_method_data": { "id": "other_77db8714d84347522c96120b998cacec", "type": "sg_fast_bank", "category": "bank_transfer", "metadata": {}, "image": "", "webhook_url": "", "supporting_documentation": "", "next_action": "not_applicable", "bic_swift": "", "account_last4": "" }, "auth_code": null, "expiration": 1770113056, "captured": true, "refunded": false, "refunded_amount": 0, "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": 1768903456, "metadata": {}, "failure_code": "", "failure_message": "", "paid": false, "paid_at": 0, "dispute": null, "refunds": null, "order": null, "outcome": null, "visual_codes": {}, "textual_codes": { "DBS Account No": "6028101259480326" }, "instructions": [ { "name": "instructions", "steps": [ { "step1": "Please Transfer funds to the provided DBS bank account using your Singapore based bank account via FAST (preferred), MEPS or GIRO." } ] } ], "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "ewallets": [ { "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "amount": 50.25, "percent": 100, "refunded_amount": 0 } ], "payment_method_options": {}, "payment_method_type": "sg_fast_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_2a342a1bd7bfabd6dc8248fb59395aa2", "cancel_reason": null, "initiation_type": "customer_present", "mid": "", "next_action": "pending_confirmation", "error_code": "", "remitter_information": {}, "save_payment_method": false, "merchant_advice_code": null, "merchant_advice_message": null, "transaction_link_id": null }, { "id": "payment_9646f22e04bbcb044570e1cdebd75a29", "amount": 0, "original_amount": 200.01, "is_partial": false, "currency_code": "SGD", "country_code": "SG", "status": "ACT", "description": "", "merchant_reference_id": "", "customer_token": "cus_9f4965b9807bc1aeae67b47a0ae5b081", "payment_method": "other_a676f227694a1f1a5729221c4b98af3c", "payment_method_data": { "id": "other_a676f227694a1f1a5729221c4b98af3c", "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": 1768905256, "captured": true, "refunded": false, "refunded_amount": 0, "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": 1768903456, "metadata": {}, "failure_code": "", "failure_message": "", "paid": false, "paid_at": 0, "dispute": null, "refunds": null, "order": null, "outcome": null, "visual_codes": { "PayNow QR": "data:image/png;base64,iVBORw0KGgoAAAAN=" }, "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": 0 } ], "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_2a342a1bd7bfabd6dc8248fb59395aa2", "cancel_reason": null, "initiation_type": "customer_present", "mid": "", "next_action": "pending_confirmation", "error_code": "", "remitter_information": {}, "save_payment_method": false, "merchant_advice_code": null, "merchant_advice_message": null, "transaction_link_id": null } ] } } ``` - Bad Request - Different Currencies - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payments/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 '{ "merchant_reference_id": "2026-01-20b", "payments": [ { "payment_method": { "type": "sg_fast_bank", "fields": {} }, "customer": "cus_4e25112ac20e144ad073a614dc46934b", "amount": 50.25, "currency": "USD", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net" }, { "payment_method": { "type": "sg_paynow_bank", "fields": {} }, "customer": "cus_9f4965b9807bc1aeae67b47a0ae5b081", "amount": 200.01, "currency": "SGD", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net" } ] }' ``` - ```json { "status": { "error_code": "ERROR_DIFFERENT_CURRENCIES_NOT_SUPPORTED_FOR_GROUP_PAYMENT", "status": "ERROR", "message": "The request tried to create a group payment or replace a failed payment in a group payment, but the individual payments did not all use the same currency. The request was rejected. Corrective action: Use the same currency for all payments.", "response_code": "ERROR_DIFFERENT_CURRENCIES_NOT_SUPPORTED_FOR_GROUP_PAYMENT", "operation_id": "44180779-8c2e-4a60-a3da-80d31380e9e3" } } ``` - Bad Request - Zero Amount - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payments/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 '{ "merchant_reference_id": "2026-01-20c", "payments": [ { "payment_method": { "type": "sg_fast_bank", "fields": {} }, "customer": "cus_4e25112ac20e144ad073a614dc46934b", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "amount": 50.25, "currency": "SGD", }, { "payment_method": { "type": "sg_paynow_bank", "fields": {} }, "customer": "cus_9f4965b9807bc1aeae67b47a0ae5b081", "amount": 0, "currency": "SGD", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", } ] }' ``` - ```json { "status": { "error_code": "ERROR_PAYMENT_INVALID_AMOUNT", "status": "ERROR", "message": "The request tried to create a payment, but the amount was not found or not recognized. The request was rejected. Corrective action: Set 'amount' to a positive decimal number.", "response_code": "ERROR_PAYMENT_INVALID_AMOUNT", "operation_id": "49a904fe-a33c-4af2-97a7-a71aa9929991" } } ```