PayFacto API - v1.0 - POST /v1/datacandy/completeCancel

Commits or cancels a previously initiated DataCandy transaction (such as an activation or redemption). The transactionConfirmationNumber returned by the prior DataCandy operation and the Action field (C = commit, A = cancel) are both required.

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 DataCandy Complete / Cancel 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}. For terminal transactions (InputType=N), send CardNumber as 40 space characters and ExpirationDate as 4 space characters.

🎁

DataCandy Gift & Loyalty Cards

DataCandy is a gift and loyalty card solution integrated through PayFacto. All DataCandy endpoints operate on cards identified by CardNumber. DataCandy card transactions are identified by card type F (Datacandy/fidelity) in the response. Refer to the DataCandy documentation for account type numbers and card program specifics.

🔄

Second Step of a DataCandy Transaction Flow

This endpoint is the mandatory second step after any DataCandy transaction that returns a transactionConfirmationNumber (e.g., /v1/datacandy/activate, /v1/datacandy/redemption). Use Action=C to commit (confirm) the transaction and apply it permanently to the card, or Action=A to cancel it and restore the card to its previous state. The transactionConfirmationNumber saved from the prior DataCandy response is required here.

Request

POST https://test.api.payfacto.cloud/v1/datacandy/completeCancel

ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. For terminal transactions (InputType=N), send CardNumber as 40 space characters and ExpirationDate as 4 space characters. 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`
CustomerNumber	Alphanumeric(8)	Merchant-assigned customer identifier. Associates a client record with the transaction. Example: `CLIENT12`
Amount	Numeric(11)	The amount of the transaction being committed or cancelled, including the decimal portion, left (0) padded. Must match the amount of the original DataCandy transaction. Example: `00000002500` = $25.00
InvoiceNumber	Alphanumeric(12)	Merchant-generated invoice number associated with this Complete / Cancel operation. May be unique or reused per merchant needs. Example: `CMT000000001`
InputType	Alphanumeric(1)	How the transaction is initiated. `N` = terminal/pinpad (Semi-Integrated), `I` = Internet/E-Commerce, `M` = MOTO, `U` = Unattended.
CardType	Alphanumeric(1)	Card brand. For `InputType=N` send a blank space. For `I`/`M`: `A` = Amex, `M` = Mastercard, `V` = Visa, `I` = Diners, `O` = Discover. Blank for unknown.
CardNumber	Alphanumeric(40)	The DataCandy gift or loyalty card number, left-justified and space-padded to 40 characters. For `InputType=N`, send 40 space characters — the terminal reads the card directly.
ExpirationDate	Numeric(4)	Card expiration date in `MMYY` format. For `InputType=N`, send 4 space characters. Example: `1226`
MerchantTerminalNumber	Numeric(5)	Identifies the terminal on PayFacto's network. For E-Commerce transactions, send 5 blank spaces. Example: `12345`
LanguageCode	Alphanumeric(1)	Language for PayFacto responses and terminal display. `F` = French, `E` = English.
CurrencyCode	Alphanumeric(3)	Currency of the transaction (indicative only). `CAD` = Canadian dollars, `USD` = US dollars (requires a US merchant number).
OperatorID	Alphanumeric(8)	Identifies the cashier, agent, or system that initiated the transaction. Example: `USER0001`
TransactionConfirmationNumber	Numeric	The confirmation number returned in the `transactionConfirmationNumber` field of the prior DataCandy transaction response (e.g., activate, redemption). Identifies which pending DataCandy transaction to commit or cancel. Example: `987654321`
Action	Alphanumeric(1)	Determines whether to commit or cancel the prior DataCandy transaction. `C` = Commit — confirms the transaction and permanently applies the balance change to the card. `A` = Cancel — annuls the transaction and restores the card to its previous state.

Request — Code Example

⚠️

The example below uses the test endpoint and a sandbox API key, and shows a commit (Action=C) for an E-Commerce flow. Replace credentials and base URL before going live.

cURL

# DataCandy Complete / Cancel -- POST /v1/datacandy/completeCancel
# Step 1: Build the cleartext payload (Action=C to commit, Action=A to cancel)
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&Amount=00000002500&InvoiceNumber=CMT000000001&InputType=I&CardType= &CardNumber=6006491000000000001                   &ExpirationDate=1226&MerchantTerminalNumber=     &LanguageCode=E&CurrencyCode=CAD&OperatorID=USER0001&TransactionConfirmationNumber=987654321&Action=C"

# 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/datacandy/completeCancel" \
  -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` = operation successful. All other values indicate a failure. Refer to Section 6 for endpoint-specific codes.
