docs(rest-api): add deferred tokenization endpoint

CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is the Handpoint developer documentation website, built with [Docusaurus 2](https://docusaurus.io/). It documents multiple payment SDKs: Android, iOS, JavaScript, Express, Windows, and REST API.
+
+## Commands
+
+```bash
+yarn install          # Install dependencies
+yarn start            # Start local dev server at localhost:3000
+yarn build            # Build the static site
+yarn clear            # Remove build artifacts
+```
+
+### Creating a new SDK version (required before releasing to production)
+
+```bash
+npm run docusaurus docs:version:android "Android SDK 7.x.x"
+npm run docusaurus docs:version:ios "iOS SDK x.x.x"
+npm run docusaurus docs:version:javascript "JavaScript SDK x.x.x"
+npm run docusaurus docs:version:restapi "REST API x.x.x"
+npm run docusaurus docs:version:windows "Windows SDK x.x.x"
+npm run docusaurus docs:version:express "Express SDK x.x.x"
+```
+
+After running these commands, restart Docusaurus to see the new version.
+
+## Architecture
+
+### Multi-instance Docusaurus setup
+
+The site uses Docusaurus multi-instance docs plugins — each SDK is a separate plugin instance with its own versioned docs, sidebar config, and search index. The main plugin handles `docs/` (FAQs, intro), while six additional plugin instances handle `android/`, `ios/`, `javascript/`, `restapi/`, `windows/`, `express/`.
+
+Each SDK plugin has:
+- A live docs folder (e.g., `android/`)
+- Versioned docs folder (e.g., `android_versioned_docs/`)
+- Versioned sidebars (e.g., `android_versioned_sidebars/`)
+- A versions manifest (e.g., `android_versions.json`)
+
+Sidebars for most SDKs use `sidebarsIos.js` (autogenerated). Android uses `sidebarsAndroid.js`.
+
+### `includeCurrentVersion` flag
+
+In `docusaurus.config.js`, some plugins have `includeCurrentVersion: false, // dev` comments. The `setenv.sh` script toggles this flag:
+- **Staging** (`setenv.sh test`): sets to `true` — shows work-in-progress docs
+- **Production** (`setenv.sh prod`): sets to `false` — hides unreleased docs
+
+**Do not manually toggle this flag** — it is managed by the deployment script.
+
+## Branching and Deployment
+
+Follows Gitflow:
+- Feature branches → PR to `dev` → auto-deploys to `developer.handpoint.io`
+- `dev` → PR to `main` → auto-deploys to `developer.handpoint.com`
+
+**Before merging a new SDK version to `main`**, always run the version-tagging command above first.
+
+CI/CD is defined in `.github/workflows/deploy.yml`. The `setenv.sh` script is run as part of the deployment to switch URLs and `includeCurrentVersion` flags between environments.

restapi/restendpoints.md

@@ -311,6 +311,79 @@ Error example response (using invalid guid):
 }
 ```
 
+## /transactions/\{guid\}/token \{#transactionsguidtoken\}
+
+`DeferredTokenization`
+
+GET endpoint used to retrieve a card token from a previously completed transaction. This operation, known as **deferred tokenization**, allows merchants to obtain a card token without requiring tokenization to be enabled at the time of the original transaction. The returned `cardToken` can be used for subsequent operations such as cardholder identification or MOTO payments. See the supported transaction types below.
+
+:::note
+Deferred tokenization is supported for the following transaction types: `sale`, `refund`, `preAuthorizationCapture`, `moToSale` and `moToRefund`. Other transaction types will return a `400` error.
+:::
+
+:::warning
+Tokenization requests must be made within **12 months** of the original transaction. Requests for transactions older than 12 months will not be processed.
+:::
+
+**Parameters**
+
+| Parameter      | Notes |
+| ----------- | ----------- |
+| `Header: ApiKeyCloud` <span class="badge badge--primary">Required</span>   <br />*String*     | Api key used to authenticate the merchant. (UNIQUE per Merchant) |
+| `Path parameter: guid` <span class="badge badge--primary">Required</span>   <br />*String*    | The GUID of the completed card-present transaction from which to retrieve the token. |
+
+**Returns**
+
+| Response      | Response Code |
+| ----------- | ----------- |
+| [DeferredTokenizationResponse](restobjects.md#deferredTokenizationResponse) | Response code 200. |
+| **BadRequest** | Response code 400. Returned when the transaction type is not eligible for deferred tokenization. |
+
+**Code Example**
+
+```shell
+Operation executed using CLI tool CURL:
+
+REQUEST (sale tokenization):
+  curl -X GET \
+   -H "ApiKeyCloud: MeRcHaNt-ApIkEy" \
+   -H "Content-Type: application/json" \
+   "https://cloud.handpoint.com/transactions/75413c40-21db-11f1-991b-6f80eaf25911/token" (production)
+   "https://cloud.handpoint.io/transactions/75413c40-21db-11f1-991b-6f80eaf25911/token" (development)
+
+RESPONSE code 200:
+{
+    "agreementNumber": "123456789010102",
+    "cardToken": "665630867",
+    "cardTokenizationGuid": "7df78050-21dc-11f1-991b-6f80eaf25911",
+    "expiryDateMMYY": "0927",
+    "httpStatus": "200",
+    "maskedCardNumber": "************3555",
+    "serverDateTime": "20260317083711509",
+    "transactionReference": "75413c40-21db-11f1-991b-6f80eaf25911"
+}
+
+Error example response (transaction type not eligible for deferred tokenization):
+{
+    "error": {
+        "details": {
+            "body": {
+                "error": {
+                    "errorCode": "3112",
+                    "errorGuid": "624d05e0-21dd-11f1-991b-6f80eaf25911",
+                    "httpStatus": "403",
+                    "reason": "Transaction type is not eligible for deferred tokenization"
+                }
+            },
+            "status": 403
+        },
+        "message": "Viscus operation failed",
+        "name": "BadRequestError",
+        "statusCode": 400
+    }
+}
+```
+
 ## Transaction Result Recovery
 
 

restapi/restobjects.md

@@ -169,6 +169,40 @@ A class which holds the payment terminal status.
 }
 ````
 
+## Deferred Tokenization Response {#deferredTokenizationResponse}
+
+`DeferredTokenizationResponse` <span class="badge badge--info">Object</span>
+
+Response object returned by the [`GET /transactions/{guid}/token`](restendpoints.md#transactionsguidtoken) endpoint. Contains the card token and associated details retrieved from a completed transaction. Supported transaction types: `sale`, `refund`, `preAuthorizationCapture`, `moToSale` and `moToRefund`.
+
+**Properties**
+
+| Property      | Description |
+| ----------- | ----------- |
+| `agreementNumber`  <br />*String*   | The merchant agreement number associated with the transaction.|
+| `cardToken`  <br />*String*   | Token representing the PAN of the card. Can be used for subsequent MOTO operations.|
+| `cardTokenizationGuid`  <br />*String*   | Unique identifier of the tokenization operation.|
+| `expiryDateMMYY`  <br />*String*   | Card expiry date in MMYY format.|
+| `httpStatus`  <br />*String*   | HTTP status code of the tokenization response.|
+| `maskedCardNumber`  <br />*String*   | Masked card number, showing only the last 4 digits.|
+| `serverDateTime`  <br />*String*   | Server date and time when the token was generated, in `YYYYMMDDHHmmssSSS` format.|
+| `transactionReference`  <br />*String*   | The GUID of the original card-present transaction.|
+
+**Code example**
+
+````json
+{
+    "agreementNumber": "123456789010102",
+    "cardToken": "665630867",
+    "cardTokenizationGuid": "7df78050-21dc-11f1-991b-6f80eaf25911",
+    "expiryDateMMYY": "0927",
+    "httpStatus": "200",
+    "maskedCardNumber": "************3555",
+    "serverDateTime": "20260317083711509",
+    "transactionReference": "75413c40-21db-11f1-991b-6f80eaf25911"
+}
+````
+
 ## Financial Status{#financialStatus}
 
 `Financial Status` <span class="badge badge--info">Enum</span>