PayFacto API - v1.0 - POST /v1/recur/nack

Declines a CVV or AVS verification result from a recurring session and triggers deletion of the associated token. Use this endpoint when your application determines that the CVV or AVS result from a prior recurring session is unacceptable and the stored card token should be removed.

ℹ️

Ack / Nack pattern for recurring sessions

After a recurring session completes, your application evaluates the CVV (cvv2Cvc2Status) and AVS (avsStatus) results returned by the gateway.

Acceptable result — Call Recurring — Ack to confirm the session. The token is retained for future recurring charges.

Unacceptable result — Call this endpoint (Nack) to decline the session. The token is permanently deleted and cannot be used for future charges.

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 Nack request.

🌐

Environment Base URL

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

📄

Session ID

You must have stored the ID returned by the recurring session creation response. This is the identifier passed to this endpoint to target the correct session and token for deletion.

📦

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}.

Request

POST https://test.api.payfacto.cloud/v1/recur/nack

⚠️

Sending a Nack is irreversible. Once processed, the token associated with the session ID is permanently deleted and cannot be recovered. Ensure the CVV/AVS result genuinely warrants rejection before calling this endpoint.

ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>.

Required fields

Field	Type	Description
CompanyNumber	Numeric(5)	Identifies the merchant on PayFacto's network. Provided by PayFacto. Example: `12345`
MerchantNumber	Numeric(8)	Identifies the merchant to PayFacto's network. Provided by the integration team. Example: `53400000`
ID	Numeric(12)	The unique identifier of the recurring session whose CVV or AVS result is being declined. Obtained from the session creation response. Left zero-padded. Example: `000000000001`

Request — Code Example

⚠️

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

cURL

# Recurring: Nack — POST /v1/recur/nack
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345\
&MerchantNumber=53400000\
&ID=000000000001"

# 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/recur/nack" \
  -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)	`00`=the nack was processed successfully and the associated token has been deleted. Any other value indicates a failure.

Response — Code Example

JSON — 200 Nack Accepted

{
  "returnCode": "00"
}

JSON — Nack Failed

{
  "returnCode": "9121"
}

Error / Return Codes

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

Return Code	Meaning	When it occurs	Recommended Action
00	Nack accepted	The CVV/AVS decline was recorded and the associated token has been permanently deleted.	No further action required. The token can no longer be used. If the customer should continue with recurring billing, a new session and token must be created.
Non-00	Nack failed	The nack could not be processed. Common causes: the `ID` was not found, the session has already been acknowledged or nacked, or the merchant credentials did not match the session.	Verify that the `ID` is correct and that the session has not already been finalized. Refer to the Return Code Index for code-specific guidance.