PayFacto API - v1.0 - Solution : DataCandy

Enable gift and loyalty program support via DataCandy alongside credit and debit in semi-integrated setups — how to activate a gift card account, the full set of DataCandy transaction endpoints, and the complete acquirer return code list.

Contents

🔒Account Activation Linked to the Gift Card ➕DataCandy Increment 💳DataCandy Purchase (Redemption)💰DataCandy Balance ⏳DataCandy Partial Cancel ❌DataCandy Complete Cancel 📋DataCandy Return Codes

🔒

Account Activation Linked to the Gift Card

ℹ️

Make sure your payment terminal is properly configured before processing DataCandy gift card transactions.

DataCandy provides the terminal configuration information directly to the merchant. This information includes:

🔑

DataCandy Merchant Number

Identifies the merchant within the DataCandy platform.

🔑

DataCandy Access Key

Used to authenticate API requests to DataCandy.

🔑

DataCandy Merchant Password

Required for merchant-level authentication.

ℹ️

For complete application information, refer to the DataCandy User Guide.

To activate an account linked to a gift card, you must complete the Activation transaction using the payment terminal. To activate an account, the merchant must call the Payment API using the following function:

DataCandy - Activate

The amount sent in the Activation call is automatically credited on the DataCandy gift card account. Using this endpoint, the account status of the card in the DataCandy dashboard is updated from Activable to Active.

API	Endpoint
DataCandy - Activate	https://developer.payfacto.com/docs/datacandy-activate

❗

Activation Makes All Other Transactions Possible

This step is required before performing other types of DataCandy transactions: Increment, Purchase (Redemption), Balance, Partial Cancel, and Complete Cancel.

➕

DataCandy Increment

This transaction is used to increment (add funds to) a DataCandy gift card. The initial amount is credited to the gift card during the Activation transaction.

To process an Increment transaction, the merchant must call the Payment API using the following function:

DataCandy - Increment

Adds funds to an already-activated DataCandy gift card.

API	Endpoint
DataCandy - Increment	https://test.api.payfacto.cloud/v1/datacandy/increment

💳

DataCandy Purchase (Redemption)

This transaction is used to redeem a DataCandy gift card.

To process a Purchase transaction, the merchant must call the Payment API using the following function:

DataCandy - Purchase

Redeems balance from a DataCandy gift card.

API	Endpoint
DataCandy - Purchase	https://test.api.payfacto.cloud/v1/datacandy/redemption

💰

DataCandy Balance

This transaction is used to get the balance remaining on a DataCandy gift card.

To process a Balance transaction, the merchant must call the Payment API using the following function:

DataCandy - Balance

Retrieves the current balance on a DataCandy gift card.

API	Endpoint
DataCandy - Balance	https://test.api.payfacto.cloud/v1/datacandy/balance

⏳

DataCandy Partial Cancel

This transaction is used to perform a partial cancel of a previous DataCandy transaction.

To process a partial cancel, the merchant must call the Payment API using the following function:

DataCandy - Partial Cancel

Reverses part of the amount of a previous DataCandy transaction.

API	Endpoint
DataCandy - Partial Cancel	https://test.api.payfacto.cloud/v1/datacandy/partialCancel

❌

DataCandy Complete Cancel

This transaction is used to fully cancel a previous DataCandy transaction.

To process a complete cancel transaction, the merchant must call the Payment API using the following function:

DataCandy - Complete Cancel

Fully reverses a previous DataCandy transaction.

API	Endpoint
DataCandy - Complete Cancel	https://test.api.payfacto.cloud/v1/datacandy/completeCancel

📋

DataCandy Return Codes

The following table lists the acquirer return codes returned by DataCandy.

Code	Description
1	Transaction is valid and was accepted.
101	The card specified by the CID parameter is invalid or does not exist.
102	The amount specified by the AMT parameter is invalid or not properly formatted.
103	The card you are trying to activate is already active.
104	The card specified by the CID parameter is expired and no longer active.
105	The account's balance is insufficient.
106	A value used for authentication could not be validated, such as MID or MPW.
107	The transaction specified by the TCR parameter could not be found.
108	The transaction is invalid.
109	The transaction could not be processed because the actual date/time is outside the allowed transaction processing window.
111	The transaction specified by the TCR parameter is not a lock transaction or is the wrong lock transaction.
140	The program specified by the PRG parameter is invalid.
141	The API version specified by the VER parameter isn't supported.
142	Your request did not include the mandatory VER parameter.
143	The API version specified by the VER parameter is in an invalid format. It should be in the YYYY-MM-DD form. For example: 2010-01-06.
144	The language specified by the LNG parameter isn't supported.
146	The language you specified in the LNG parameter is in an invalid format.
216	The invoice number specified in the INV parameter has already been used for this merchant in the current year. This error is only triggered when the client requires this configuration.
222	The invoice number specified in the INV parameter is invalid.
223	Card locked due to repeated failed PIN attempts.
225	Invalid action/transaction type.
228	Invalid workstation number.
229	Invalid waiter/employee number.
233	Invalid PIN number. The PIN number was sent but does not match.
234	Empty PIN. A PIN number was required but none was sent.
235	Invalid DB PIN value. The server-side PIN value is invalid (e.g. non-numerical PIN).
260	Sample error message: card is valid from 2016-06-01 to 2016-12-31. This error is triggered when the start date of the card is in the future.
262	Too many attached accounts found. Unable to determine which one to use.
264	The account is inactive.
265	The account is expired.
268	The target account's balance exceeds the maximum possible balance.
270	The card can't be activated due to invalid expiry setting.
277	The source account does not support balance transfers.
279	The amount specified in the AMT parameter is lower than the minimum increment amount.
280	The amount specified in the AMT parameter is lower than the minimum activation amount.
281	Emptying cards is not supported at the specified location.
282	The source account's balance exceeds the maximum amount supported at the specified location.
283	The account does not support locking.
284	The account is currently locked.
285	The account is not currently locked.
286	The amount specified in the AMT parameter is higher than the maximum increment amount.
287	The amount specified in the AMT parameter is higher than the maximum activation amount.
288	Emptying cards is not supported for the account type of the given card.
322	The maximum number of redemptions allowed at this merchant has been met.
500	There is an internal problem with the DataCandy API, which you cannot resolve. Retry the request. If the problem persists, contact us.