Learn how to reconcile and track payments associated with a Group Payment Session using the Hands In API.

📊 Reconcile a Group Payment Session

When multiple customers contribute to a group payment, each payment is tracked individually. To support reconciliation, Hands In provides a referenceId that can be used to identify and trace payments across systems.

By default, any payment made under a group payment session will have a referenceId formatted as:

{groupPaymentId}_{customerId}

Where:

groupPaymentId is the unique ID of the group payment session.
customerId associated with the participant in the group who the payment is for.

🧾 Using `referenceId` for Group Payments

When creating a group payment session, you may pass a custom referenceId. This value will be prefixed to all payment referenceIds for a particular group order, allowing you to easily match incoming payments with your system records.

Example Create Request with `referenceId`

curl --request POST \
  --url https://api.sandbox.handsin.com/v1/group-payments \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "x-api-key: <your-api-key>" \
  --data '{
    "idempotencyKey": "example_unique_idempotency_key",
    "referenceId": "YOUR_UNIQUE_MERCHANT_ORDER_REF",
    "amountMoney": {
      "amount": 2000,
      "currency": "GBP"
    },
    "customer": {
      "firstName": "Example",
      "email": "example@handsin.com"
    },
    "lineItemParams": [
      {
        "item": {
          "name": "Example LineItem",
          "amountMoney": {
            "amount": 1000,
            "currency": "GBP"
          }
        },
        "quantity": 2
      }
    ],
    "splitType": "BY_ITEM"
  }'

const url = "https://api.sandbox.handsin.com/v1/group-payments";

const payload = {
  idempotencyKey: "example_unique_idempotency_key",
  referenceId: "YOUR_UNIQUE_MERCHANT_ORDER_REF",
  amountMoney: {
    amount: 2000,
    currency: "GBP",
  },
  customer: {
    firstName: "Example",
    email: "example@handsin.com",
  },
  lineItemParams: [
    {
      item: {
        name: "Example LineItem",
        amountMoney: {
          amount: 1000,
          currency: "GBP",
        },
      },
      quantity: 2,
    },
  ],
  splitType: "BY_ITEM",
};

try {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
      "x-api-key": "<your-api-key>",
    },
    body: JSON.stringify(payload),
  });

  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error("Request failed:", error.message);
}

import requests

url = "https://api.sandbox.handsin.com/v1/group-payments"
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>"
}
payload = {
    "idempotencyKey": "example_unique_idempotency_key",
    "referenceId": "YOUR_UNIQUE_MERCHANT_ORDER_REF",
    "amountMoney": {
        "amount": 2000,
        "currency": "GBP"
    },
    "customer": {
        "firstName": "Example",
        "email": "example@handsin.com"
    },
    "lineItemParams": [
        {
            "item": {
                "name": "Example LineItem",
                "amountMoney": {
                    "amount": 1000,
                    "currency": "GBP"
                }
            },
            "quantity": 2
        }
    ],
    "splitType": "BY_ITEM"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Now any payments made into this group payment session will have the following referenceId - YOUR_UNIQUE_MERCHANT_ORDER_REF_{customerId}

where YOUR_UNIQUE_MERCHANT_ORDER_REF is the value you passed in to the referenceId field when creating the group payment

🔍 Look Up Payments Via Your Merchant Dashboard

The Payments page with a reference typed into the search box and the matching payments listed with their Reference ID

Open Payments in your Hands In Dashboard. The Reference ID column shows each payment's referenceId, and you can search by it. Enter your system's referenceId, or the start of it, in the search box.

In the example above, the search lists only the payments whose reference matches, out of many payments. The payments in a group payment session have referenceId's such as:

Card #	Example Reference ID
1	YOUR_UNIQUE_MERCHANT_ORDER_REF_CUSTOMER-1
2	YOUR_UNIQUE_MERCHANT_ORDER_REF_CUSTOMER-2
3	YOUR_UNIQUE_MERCHANT_ORDER_REF_CUSTOMER-3

✅ That's it — you've learned how to use referenceId to help reconcile payments from a group payment session using your dashboard.

➡️ For real-time reconciliation and tracking of events, we recommend setting up webhook notifications to receive updates as they happen.
Alternatively, API integrations can poll the group payment session and fetch each payment for that session using the values from the group payment's memberPayments field and in conjunction with the retrieve payment endpoint

Reconcile Group Payments

📊 Reconcile a Group Payment Session

🧾 Using `referenceId` for Group Payments

Example Create Request with `referenceId`

🔍 Look Up Payments Via Your Merchant Dashboard

On this page

Reconcile Group Payments

📊 Reconcile a Group Payment Session

🧾 Using referenceId for Group Payments

Example Create Request with referenceId

🔍 Look Up Payments Via Your Merchant Dashboard

On this page

🧾 Using `referenceId` for Group Payments

Example Create Request with `referenceId`