balanceAmount	Numeric(12)	The balance in dollars available on the card following the commit or cancel. Example: `000000002500` = $25.00
totalBalanceAmount	Numeric(12)	The total balance on the card including all locked amounts following the commit or cancel. Example: `000000002500` = $25.00
accountTypeNumber	Numeric(1)	The account type number associated with the DataCandy card program. Refer to the DataCandy documentation for possible values.
pic	Numeric(1)	Indicates whether the card's profile is complete. `1` = complete, `0` = incomplete.
transactionNumber	Numeric(12)	Unique PayFacto gateway transaction identifier for this Complete / Cancel operation. Example: `000111222444`
cardNumber	Alphanumeric(40)	Echo of the request CardNumber (masked).
cardType	Alphanumeric(1)	Card type determined by the network. For DataCandy transactions this will always be `F` (Datacandy/fidelity).
companyNumber	Numeric(5)	Echo of the request CompanyNumber.
expirationDate	Numeric(4)	Echo of the request ExpirationDate, in `MMYY` format.
invoiceNumber	Alphanumeric(12)	Echo of the request InvoiceNumber.
languageCode	Alphanumeric(1)	Echo of the request LanguageCode.
merchantNumber	Numeric(8)	Echo of the request MerchantNumber.
operatorId	Alphanumeric(8)	Echo of the request OperatorID.
receiptDisp	Alphanumeric(32)	PayFacto-generated receipt message. Can be used to produce a receipt. Example: `APPROVED-THANK-YOU`
referenceNumber	Alphanumeric(10)	Reference number obtained following successful processing of the operation.
sequenceNumber	Alphanumeric(12)	Sequence number generated by the banking acquirer.
serverNumber	Alphanumeric(4)	Identifies the PayFacto Network server that processed the operation.
terminalDisp	Alphanumeric(24)	Message displayed on the terminal or payment page. Example: `APPROVED`
terminalNumber	Numeric(5)	Identifies the terminal in the PayFacto Network used to process the operation.
timeStamp	Alphanumeric(17)	Date and time the operation was processed on the payment server. Format: `YYYYMMDD-HHMMSSCC`. Example: `20240515-14300100`
trxDate	Numeric(8)	Transaction date at the banking acquirer. Format: `MMDDYYYY`. May differ from timeStamp.
trxMethod	Alphanumeric(3)	Summarizes how the transaction was processed. First character: `D` = swiped, `T` = manual entry. Third character: `1` = authorized. Example: `T@1`
trxTime	Numeric(6)	Transaction time at the banking acquirer. Format: `HHMMSS`. May differ from timeStamp.
trxType	Alphanumeric(1)	Type of card used. For DataCandy transactions this will be `F` = Fidelity/Gift.

Conditionally returned

Field	Type	Description
startDate	Alphanumeric(10)	Only returned when the card has a start date later than its activation date. If not returned, the card is active. Format: `YYYY-MM-DD`. Example: `2024-12-31`
ctm	String(155)	Only returned when the DataCandy program has a consumer targeted message configured. A multiple-line message to be printed on the customer receipt. Each line is separated by a pipe `\|` character.
customerNumber	Alphanumeric(8)	Only returned when provided in the request. Echo of the request CustomerNumber.
demoMode	Alphanumeric(4)	Only returned when the terminal is in demo mode. Value will be `true`.
errorDescription	Alphanumeric(50)	Only returned when the operation is not successful. Human-readable description of the failure reason.
terminalInvoiceNumber	Numeric(12)	Only returned for terminal transactions. Terminal-assigned invoice number.

