Hands In

Create a Multi Card Payment Session

Learn how to create a multi card payment session.

Get Markdown

๐Ÿ› ๏ธ How to Create a Multi Card Payment Session

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

๐Ÿงพ Create Multi Card Request Examples

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 '{
    "idempotencyKey": "example_unique_idempotency_key",
    "amountMoney": {
      "amount": 1000,
      "currency": "GBP"
    },
    "customer": {
      "firstName": "Example",
      "lastName": "Customer",
      "email": "example@handsin.com",
      "phoneNumber": "+447232323",
      "language": "en"
    }
  }'
const url = "https://api.sandbox.handsin.com/v1/multi-card-payments";

const payload = {
  idempotencyKey: "example_unique_idempotency_key",
  amountMoney: {
    amount: 1000,
    currency: "GBP",
  },
  customer: {
    firstName: "Example",
    lastName: "Customer",
    email: "example@handsin.com",
    phoneNumber: "+447232323",
    language: "en",
  },
};

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),
  });

  if (!response.ok) {
    throw new Error(`Response status: ${response.status}`);
  }

  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/multi-card-payments"
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>"
}
payload = {
    "idempotencyKey": "example_unique_idempotency_key",
    "amountMoney": {
        "amount": 1000,
        "currency": "GBP"
    },
    "customer": {
        "firstName": "Example",
        "lastName": "Customer",
        "email": "example@handsin.com",
        "phoneNumber": "+447232323",
        "language": "en"
    }
}

try:
    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
    print(response.json())
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")
$headers = @{
  "Accept" = "application/json"
  "Content-Type" = "application/json"
  "x-api-key" = "<your-api-key>"
}

$body = @{
  idempotencyKey = "example_unique_idempotency_key"
  amountMoney = @{
    amount = 1000
    currency = "GBP"
  }
  customer = @{
    firstName = "Example"
    lastName = "Customer"
    email = "example@handsin.com"
    phoneNumber = "+447232323"
    language = "en"
  }
} | ConvertTo-Json -Depth 3

try {
  $response = Invoke-RestMethod -Uri "https://api.sandbox.handsin.com/v1/multi-card-payments" \
    -Method POST -Headers $headers -Body $body
  $response
} catch {
  Write-Host "Request failed: $($_.Exception.Message)"
}

๐Ÿ” Authentication Required:

Be sure to include your sandbox Merchant API key in the request headers using the x-api-key field. Otherwise, you will most likely encounter a 401 error.

โœ… Example JSON Response

{
  "id": "example-multi-card-id-123",
  "amountMoney": {
    "amount": 1000,
    "currency": "GBP"
  },
  "totalMoney": {
    "amount": 1000,
    "currency": "GBP"
  },
  "status": "PENDING",
  "autocomplete": true,
  "enablePartialPayment": false,
  "url": "https://checkout.sandbox.handsin.com/r/example-multi-card-redirect-id",
  "customerId": "example-customer-id",
  "merchantId": "your-merchant-id",
  "createdAt": "2025-04-23T10:27:14.000Z",
  "updatedAt": "2025-04-23T10:27:14.000Z"
}

๐Ÿง  Response Field Breakdown

FieldDescription
idThe unique identifier for this multi card payment session.
urlHands In-hosted checkout link to redirect your customer for payment.
statusThe current state of the payment session (e.g., PENDING, APPROVED, COMPLETED, EXPIRED, CANCELLED).
autocompleteSet to false if you want to manually complete the session via the API or dashboard.
enablePartialPaymentSet to true to automatically capture payments as customers authorize a transaction.

๐Ÿ“— For detailed parameter descriptions and usage, visit our Multi Card API reference documentation .

On this page