PayFacto API - v1.0 - POST /v1/recur/nack
POST /v1/recur/nack
Recurring — 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.
Version: v1.0
| Last updated: 2026-05-15 | Author: Annick Lachapelle
ℹ️
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.
🔑
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.
📄
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}.
⚠️
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 |
⚠️
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"
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. |
JSON — 200 Nack Accepted
{
"returnCode": "00"
}JSON — Nack Failed
{
"returnCode": "9121"
}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. |
Related Articles
PayFacto API - v1.0 - POST /v1/recur/ModInvoice
POST /v1/recur/ModInvoice Recurring — Modify Invoice Updates the status of a recurring invoice. Use this endpoint to activate, suspend, or otherwise change the processing state of a specific invoice within a subscription. Version: v1.0 | Last ...
PayFacto API - v1.0 - POST /v1/recur/InfoUser
POST /v1/recur/InfoUser Recurring — Info User Retrieves all available information on an existing Token stored in the PayFacto Token Vault. Use this endpoint to look up a subscriber's card details, subscription state, and billing history before ...
PayFacto API - v1.0 - POST /v1/recur/DelSubscription
POST /v1/recur/DelSubscription Recurring — Delete Subscription Permanently deletes an active subscription from the PayFacto recurring billing module. Once deleted, all associated invoices will cease to be processed and the subscription cannot be ...
PayFacto API - v1.0 - POST /v1/recur/ModUser
POST /v1/recur/ModUser Recurring — Modify User Updates the information linked to a Token in the PayFacto recurring billing module. Supports full card replacement or expiry-date-only updates without changing the stored card number. Version: v1.0 | ...
PayFacto API - v1.0 - POST /v1/standaloneCompletion
POST /v1/standaloneCompletion Standalone Completion Sends a Pre-Authorization Completion to any properly configured Semi-Integrated terminal. The target terminal can be the one where the original Pre-Authorization was performed, or any other terminal ...