PayFacto API - v1.0 - POST /v1/closeBatch

Closes the current open batch on a Semi-Integrated terminal, triggering settlement of all transactions accumulated in that batch with the banking acquirer. No new transactions can be submitted to the terminal while a batch closing is in progress.

Prerequisites

🔑

API Key

Generate your API key from the Payments Manager: Administrator Client → API Key → Add New Key. Pass it as auth-api-key in every request.

🏪

Company & Merchant Numbers

Your CompanyNumber (5-digit) and MerchantNumber (8-digit) are issued by PayFacto during onboarding. Both are required on every Close Batch request.

🌐

Environment Base URL

Test: https://test.api.payfacto.cloud/v1 | Production: Provided by the PayFacto Integration team upon certification.

📦

Request Format — Base64-Encoded Payload

Requests use HTTP POST with an application/x-www-form-urlencoded body. Assemble all parameters as a cleartext query string, Base64-encode it, then send: auth-api-key={key}&payload={base64}.

🖥️

Semi-Integrated Terminal Only

Close Batch is exclusively a terminal administrative operation. The terminal identified by MerchantTerminalNumber must be online and available. Blank spaces are not accepted for this field.

⚠️

Transaction Lockout During Batch Close

No transaction can be submitted to the terminal while a batch closing is in progress. Attempting to do so will return return code 9115. Wait for the batch close to complete before resuming normal transaction processing. The batch number is generated by the terminal and returned in every transaction response as batchNumber.

Request

POST https://test.api.payfacto.cloud/v1/closeBatch

ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. MerchantTerminalNumber must be the assigned terminal number — blank spaces are not accepted. This endpoint has no optional fields.

Required fields

Field	Type	Description
CompanyNumber	Numeric(5)	Identifies the merchant on PayFacto's network. Provided by PayFacto during onboarding. Example: `12345`
MerchantNumber	Numeric(8)	Identifies the merchant to PayFacto's network. Provided by the integration team. Example: `53400000`
MerchantTerminalNumber	Numeric(5)	Identifies the Semi-Integrated terminal on PayFacto's network whose batch is to be closed. Must be the assigned terminal number — blank spaces are not accepted. Example: `12345`
BatchNumber	Numeric(4)	The batch number identifying the batch to be closed. This value is returned as `batchNumber` in the response of every transaction processed on this terminal. The batch number must be unique and must identify an open batch. Example: `0001`
OperatorID	Alphanumeric(8)	Identifies the cashier or system that initiated the batch close. Useful for identifying the employee who generated the transaction on PayFacto's network. Example: `USER0001`

Request — Code Example

⚠️

The example below uses the test endpoint and a sandbox API key. Replace credentials and base URL before going live.

cURL

# Close Batch — POST /v1/closeBatch
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&MerchantTerminalNumber=12345&BatchNumber=0001&OperatorID=USER0001"

# Step 2: Base64-encode the payload
ENCODED=$(echo -n "$PAYLOAD" | base64)

# Step 3: Submit the request
curl -X POST "https://test.api.payfacto.cloud/v1/closeBatch" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"

Response

Always returned

Field	Type	Description
returnCode	Alphanumeric(4)	Identifies the exact status of the result. `00` = batch closed successfully. All other values indicate a failure. Refer to Section 6 for endpoint-specific codes.
batchNumber	Numeric(4)	The batch number that was closed, as used by the terminal when processing the transactions in the batch. Example: `0001`
transactionNumber	Numeric(12)	Unique PayFacto gateway transaction identifier for the batch close operation. Example: `000111222333`
companyNumber	Numeric(5)	Echo of the request CompanyNumber.
merchantNumber	Numeric(8)	Echo of the request MerchantNumber.
operatorId	Alphanumeric(8)	Echo of the request OperatorID.
serverNumber	Alphanumeric(4)	Identifies the PayFacto Network server that processed the batch close.
terminalNumber	Numeric(5)	Identifies the terminal in the PayFacto Network whose batch was closed.
timeStamp	Alphanumeric(17)	Date and time the batch close was processed on the payment server. Format: `YYYYMMDD-HHMMSSCC`. Example: `20240515-23000100`
receiptDisp	Alphanumeric(32)	PayFacto-generated message for the batch close. Can be used to produce a receipt. Example: `APPROVED-THANK-YOU`
terminalDisp	Alphanumeric(24)	Message displayed on the terminal following the batch close. Example: `APPROVED`

Conditionally returned

Field	Type	Description
demoMode	Alphanumeric(4)	Only returned when the terminal is in demo mode. Value will be `true`.
errorDescription	Alphanumeric(50)	Only returned when the batch close is not successful. Human-readable description of the failure reason.

Response — Code Example

JSON — 200 Batch Closed Successfully

