From 22b433cf7def2b8fb984ea0f6d6cebd219271f66 Mon Sep 17 00:00:00 2001 From: ecunado Date: Tue, 17 Mar 2026 09:51:53 +0100 Subject: [PATCH 1/6] docs(rest-api): add deferred tokenization endpoint documentation Documents the GET /transactions/{guid}/token endpoint that allows merchants to retrieve a card token from a previously completed card-present transaction. Adds DeferredTokenizationResponse object to the objects reference. Co-Authored-By: Claude Sonnet 4.6 --- restapi/restendpoints.md | 71 ++++++++++++++++++++++++++++++++++++++++ restapi/restobjects.md | 34 +++++++++++++++++++ 2 files changed, 105 insertions(+) diff --git a/restapi/restendpoints.md b/restapi/restendpoints.md index cebcf08a..5a587774 100644 --- a/restapi/restendpoints.md +++ b/restapi/restendpoints.md @@ -311,6 +311,77 @@ Error example response (using invalid guid): } ``` +## /transactions/\{guid\}/token \{#transactionsguidtoken\} + +`DeferredTokenization` + +GET endpoint used to retrieve a card token from a previously completed card-present transaction. This operation, known as **deferred tokenization**, allows merchants to obtain a card token at any point after a `sale` or `refund` transaction has been completed on the terminal, without requiring tokenization to be enabled at the time of the original transaction. + +The returned `cardToken` can then be used to perform subsequent MOTO operations (e.g. [`POST /moto/sale`](#moto-operations-no-reader)). + +:::note +Deferred tokenization is only available for `sale` and `refund` transaction types. Other transaction types (e.g. tip adjustments) will return a `400` error. +::: + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `Header: ApiKeyCloud` Required
*String* | Api key used to authenticate the merchant. (UNIQUE per Merchant) | +| `Path parameter: guid` Required
*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 diff --git a/restapi/restobjects.md b/restapi/restobjects.md index 2636cac4..255a7333 100644 --- a/restapi/restobjects.md +++ b/restapi/restobjects.md @@ -169,6 +169,40 @@ A class which holds the payment terminal status. } ```` +## Deferred Tokenization Response {#deferredTokenizationResponse} + +`DeferredTokenizationResponse` Object + +Response object returned by the [`GET /transactions/{guid}/token`](restendpoints.md#transactionsguidtoken) endpoint. Contains the card token and associated details retrieved from a completed card-present transaction. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `agreementNumber`
*String* | The merchant agreement number associated with the transaction.| +| `cardToken`
*String* | Token representing the PAN of the card. Can be used for subsequent MOTO operations.| +| `cardTokenizationGuid`
*String* | Unique identifier of the tokenization operation.| +| `expiryDateMMYY`
*String* | Card expiry date in MMYY format.| +| `httpStatus`
*String* | HTTP status code of the tokenization response.| +| `maskedCardNumber`
*String* | Masked card number, showing only the last 4 digits.| +| `serverDateTime`
*String* | Server date and time when the token was generated, in `YYYYMMDDHHmmssSSS` format.| +| `transactionReference`
*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` Enum From 903bb1b11a26a58656afde0a2d29402f66fe88e4 Mon Sep 17 00:00:00 2001 From: ecunado Date: Tue, 17 Mar 2026 10:02:09 +0100 Subject: [PATCH 2/6] docs(rest-api): fix supported operation types for deferred tokenization Add all eligible transaction types: sale, refund, preAuthorizationCapture, moToSale and moToRefund. Co-Authored-By: Claude Sonnet 4.6 --- restapi/restendpoints.md | 2 +- restapi/restobjects.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/restapi/restendpoints.md b/restapi/restendpoints.md index 5a587774..4aaf473f 100644 --- a/restapi/restendpoints.md +++ b/restapi/restendpoints.md @@ -320,7 +320,7 @@ GET endpoint used to retrieve a card token from a previously completed card-pres The returned `cardToken` can then be used to perform subsequent MOTO operations (e.g. [`POST /moto/sale`](#moto-operations-no-reader)). :::note -Deferred tokenization is only available for `sale` and `refund` transaction types. Other transaction types (e.g. tip adjustments) will return a `400` error. +Deferred tokenization is supported for the following transaction types: `sale`, `refund`, `preAuthorizationCapture`, `moToSale` and `moToRefund`. Other transaction types will return a `400` error. ::: **Parameters** diff --git a/restapi/restobjects.md b/restapi/restobjects.md index 255a7333..a2125c9b 100644 --- a/restapi/restobjects.md +++ b/restapi/restobjects.md @@ -173,7 +173,7 @@ A class which holds the payment terminal status. `DeferredTokenizationResponse` Object -Response object returned by the [`GET /transactions/{guid}/token`](restendpoints.md#transactionsguidtoken) endpoint. Contains the card token and associated details retrieved from a completed card-present transaction. +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** From e024e0ddd1f0f51bb9e83d570b7c0c323aa6cef6 Mon Sep 17 00:00:00 2001 From: ecunado Date: Tue, 17 Mar 2026 10:08:11 +0100 Subject: [PATCH 3/6] docs(rest-api): update deferred tokenization description to include all supported types Co-Authored-By: Claude Sonnet 4.6 --- restapi/restendpoints.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/restapi/restendpoints.md b/restapi/restendpoints.md index 4aaf473f..fcec5a97 100644 --- a/restapi/restendpoints.md +++ b/restapi/restendpoints.md @@ -315,7 +315,7 @@ Error example response (using invalid guid): `DeferredTokenization` -GET endpoint used to retrieve a card token from a previously completed card-present transaction. This operation, known as **deferred tokenization**, allows merchants to obtain a card token at any point after a `sale` or `refund` transaction has been completed on the terminal, without requiring tokenization to be enabled at the time of the original transaction. +GET endpoint used to retrieve a card token from a previously completed card-present transaction. This operation, known as **deferred tokenization**, allows merchants to obtain a card token at any point after a supported transaction (`sale`, `refund`, `preAuthorizationCapture`, `moToSale` or `moToRefund`) has been completed, without requiring tokenization to be enabled at the time of the original transaction. The returned `cardToken` can then be used to perform subsequent MOTO operations (e.g. [`POST /moto/sale`](#moto-operations-no-reader)). From 3f213b9c89dbc78dc4be137387a65fe1d61282d4 Mon Sep 17 00:00:00 2001 From: ecunado Date: Tue, 17 Mar 2026 10:10:35 +0100 Subject: [PATCH 4/6] docs(rest-api): improve deferred tokenization description Remove redundant type list from prose (already in the note box) and broaden cardToken use cases beyond MOTO operations. Co-Authored-By: Claude Sonnet 4.6 --- restapi/restendpoints.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/restapi/restendpoints.md b/restapi/restendpoints.md index fcec5a97..35afda39 100644 --- a/restapi/restendpoints.md +++ b/restapi/restendpoints.md @@ -315,9 +315,7 @@ Error example response (using invalid guid): `DeferredTokenization` -GET endpoint used to retrieve a card token from a previously completed card-present transaction. This operation, known as **deferred tokenization**, allows merchants to obtain a card token at any point after a supported transaction (`sale`, `refund`, `preAuthorizationCapture`, `moToSale` or `moToRefund`) has been completed, without requiring tokenization to be enabled at the time of the original transaction. - -The returned `cardToken` can then be used to perform subsequent MOTO operations (e.g. [`POST /moto/sale`](#moto-operations-no-reader)). +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. From 40c5505a39c54384992bf823d7ffc5243a753ecd Mon Sep 17 00:00:00 2001 From: ecunado Date: Tue, 17 Mar 2026 12:34:24 +0100 Subject: [PATCH 5/6] docs(ia): CLAUDE.md --- CLAUDE.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..b18d81e4 --- /dev/null +++ b/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. From 118d66dd033e792b7f7eba30a83e76b4ddd79777 Mon Sep 17 00:00:00 2001 From: ecunado Date: Tue, 17 Mar 2026 12:35:59 +0100 Subject: [PATCH 6/6] docs(rest-api): add 12-month tokenization window warning to deferred tokenization endpoint Co-Authored-By: Claude Sonnet 4.6 --- restapi/restendpoints.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/restapi/restendpoints.md b/restapi/restendpoints.md index 35afda39..d73e435b 100644 --- a/restapi/restendpoints.md +++ b/restapi/restendpoints.md @@ -321,6 +321,10 @@ GET endpoint used to retrieve a card token from a previously completed transacti 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 |