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. diff --git a/restapi/restendpoints.md b/restapi/restendpoints.md index cebcf08a..d73e435b 100644 --- a/restapi/restendpoints.md +++ b/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` 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..a2125c9b 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 transaction. Supported transaction types: `sale`, `refund`, `preAuthorizationCapture`, `moToSale` and `moToRefund`. + +**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