🛠️ How to Create a Group Payment Session

You can create a group payment session by sending a POST request to https://api.sandbox.handsin.com/v1/group-payments

🧾 Create Group Payment Request Examples

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",
    "customer": {
      "firstName": "example",
      "email": "example@handsin.com"
    },
    "amountMoney": {
      "amount": 2000,
      "currency": "GBP"
    },
    "lineItemParams": [
      {
        "item": {
          "name": "Example LineItem",
          "amountMoney": {
            "amount": 1000,
            "currency": "GBP"
          }
        },
        "quantity": 2
      }
    ],
    "splitType": "BY_ITEM",
    "expirationDate": "2025-04-24T11:43:44.000Z"
  }'

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

const payload = {
  idempotencyKey: "example_unique_idempotency_key",
  customer: {
    firstName: "example",
    email: "example@handsin.com",
  },
  amountMoney: {
    amount: 2000,
    currency: "GBP",
  },
  lineItemParams: [
    {
      item: {
        name: "Example LineItem",
        amountMoney: {
          amount: 1000,
          currency: "GBP",
        },
      },
      quantity: 2,
    },
  ],
  splitType: "BY_ITEM",
  expirationDate: "2025-04-24T11:43:44.000Z",
};

fetch(url, {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>",
  },
  body: JSON.stringify(payload),
})
  .then((res) => res.json())
  .then(console.log)
  .catch((err) => console.error("Request failed:", err));

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",
    "customer": {
        "firstName": "example",
        "email": "example@handsin.com"
    },
    "amountMoney": {
        "amount": 2000,
        "currency": "GBP"
    },
    "lineItemParams": [
        {
            "item": {
                "name": "Example LineItem",
                "amountMoney": {
                    "amount": 1000,
                    "currency": "GBP"
                }
            },
            "quantity": 2
        }
    ],
    "splitType": "BY_ITEM",
    "expirationDate": "2025-04-24T11:43:44.000Z"
}

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

🔐 Authentication Required:

Be sure to include your sandbox Merchant API key in the request headers using the x-api-key field.

✅ Example JSON Response

{
  "merchantId": "your-merchant-id",
  "id": "example-group-payment-id-123",
  "ownerId": "example-customer-id-01",
  "status": "PENDING",
  "memberIds": ["example-customer-id-01"],
  "invited": [],
  "memberPayments": {},
  "splitType": "BY_ITEM",
  "itemAllocation": {},
  "lineItems": [
    {
      "item": {
        "name": "Example LineItem",
        "amountMoney": {
          "amount": 1000,
          "currency": "GBP"
        },
        "id": "example-item-1"
      },
      "quantity": 2,
      "subtotalMoney": {
        "amount": 2000,
        "currency": "GBP"
      },
      "totalMoney": {
        "amount": 2000,
        "currency": "GBP"
      }
    }
  ],
  "totalMoney": {
    "amount": 2000,
    "currency": "GBP"
  },
  "amountMoney": {
    "amount": 2000,
    "currency": "GBP"
  },
  "expirationDate": "2025-04-24T11:43:44.000Z",
  "url": "https://checkout.sandbox.handsin.com/r/example-group-payment-redirect-id",
  "createdAt": "2025-04-23T11:43:44.000Z",
  "updatedAt": "2025-04-23T11:43:44.000Z",
  "enablePartialPayment": false,
  "customerUrl": "https://checkout.sandbox.handsin.com/g/example-group-payment-id-123/group-dashboard?mid=your-merchant-id&cid=example-customer-id-01"
}

Field	Description
`id`	The unique identifier for this group payment session.
`url`	Hands In-hosted checkout link to redirect your customer for payment.
`status`	The current state of the payment session (e.g., `PENDING`, `APPROVED`, `COMPLETED`, `EXPIRED`, `CANCELLED`).
`enablePartialPayment`	Set to `true` to automatically capture payments as customers authorize a transaction.

📗 For detailed parameter descriptions and usage, visit our Group Payment API reference documentation.

Create a Group Payment Session

🛠️ How to Create a Group Payment Session

🧾 Create Group Payment Request Examples

✅ Example JSON Response

On this page