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 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:
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_tokenizableis true. See the response to 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.
The code samples include successful requests (200) and bad requests (400).
For error messages that appear due to bad requests (400), see:
For information about unauthorized request (401) and other authentication errors, see Troubleshooting Authentication and Authorization Errors.
description
Description of the group payment transaction.
payments
Array of 'payment' objects. For details about the fields in the 'payment' object, see Create Payment.
Code Samples
.NET
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
const makeRequest = require('<path-to-your-utility-file>/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 $path = $_SERVER['DOCUMENT_ROOT']; $path .= "/<path-to-your-utility-file>/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
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 -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", } ] }'{ "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 -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" } ] }'{ "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 -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", } ] }'{ "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" } }