PayFacto API - v1.0 - POST /v1/signature/get

Retrieves the cardholder signature captured at a semi-integrated terminal for a specific transaction. The signature is returned as a Base64-encoded image. Used for record-keeping. No transaction is processed and no record is modified.

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 Get Signature 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

Signatures are captured only on semi-integrated terminal transactions (InputType=N). This endpoint is not applicable to E-Commerce or MOTO transactions. A signature is only available when the terminal captured one during the original transaction.

✍️

Base64-Encoded Image Response

The signature field is returned as a Base64-encoded image string. Decode it before rendering or embedding in a receipt. The image format is determined by the terminal model; common formats include PNG and BMP.

🔍

Read-Only Operation

This endpoint retrieves data only. No transaction is processed and no record is modified.

Request

POST https://test.api.payfacto.cloud/v1/signature/get

ℹ️

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 on which the original transaction was processed. 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`
TransactionNumber	Numeric(12)	The PayFacto gateway transaction identifier of the transaction whose signature to retrieve. This is the `transactionNumber` returned in the original terminal transaction response. Example: `000111222333`

Request — Code Example

⚠️

The example below uses the test endpoint and a sandbox API key. Replace credentials and base URL before going live. The TransactionNumber must be the transactionNumber from the original terminal transaction response.

cURL

# Get Signature -- POST /v1/signature/get
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&MerchantTerminalNumber=12345&LanguageCode=E&OperatorID=USER0001&TransactionNumber=000111222333"

# 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/signature/get" \
  -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` = signature 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.
timeStamp	Alphanumeric(17)	Date and time the request was processed. Format: `YYYYMMDD-HHMMSSCC`. Example: `20240515-15000100`

Conditionally returned

Field	Type	Description
signature	Alphanumeric	★ Decode before use. Returned when `returnCode` is `00` and a signature was captured for the transaction. Base64-encoded image of the cardholder's signature. Decode to binary before rendering or embedding in a receipt. Image format (PNG, BMP) depends on the terminal model.
errorDescription	Alphanumeric(50)	Only returned when the request fails. Human-readable description of the failure reason.

ℹ️

Rendering the signature image. The signature field contains the raw Base64 string. To render it in HTML, prepend the appropriate data URI scheme and embed it in an img tag. For a PNG signature:

<img src="data:image/png;base64,{signature}" alt="Cardholder Signature" />

Response — Code Example

JSON — 200 Success

{
  "returnCode":  "00",
  "serverNumber": "0001",
  "timeStamp":   "20240515-15000100",
  "signature":   "iVBORw0KGgoAAAANSUhEUgAA..."
}

JSON — Error

{
  "returnCode":       "9033",
  "errorDescription": "INVALID POS TERMINAL NUMBER",
  "serverNumber":     "0001",
  "timeStamp":        "20240515-15000200"
}

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	Signature retrieved	The signature image was retrieved successfully for the specified transaction.	Decode the Base64 `signature` value to binary before rendering. Use a data URI for HTML embedding (e.g. `data:image/png;base64,{signature}`) or write the decoded bytes to a file.
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 on which the original transaction was processed.
9032 / 9033	Invalid / rejected: POS terminal number	`MerchantTerminalNumber` does not follow the specification, or the terminal is not configured for this merchant.	Check your application. Confirm the terminal number matches the terminal on which the original transaction was processed. If the problem persists, contact PayFacto customer service.
9051	Time out	Request processing timed out.	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.