diff --git a/restapi/restendpoints.md b/restapi/restendpoints.md index 03c7d6d..eb7ebde 100644 --- a/restapi/restendpoints.md +++ b/restapi/restendpoints.md @@ -810,7 +810,7 @@ Typical fields in the request body (see [MotoSaleRequest](restobjects#motoSaleRe ```shell http POST https://cloud.handpoint.io/moto/sale \ - ApiKeyCloud:SX34S16-WRZMY6C-JNJMP9J-7B0P0TH \ + ApiKeyCloud:XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX \ amount='20.00' \ currency='EUR' \ cardToken='665630867' @@ -884,7 +884,7 @@ A very common cause of **3107** is having “CVV/CV2 input mandatory” enabled ```shell curl -X POST \ -H "Content-Type: application/json" \ - -H "ApiKeyCloud: SX34S16-WRZMY6C-JNJMP9J-7B0P0TH" \ + -H "ApiKeyCloud: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" \ -d '{ "amount": "20.00", "currency": "EUR", @@ -936,7 +936,7 @@ Supports full and partial refunds, depending on acquirer configuration. ```shell http POST https://cloud.handpoint.io/moto/refund \ - ApiKeyCloud:SX34S16-WRZMY6C-JNJMP9J-7B0P0TH \ + ApiKeyCloud:XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX \ originalGuid='1a41d9f0-cf72-11f0-95b2-770b7d1d8e67' \ amount='5.00' \ currency='EUR' @@ -987,7 +987,7 @@ Supports full and partial refunds, depending on acquirer configuration. ```shell curl -X POST \ -H "Content-Type: application/json" \ - -H "ApiKeyCloud: SX34S16-WRZMY6C-JNJMP9J-7B0P0TH" \ + -H "ApiKeyCloud: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" \ -d '{ "originalGuid": "1a41d9f0-cf72-11f0-95b2-770b7d1d8e67", "amount": "5.00", @@ -1039,7 +1039,7 @@ Typical fields (see [MotoReversalRequest](restobjects#motoReversalRequest) for f ```shell http POST https://cloud.handpoint.io/moto/reversal \ - ApiKeyCloud:RCZNP67-CB6M5VN-J4QBVGZ-9JWX765 \ + ApiKeyCloud:XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX \ originalGuid='b28bdb10-cf87-11f0-b588-a122fae316de' \ amount='20.00' \ currency='EUR' @@ -1088,7 +1088,7 @@ Typical fields (see [MotoReversalRequest](restobjects#motoReversalRequest) for f ```shell curl -X POST \ -H "Content-Type: application/json" \ - -H "ApiKeyCloud: RCZNP67-CB6M5VN-J4QBVGZ-9JWX765" \ + -H "ApiKeyCloud: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" \ -d '{ "originalGuid": "b28bdb10-cf87-11f0-b588-a122fae316de", "amount": "20.00", @@ -1097,4 +1097,125 @@ curl -X POST \ "transactionReference": "4d7b1a2c-5bfd-4a30-9b6f-123456789abc" }' \ "https://cloud.handpoint.io/moto/reversal" +``` + +## Batch Operations + +Batch operations allow you to remotely **close a batch on a specific payment terminal** using Cloud API. + +These endpoints are typically used in scenarios where the acquirer or merchant workflow is batch-based (for example, +daily settlement batches per terminal). + +Currently, the primary batch operation exposed via Cloud API is: + +- `POST /batch/close` — requests the **closure of a batch** for a given terminal (`deviceType`, `serialNumber`) and `batchNumber`. + +All request and response payloads are defined in the corresponding [Batch objects](restobjects#batch). + +--- + +### /batch/close + +`BatchClose` + +`POST /batch/close` is used to request **closure of a batch** for a specific payment terminal, identified by its +`deviceType` and `serialNumber`, and a `batchNumber`. + +Typical use cases: + +- End-of-day batch closure triggered from a back-office or back-office job. +- Manual batch close as part of a support or reconciliation process. + +#### Parameters + +| Parameter | Notes | +| --------- | ----- | +| `Header: ApiKeyCloud` Required | Cloud API key used to authenticate the merchant. | +| `Request Body: BatchCloseRequest` Required | [BatchCloseRequest](restobjects#batchCloseRequest) object containing `deviceType`, `serialNumber` and `batchNumber`. | + +Typical fields in the request body (see [BatchCloseRequest](restobjects#batchCloseRequest) for full details): + +- `deviceType` Required – Terminal model identifier (for example, `"PAXA920MAX"`). +- `serialNumber` Required – Serial number of the payment terminal (for example, `"2740013262"`). +- `batchNumber` Required – Identifier of the batch to close (for example, `"1"`). + +#### Returns + +| Result | Notes | +| ------ | ----- | +| `200` | Batch close request accepted. The response body is a [BatchCloseResponse](restobjects#batchCloseResponse) with the batch number, a unique `closeBatchGuid`, timestamps and an issuer-style response code/text. | +| `400` | Business rule error or generic gateway error. Returned as `BadRequestError`, with `error.code`, `error.message` and `error.details` describing the problem. | +| `422` | Payload validation error (`VALIDATION_FAILED`) when required fields are missing or do not match the schema (for example, missing `batchNumber`). | +| `5xx` | Internal error or service unavailability. The final outcome of the batch close may be unknown and may require reconciliation or a retry at a later time. | + +#### Behaviour examples + +**Happy path – close batch 1 for a terminal** + +```shell +http POST https://cloud.handpoint.io/batch/close \ + ApiKeyCloud:XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX \ + deviceType='PAXA920MAX' \ + serialNumber='2740013262' \ + batchNumber='1' +```` + +Example response: + +```json +{ + "batchNumber": "1", + "closeBatchGuid": "14431ad0-d0dc-11f0-9ed0-695d1a368668", + "closedAt": "20251204064010281", + "customerReference": {}, + "httpStatus": "200", + "issuerResponseCode": "00", + "issuerResponseText": "ACCEPTED" +} +``` + +**Validation error – missing `batchNumber`** + +```shell +http POST https://cloud.handpoint.io/batch/close \ + ApiKeyCloud:XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX \ + deviceType='PAXA920MAX' \ + serialNumber='2740013262' +``` + +Response: + +```json +{ + "error": { + "code": "VALIDATION_FAILED", + "details": [ + { + "code": "required", + "info": { + "missingProperty": "batchNumber" + }, + "message": "must have required property 'batchNumber'", + "path": "" + } + ], + "message": "The request body is invalid. See error object `details` property for more info.", + "name": "UnprocessableEntityError", + "statusCode": 422 + } +} +``` + +#### Code example – Close batch via `curl` + +```shell +curl -X POST \ + -H "Content-Type: application/json" \ + -H "ApiKeyCloud: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" \ + -d '{ + "deviceType": "PAXA920MAX", + "serialNumber": "2740013262", + "batchNumber": "1" + }' \ + "https://cloud.handpoint.io/batch/close" ``` \ No newline at end of file diff --git a/restapi/restobjects.md b/restapi/restobjects.md index b5b9206..334adf0 100644 --- a/restapi/restobjects.md +++ b/restapi/restobjects.md @@ -1011,4 +1011,66 @@ The exact shape is very similar across these operations; some fields (such as `o "serverDateTime": "20251202140733578", "terminalDateTime": "20251202140733000" } +``` + +## Batch {#batch} + +### BatchCloseRequest {#batchCloseRequest} + +`BatchCloseRequest` Object + +Object used by the [`POST /batch/close`](restendpoints#batch-operations) endpoint to request closure of a batch for a specific payment terminal. + +**Properties** + +| Property | Description | +| -------- | ----------- | +| `deviceType` Required
*String* | Terminal model identifier, matching the device type configured in Cloud API (for example, `"PAXA920MAX"`). | +| `serialNumber` Required
*String* | Serial number of the payment terminal whose batch is being closed (for example, `"2740013262"`). | +| `batchNumber` Required
*String* | Identifier of the batch to close (for example, `"1"`, `"2"`). Typically a numeric string defined by the acquirer or terminal configuration. | +| `customerReference`
*String \| Object* | Optional reference or metadata defined by the integrator. If provided, it can be echoed back in the response for reconciliation. | + +**Code example** + +```json +{ + "deviceType": "PAXA920MAX", + "serialNumber": "2740013262", + "batchNumber": "1", + "customerReference": "end-of-day-2025-12-04" +} +``` + +--- + +### BatchCloseResponse {#batchCloseResponse} + +`BatchCloseResponse` Object + +Object returned by [`POST /batch/close`](restendpoints#batch-operations) when the batch close request is accepted by the gateway. + +**Properties** + +| Property | Description | +| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `batchNumber`
*String* | Batch number that was requested to be closed. Mirrors the `batchNumber` from the request. | +| `closeBatchGuid`
*String* | Unique identifier for the batch close operation. Can be used for support and audit purposes. | +| `closedAt`
*String* | Timestamp (gateway internal format) indicating when the batch close request was processed (for example, `"20251204064010281"`). | +| `customerReference`
*Object* | Optional reference or metadata associated with this batch close. May be an empty object if no metadata was provided. | +| `httpStatus`
*String* | HTTP status code as returned by the gateway (for example, `"200"`). | +| `issuerResponseCode`
*String* | Response code for the batch close operation (for example, `"00"` for accepted). | +| `issuerResponseText`
*String* | Human-readable description of the response (for example, `"ACCEPTED"`). | + +**Code example** + +```json +{ + "batchNumber": "1", + "closeBatchGuid": "14431ad0-d0dc-11f0-9ed0-695d1a368668", + "closedAt": "20251204064010281", + "customerReference": {}, + "httpStatus": "200", + "issuerResponseCode": "00", + "issuerResponseText": "ACCEPTED" +} ``` \ No newline at end of file