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

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 updated: 2026-05-15   |   Author: Annick Lachapelle  

Invoice Status Values

CodeNameDescription
01ActiveThe invoice will be processed at the next scheduled execution.
02In processA withdrawal is currently in progress.
03ProcessedThe withdrawal was processed but some finalizing operations are still pending.
04CompletedAll operations are complete. This is a terminal state.
05ErrorAn error occurred during the withdrawal.
06SuspendedThe invoice is unpaid and will not be processed at the next execution. Set to Active (01) to resume.
07ExpiredThe subscriber's card has expired. The merchant must update the card information to reactivate.
08Without cardNo card information is on file. The merchant must add a card to reactivate the invoice.
1

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

πŸ“„

Existing Invoice

The invoice identified by CustomerNumber and InvoiceNumber must already exist in the PayFacto recurring billing system. Use Recurring β€” Info Invoice to confirm the invoice exists and review its current status before modifying.

2

   Request

POST https://test.api.payfacto.cloud/v1/recur/ModInvoice
ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. Only the Status field is changed; all other invoice attributes remain unchanged.

Required fields

FieldTypeDescription
CompanyNumberNumeric(5)Identifies the merchant on PayFacto's network. Provided by PayFacto. Example: 12345
MerchantNumberNumeric(8)Identifies the merchant to PayFacto's network. Provided by the integration team. Example: 53400000
CustomerNumberAlphanumeric(8)The recurring customer identifier whose invoice is being updated. Example: CLIENT12
InvoiceNumberAlphanumeric(12)The invoice number of the recurring invoice to update. Example: INV000000060
StatusNumeric(2)The new status to apply to the invoice. Accepted values: 01=Active (invoice will be processed at the next execution), 02=In process, 03=Processed, 04=Completed (final state), 05=Error, 06=Suspended (invoice will not be processed at next execution), 07=Expired (card expired; merchant action required), 08=Without card (no card on file; merchant action required).
OperatorIDAlphanumeric(8)Identifies the operator or system performing the update. Example: USER0001
3

   Request β€” Code Example

⚠️

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

cURL β€” Suspend an invoice
# Recurring: Modify Invoice β€” POST /v1/recur/ModInvoice
# Example: suspend invoice INV000000060 for customer CLIENT12
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345\
&MerchantNumber=53400000\
&CustomerNumber=CLIENT12\
&InvoiceNumber=INV000000060\
&Status=06\
&OperatorID=USER0001"

# 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/ModInvoice" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"
4

   Response

ℹ️

The source specification does not designate any response fields as unconditionally mandatory for this endpoint. Always check recurReturnCode first. The remaining fields reflect the full state of the invoice and its associated subscription after the update.

Response fields

FieldTypeDescription
recurReturnCodeAlphanumeric(4)00=the invoice was updated successfully. Any other value indicates a failure. Check this field first before inspecting the remaining response fields.
transactionReturnCodeAlphanumeric(4)Return code of the transaction associated with the invoice update, if a payment was triggered as part of the operation.
transactionNumberNumeric(12)Unique PayFacto gateway identifier of the transaction associated with this invoice, if applicable.
idNumeric(12)Unique identifier of the invoice that was modified. Left zero-padded.
subscriptionIdNumeric(12)Identifier of the subscription to which the invoice belongs.
clientAlphanumeric(8)Subscriber (customer) number associated with the invoice.
statusNumeric(2)Current status of the invoice after the update. Reflects the value set in the request. See the Status request field for possible values and meanings.
amountNumeric(11)Invoice amount. Zero-padded left.
currencyCodeAlphanumeric(3)Currency of the invoice. CAD=Canadian dollars, USD=US dollars.
frequencyNumeric(2)Frequency code of the subscription associated with this invoice.
numberOfPaymentsNumeric(3)Number of payments remaining or scheduled for the subscription.
startDateNumeric(8)Start date of the subscription. Format: YYYYMMDD.
endDateNumeric(8)End date of the subscription, or 8 spaces if open-ended. Format: YYYYMMDD.
lastInvoiceDateNumeric(8)Date the last invoice was processed. Format: YYYYMMDD.
nextInvoiceDateNumeric(8)Date the next invoice is scheduled to be processed. Format: YYYYMMDD.
nameAlphanumeric(50)Subscriber name associated with the invoice.
accountNumberAlphanumeric(50)Merchant reference number for the subscriber account.
descriptionAlphanumeric(50)Merchant reference description for the subscription.
emailAlphanumeric(240)Email address of the subscriber, if on file.
languageCodeAlphanumeric(1)Language preference of the subscriber. F=French, E=English.
cardNumberAlphanumeric(40)Masked card number on file for the subscriber.
cardTypeAlphanumeric(1)Card brand on file. A=Amex, D=Debit, M=Mastercard, V=Visa, O=Discover, I=Diners, J=JCB, F=Datacandy.
expirationDateNumeric(4)Card expiration date on file. Format: MMYY.
avsStatusAlphanumeric(1)AVS verification status from the most recent transaction. M=Both match, N=Neither match, Z=Postal only, A=Address only, U=Unavailable.
cvv2Cvc2StatusAlphanumeric(1)CVD verification status from the most recent transaction. M=Matches, N=Does not match, blank=Unknown.
secureIDAlphanumeric(35)Secure session identifier, if a hosted session was used during the operation.
errorDescriptionAlphanumeric(50)Only returned when recurReturnCode is not 00. Human-readable description of the failure reason.
5

   Response β€” Code Example

JSON β€” 200 Invoice Updated (suspended)
{
  "recurReturnCode":       "00",
  "transactionReturnCode": "00",
  "id":                    "000000000042",
  "subscriptionId":        "000000000010",
  "client":                "CLIENT12",
  "status":                "06",
  "amount":                "00000010000",
  "currencyCode":          "CAD",
  "frequency":             "03",
  "numberOfPayments":      "012",
  "startDate":             "20240101",
  "endDate":               "20251231",
  "lastInvoiceDate":       "20240501",
  "nextInvoiceDate":       "20240601",
  "name":                  "Jane Doe",
  "accountNumber":         "ACC00012345",
  "description":           "Monthly subscription",
  "email":                 "jane.doe@example.com",
  "languageCode":          "E",
  "cardNumber":            "411111XXXXXX1111",
  "cardType":              "V",
  "expirationDate":        "1226"
}
JSON β€” Update Failed
{
  "recurReturnCode":  "9121",
  "errorDescription": "INVOICE NOT FOUND"
}
6

   Error / Return Codes

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

recurReturnCodeMeaningWhen it occursRecommended Action
00Invoice updatedThe invoice status was updated successfully.Confirm the new status in the response matches the value sent in the request. No further action required.
Non-00Update failedThe invoice could not be updated. Common causes: the invoice was not found for the given CustomerNumber and InvoiceNumber, or an invalid Status code was submitted.Check errorDescription. Use Recurring β€” Info Invoice to confirm the invoice exists and verify the correct InvoiceNumber. Refer to the Return Code Index for code-specific guidance.

    • Related Articles

    • 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/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/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 ...

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