Response — Code Example

JSON — 200 Commit Approved

{
  "returnCode":         "00",
  "transactionNumber":  "000111222444",
  "referenceNumber":    "0000000002",
  "balanceAmount":      "000000002500",
  "totalBalanceAmount": "000000002500",
  "accountTypeNumber":  "1",
  "pic":                "1",
  "cardNumber":         "6006491XXXXX0001                       ",
  "cardType":           "F",
  "trxType":            "F",
  "trxDate":            "05152024",
  "trxTime":            "143501",
  "trxMethod":          "T@1",
  "timeStamp":          "20240515-14350100",
  "sequenceNumber":     "000011112223",
  "serverNumber":       "0001",
  "terminalNumber":     "00001",
  "companyNumber":      "12345",
  "merchantNumber":     "53400000",
  "invoiceNumber":      "CMT000000001",
  "expirationDate":     "1226",
  "languageCode":       "E",
  "operatorId":         "USER0001",
  "receiptDisp":        "APPROVED-THANK-YOU      ",
  "terminalDisp":       "APPROVED        "
}

JSON — Declined / Error

{
  "returnCode":        "05",
  "errorDescription":  "TRANSACTION DECLINED",
  "terminalDisp":      "DECLINED        ",
  "receiptDisp":       "DECLINED                ",
  "transactionNumber": "000111222445",
  "timeStamp":         "20240515-14350200"
}

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 commit or cancel was applied successfully. The card balance reflects the outcome of the action taken.	Display the `balanceAmount` on the receipt. Print the `ctm` message if present.
05	Transaction declined	The commit or cancel was declined by the DataCandy platform or the issuer.	Retry the operation. If the problem persists, contact PayFacto customer service.
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.
9013 / 9014 / 9015	Null / invalid / rejected: amount	`Amount` is null, does not match the required 11-digit length, or does not follow the specification.	Confirm the amount is left (0) padded to 11 digits and matches the amount of the original DataCandy transaction. If the problem persists, contact PayFacto customer service.
9016 / 9017 / 9018	Null / invalid / rejected: invoice number	`InvoiceNumber` is null, exceeds 12 characters, or does not follow the specification.	Check your application. The field must correspond to the specification in the documentation.
9019 / 9020 / 9021	Null / invalid / rejected: input type	`InputType` is null, not a single character, not in the list of accepted values (`N`, `I`, `M`, `U`), or not associated with the merchant.	Check your application. The field must correspond to the specification in the documentation.
9022 / 9023 / 9024	Null / invalid / rejected: card type	`CardType` is null, not a single character, or not in the list of accepted values.	Check your application. For terminal transactions send a blank space; for E-Commerce use one of the accepted card type codes.
9025 / 9026 / 9027	Null / invalid / rejected: card number	`CardNumber` is null, exceeds 40 characters, or does not follow the specification.	For terminal transactions send 40 space characters. For E-Commerce, send the card number left-justified and space-padded to 40 characters.
9028 / 9029 / 9030	Null / invalid / rejected: expiration date	`ExpirationDate` is null, not 4 characters, or does not follow the specification.	For terminal transactions send 4 space characters. For E-Commerce, send in `MMYY` format.
9031	"Null" value: POS terminal number	`MerchantTerminalNumber` is null or blank when a terminal transaction is being attempted.	Check your application. For terminal transactions provide a valid terminal number; for E-Commerce send 5 blank spaces.
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.
9034 / 9035 / 9036	Null / invalid / rejected: language code	`LanguageCode` is null, not a single character, or not one of the accepted values (`F`, `E`).	Check your application. The field must correspond to the specification in the documentation.
9037 / 9038 / 9039	Null / invalid / rejected: currency	`CurrencyCode` is null, not 3 characters, or not one of the accepted values (`CAD`, `USD`).	Check your application. The field must correspond to the specification in the documentation.
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.
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	Transaction 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 operation.	Retry the operation. If the problem persists, contact PayFacto customer service.