Hosted Checkout

The hosted checkout is the standard integration. Create a Payment Intent, then redirect the customer to TurnStay’s secure page where they enter their card details.

Create a Payment Intent

POST /api/v1/payments/intent

Required fields

Field	Type	Description
account_id	int	Your TurnStay account ID
billing_amount	int	Amount in cents (R1,000.00 = 100000)
billing_currency	string	ISO 4217 code matching your account currency
checkin_date	string	Service or booking date (YYYY-MM-DD)

Recommended fields

Field	Type	Description
merchant_reference	string	Your booking/invoice number. Returned in all callbacks.
customer_email	string	For receipts. If omitted, the payment page asks the customer.
callback_url	string	Your server URL. TurnStay POSTs here when payment completes.
success_redirect_url	string	Where the customer goes after successful payment.
failed_redirect_url	string	Where the customer goes if the payment fails.

Python

import requests

response = requests.post(
    "https://prod.turnstay.com/api/v1/payments/intent",
    headers={"Authorization": "Bearer sk_live_YOUR_SECRET_KEY"},
    json={
        "account_id": 123,
        "billing_amount": 100000,
        "billing_currency": "ZAR",
        "checkin_date": "2026-07-15",
        "merchant_reference": "BOOKING-2026-001",
        "customer": "Jean Dupont",
        "customer_email": "jean.dupont@example.com",
        "callback_url": "https://www.yoursite.com/api/turnstay",
        "success_redirect_url": "https://www.yoursite.com/payment-ok",
        "failed_redirect_url": "https://www.yoursite.com/payment-failed",
        "description": "2 nights - Deluxe Room",
    },
)

data = response.json()
payment_url = data["turnstay_payment_url"]
lookup_id = data["lookup_id"]

Node.js

const response = await fetch("https://prod.turnstay.com/api/v1/payments/intent", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    account_id: 123,
    billing_amount: 100000,
    billing_currency: "ZAR",
    checkin_date: "2026-07-15",
    merchant_reference: "BOOKING-2026-001",
    customer: "Jean Dupont",
    customer_email: "jean.dupont@example.com",
    callback_url: "https://www.yoursite.com/api/turnstay",
    success_redirect_url: "https://www.yoursite.com/payment-ok",
    failed_redirect_url: "https://www.yoursite.com/payment-failed",
    description: "2 nights - Deluxe Room",
  }),
});

const data = await response.json();
const paymentUrl = data.turnstay_payment_url;
const lookupId = data.lookup_id;

Response

{
  "id": 45678,
  "lookup_id": "pi_abc123def456",
  "status": { "name": "INITIALIZED" },
  "turnstay_payment_url": "https://payment.turnstay.com/payments/intent/pay/pi_abc123def456",
  "billing_amount": 100000,
  "billing_currency": { "code": "ZAR", "name": "Rand" },
  "merchant_reference": "BOOKING-2026-001",
  "client_secret": "cs_xyz789",
  "created_at": "2026-06-01T10:30:00Z"
}

Save lookup_id and merchant_reference in your database — you’ll need them to match callbacks to bookings.

Redirect the customer

Send the customer’s browser to turnstay_payment_url:

# Python / Flask
return redirect(data["turnstay_payment_url"])

// Node.js / Express
res.redirect(data.turnstay_payment_url);

What happens on the payment page

• Customer sees the amount, currency, and your description.
• Collects email/phone if you didn’t provide them.
• Securely captures card details — you never see them.
• Handles 3D Secure authentication automatically.
• Redirects to your success_redirect_url or failed_redirect_url.