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

Queries the current open batch totals at a semi-integrated terminal. Returns a summary for all cards combined as well as totals by card type amounts accumulated since the last batch close. Used for end-of-day reconciliation before calling /v1/closeBatch. No batch is closed and no transaction is processed.

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 Total 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}. This endpoint does not require card data, amounts, or invoice numbers.

🖥️

Semi-Integrated Terminal Only

This endpoint targets a specific semi-integrated terminal via MerchantTerminalNumber. It is not applicable to E-Commerce or MOTO transactions. The terminal must not be processing another transaction when this request is sent.

🔍

Read-Only Operation

This endpoint queries batch totals only. No batch is closed and no transaction is processed. To close and settle the current batch, use /v1/closeBatch.

Request

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

ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. This endpoint does not require card data, amounts, or invoice numbers.

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 whose current batch totals to retrieve. Example: `12345`
LanguageCode	Alphanumeric(1)	Language for PayFacto responses. `F` = French, `E` = English.
OperatorID	Alphanumeric(8)	Identifies the cashier, agent, or system that initiated the request. 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

# Total Batch -- POST /v1/totalBatch
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&MerchantTerminalNumber=12345&LanguageCode=E&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/totalBatch" \
  -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 result of the request. `00` = batch totals retrieved successfully. All other values indicate a failure. Refer to Section 6 for endpoint-specific codes.
serverNumber	Alphanumeric(4)	Identifies the PayFacto Network server that processed the request.
terminalNumber	Numeric(5)	Identifies the terminal in the PayFacto Network that was queried.
timeStamp	Alphanumeric(17)	Date and time the request was processed. Format: `YYYYMMDD-HHMMSSCC`. Example: `20240515-17000100`

Conditionally returned — Batch totals

Returned when returnCode is 00. These fields summarize the transactions accumulated in the current open batch since the last /v1/closeBatch call. All amount fields are left (0) padded to 11 digits.

Field	Type	Description
batchNumber	Numeric(4)	The number of the current open batch. Example: `0012`
purchaseCount	Numeric	Number of approved purchase transactions in the current batch. Example: `7`
purchaseAmount	Numeric(11)	Total amount of all approved purchase transactions in the current batch, left (0) padded. Example: `00000085000` = $850.00
refundCount	Numeric	Number of approved refund transactions in the current batch. Example: `1`
refundAmount	Numeric(11)	Total amount of all approved refund transactions in the current batch, left (0) padded. Example: `00000010000` = $100.00
totalCount	Numeric	Total number of all approved transactions in the current batch (`purchaseCount` + `refundCount`). Example: `8`
totalAmount	Numeric(11)	Net batch total (`purchaseAmount` minus `refundAmount`), left (0) padded. Example: `00000075000` = $750.00
demoMode	Alphanumeric(4)	Only returned when the terminal is in demo mode. Value will be `true`.
errorDescription	Alphanumeric(50)	Only returned when the request fails. Human-readable description of the failure reason.

Response — Code Example

JSON — 200 Success

{
  "returnCode":      "00",
  "serverNumber":    "0001",
  "terminalNumber":  "12345",
  "timeStamp":       "20240515-17000100",
  "batchNumber":     "0012",
  "purchaseCount":   "7",
  "purchaseAmount":  "00000085000",
  "refundCount":     "1",
  "refundAmount":    "00000010000",
  "totalCount":      "8",
  "totalAmount":     "00000075000"
}

JSON — Error (terminal busy)

{
  "returnCode":       "3667",
  "errorDescription": "SEMI-INTEGRATED TERMINAL IS BUSY",
  "serverNumber":     "0001",
  "terminalNumber":   "12345",
  "timeStamp":        "20240515-17000200"
}

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	Batch totals retrieved	The current batch totals were retrieved successfully from the terminal.	Reconcile `purchaseAmount`, `refundAmount`, and `totalAmount` against your records before calling `/v1/closeBatch`.
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 in the payload.	Provide the terminal number of the semi-integrated terminal to query.
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.
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.
9051	Time out	Request processing timed out. Often caused by an inactive Dispatcher module.	Retry the request. If the problem persists, contact PayFacto customer service.
9049 / 9050	Fatal error	A critical error occurred while processing the request.	Retry the request. If the problem persists, contact PayFacto customer service.