🚀 Quickstart: Hands In API

This guide will help you create and share your first payment session using the Hands In API. Whether you're testing multi card or group payments, you'll be up and running in just a few steps.

✅ Prerequisites

Before you begin, make sure you’ve completed the following:

• Set up your Hands In account
• Retrieve your API key (sandbox or live)

1️⃣ Create a Payment Session

To initiate a multi card or group payment session, send a POST request to either:

• The Multi Card Payments endpoint, or
• The Group Payments endpoint

We will create a multi card payment in this example. See request below:

curl --request POST \
  --url https://api.sandbox.handsin.com/v1/multi-card-payments \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --data '{
    "amountMoney": {
      "currency": "GBP",
      "amount": 50000
    },
    "idempotencyKey": "<unique-random-string>"
  }'

curl -X POST "https://api.sandbox.handsin.com/v1/multi-card-payments" -H "Accept: application/json" -H "Content-Type: application/json" -H "x-api-key: <your-api-key>" -d "{\"amountMoney\":{\"currency\":\"GBP\",\"amount\":50000},\"idempotencyKey\":\"<unique-random-string>\"}"

$headers = @{
  "Accept" = "application/json"
  "Content-Type" = "application/json"
  "x-api-key" = "<your-api-key>"
}

$body = @{
  amountMoney = @{
    currency = "GBP"
    amount = 50000
  }
  idempotencyKey = "<unique-random-string>"
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Uri "https://api.sandbox.handsin.com/v1/multi-card-payments" `
  -Method POST -Headers $headers -Body $body

Don't forget to replace <your-api-key> with your merchant sandbox API key instead, and make sure idempotencyKey is a unique string for each request.

2️⃣ Retrieve Payment URL

The response will include a url — this is your hosted checkout session you should provide to the user in some way.

You can use the URL in the response to:

• redirect them to a new browser tab/window
• Embed it in your website using an <iframe>, or
• Send it directly to the customer via email, SMS, or any other channel.

🔁 Example Response:

{
  "id": "mc_123456",
  "merchantId": "your-merchant-id",
  "status": "PENDING",
  "url": "https://checkout.sandbox.handsin.com/m/abc123",
  "amountMoney": {
    "amount": 50000,
    "currency": "GBP"
  },
  ...
}

✅ You're Done!

That’s it — you’ve created and shared your first Hands In multi-card payment session! 🎉
When your customer opens the link, they'll be guided through our secure, white-labeled checkout experience to pay across multiple-cards.

Next, we recommend setting up webhooks so your system stays updated as payments are completed or expire.