Card on File

Save a customer’s card for future payments. Card details are stored securely in the Secure Card Service (SCS) — they never touch the TurnStay API.

How it works

1. Create a Payment Method Token Intent (PMTI) to start the tokenization flow.
2. The customer enters their card details via a hosted form or your server submits them directly to SCS (S2S).
3. TurnStay returns a payment_method_token you can use for future charges.

Create a tokenization intent

curl -X POST "https://staging.turnstay.com/api/v1/payment_method_token_intent" \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 123,
    "payment_type": "Tokenization",
    "customer_email": "guest@example.com",
    "customer_phone_number": "+270611799543",
    "callback_url": "https://yoursite.com/tokenization/callback",
    "expiry_date": "2027-01-01"
  }'

Field	Type	Required	Description
account_id	integer	Yes	Your TurnStay account ID.
payment_type	string	Yes	Set to "Tokenization".
customer_email	string	Yes	Customer’s email address.
customer_phone_number	string	Yes	Customer’s phone number (E.164 format).
callback_url	string	No	URL to receive tokenization result.
expiry_date	date	No	When the saved card should expire.

Response

The response includes latest_version with two URLs:

Field	Description
provider_tokenization_url	Hosted form URL — load in an iframe or redirect the customer.
confirm_endpoint_url	S2S endpoint — POST card details directly to SCS.

Option 1: Hosted form

Redirect the customer to provider_tokenization_url. They enter their card details on a PCI-compliant hosted page. Once complete, TurnStay sends the result to your callback_url.

Option 2: Server-to-server (S2S)

POST card details directly to the confirm_endpoint_url on SCS. Card data goes from your server to SCS — it never passes through the TurnStay API.

curl -X POST "{confirm_endpoint_url}" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholder_name": "Jane Smith",
    "card_number": "4111111111111111",
    "expiry_month": 12,
    "expiry_year": 2027,
    "cvc": "123"
  }'

Charge a saved card

Once tokenized, use the card_token field when creating a payment intent:

curl -X POST "https://staging.turnstay.com/api/v1/payments/intent" \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 123,
    "billing_amount": 50000,
    "billing_currency": "ZAR",
    "checkin_date": "2026-08-01",
    "merchant_reference": "REPEAT-GUEST-001",
    "card_token": "tok_1234567890",
    "payment_type": "Card Payment"
  }'

The payment is processed using the saved card without the customer re-entering their details.