# Create a Group Payment Session (/docs/guides/group-payment/group-payment-sessions/create-a-group-payment-session) 

# 🛠️ How to Create a Group Payment Session [#️-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 [#-create-group-payment-request-examples]

<Tabs items="[&#x22;curl&#x22;, &#x22;Node.js (fetch)&#x22;, &#x22;Python (requests)&#x22;]">
  <Tab value="curl">
    ```bash
    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"
      }'
    ```
  </Tab>

  <Tab value="Node.js (fetch)">
    ```javascript
    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));
    ```
  </Tab>

  <Tab value="Python (requests)">
    ```python
    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())
    ```
  </Tab>
</Tabs>

> 🔐 &#x2A;*Authentication Required:**
>
> Be sure to include your **sandbox Merchant API key** in the request headers using the `x-api-key` field.

***

## ✅ Example JSON Response [#-example-json-response]

```json
{
  "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](/docs/API/v1/createGroupPayment).