{
  "returnCode":        "00",
  "batchNumber":       "0001",
  "transactionNumber": "000111222333",
  "companyNumber":     "12345",
  "merchantNumber":    "53400000",
  "operatorId":        "USER0001",
  "serverNumber":      "0001",
  "terminalNumber":    "12345",
  "timeStamp":         "20240515-23000100",
  "receiptDisp":       "APPROVED-THANK-YOU      ",
  "terminalDisp":      "APPROVED        "
}

JSON — Error

{
  "returnCode":        "9221",
  "errorDescription":  "BATCH NOT OPEN",
  "terminalDisp":      "DECLINED        ",
  "receiptDisp":       "DECLINED                ",
  "transactionNumber": "000111222334",
  "timeStamp":         "20240515-23000200"
}

Error / Return Codes

The following codes are most relevant to this endpoint. For the complete catalogue see the Return Code Index.

Return Code	Meaning	When it occurs	Recommended Action
00	Transaction approved	The batch was closed and settlement with the banking acquirer was triggered successfully.	No further action required. Normal transaction processing can resume.
9004	"Null" value: company number	`CompanyNumber` is null or blank in the payload.	Check your application. The field must correspond to the specification in the documentation.
9005 / 9006	Invalid / rejected: company number	`CompanyNumber` does not match the required 5-digit length or is not configured in the payment solution.	Make sure the application uses the correct company number provided by PayFacto. If it does, contact PayFacto customer service.
9007	"Null" value: merchant number	`MerchantNumber` is null or blank in the payload.	Check your application. The field must correspond to the specification in the documentation.
9008 / 9009	Invalid / rejected: merchant number	`MerchantNumber` does not match the required 8-digit length or is not configured in the payment solution.	Make sure the application uses the merchant number provided by PayFacto. If it does, contact PayFacto customer service.
9031	"Null" value: POS terminal number	`MerchantTerminalNumber` is null or blank. A valid terminal number is required for this endpoint.	Check your application. The field must correspond to the specification in the documentation.
9032 / 9033	Invalid / rejected: POS terminal number	`MerchantTerminalNumber` does not follow the specification, or the merchant is not configured as a POS terminal merchant.	Check your application. The field must correspond to the specification in the documentation. If the problem persists, contact PayFacto customer service.
9040 / 9041 / 9042	Null / invalid / rejected: operator ID	`OperatorID` is null, exceeds 8 characters, or does not follow the specification.	Check your application. The field must correspond to the specification in the documentation.
9106	Batch not ready to close	The batch is not in a state that allows closing at this time.	Wait a moment and retry. If the problem persists, contact PayFacto customer service.
9115	Administrative transaction in progress	A batch closing process is already in progress for this merchant. No transaction can be performed while a batch close is underway.	Wait a few moments for the current batch close to complete, then retry.
9219 / 9220	Rejected / invalid: batch number	`BatchNumber` was rejected because it does not follow the specification, or does not match the required 4-digit length.	Check your application. The batch number must match the specification stated in the documentation.
9221	Batch not open	The batch identified by `BatchNumber` is not currently open and cannot be closed.	Verify the batch number. Use the batch number returned in the most recent transaction response for the target terminal.
9222	Batch not found or not closable	The batch identified by `BatchNumber` was not found or is in a state that prevents it from being closed.	Verify the batch number. If the problem persists, contact PayFacto customer service.
9223	Batch total not found	The selected batch does not exist or is empty. A batch must contain at least one transaction before it can be closed.	Use a different batch number that contains transactions. If the problem persists, contact PayFacto customer service.
3666	One or more terminals are busy	All of the merchant's terminals are currently processing transactions.	Wait and retry. If the problem persists, contact PayFacto customer service.
3667	Semi-integrated terminal is busy	The target terminal is currently processing another transaction or a recovery is in progress.	Wait 15 seconds and retry. If the problem persists, contact PayFacto customer service.
3668	Waiting for a recovery	An error occurred with the semi-integrated terminal. A recovery must be completed before another operation can be processed.	Make sure everything is plugged in correctly. If needed, restart the driver and unplug then replug the terminal power. Wait 35 seconds and retry. If the problem persists, contact PayFacto customer service.
3777	Inexistent terminal and/or merchant	The merchant or terminal has not been configured in the Dispatcher module.	If the problem persists, contact PayFacto customer service.
MB	Batch already closed	A request was made to close a batch file that has already been closed.	No further action is needed — the batch was already closed successfully. Verify the batch number before retrying.
M0	Batch closing required	The transaction log has reached its maximum capacity or the maximum number of transactions per batch has been reached. PayFacto will automatically initiate a batch close upon receiving this code.	Wait a few moments and retry the transaction. If the problem persists, contact PayFacto customer service.
9051	Time out	Processing timed out. Often caused by an inactive Dispatcher module.	Retry the operation. If the problem persists, contact PayFacto customer service.
9049 / 9050	Fatal error	A critical error occurred while processing the batch close.	Retry the operation. If the problem persists, contact PayFacto customer service.