PayFacto API - v1.0 - POST /v1/redirect/CreatePreAuthSession
POST /v1/redirect/CreatePreAuthSession
Redirect — Create Preauth Session
Creates a secure session on the PayFacto network for a hosted pre-authorization flow. Returns a secureID valid for 15 minutes that is embedded in the browser redirect URL to send the cardholder to the PayFacto hosted payment page.
Version: v1.0
| Last updated: 2026-05-15 | Author: Annick Lachapelle
ℹ️
Redirect Pre-Authorization Flow
1. Create session — Call this endpoint server-side to obtain a secureID.
2. Redirect cardholder — Send the customer's browser to the PayFacto hosted payment page using the secureID. The session expires after 15 minutes.
3. PayFacto redirects back — After the cardholder completes or abandons payment, PayFacto redirects to your successUrl or failureUrl.
4. Retrieve result — Call Redirect — Get Response with the secureID to obtain the full transaction result.
🔑
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. Never expose the API key client-side — session creation must be done server-to-server.
🏪
Company & Merchant Numbers
Your CompanyNumber (5-digit) and MerchantNumber (8-digit) are issued by PayFacto during onboarding. Both are required on every session creation request.
📦
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}.
🔗
Success & Failure URLs
Both successUrl and failureUrl must be registered and reachable HTTPS endpoints on your server. PayFacto will POST or redirect to these URLs after the cardholder interaction completes.
ℹ️
All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. Card data (CardNumber, CardType, ExpirationDate) is not sent in this request — it is collected by the PayFacto hosted payment page.
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 |
| CustomerNumber | Alphanumeric(8) | Merchant-assigned customer identifier. Associates a client record with the session. Example: CLIENT12 |
| Amount | Numeric(11) | Pre-authorization amount in the smallest currency unit, zero-padded left. Example: 00000010000 = $100.00 |
| InvoiceNumber | Alphanumeric(12) | Merchant-generated invoice number for this session. Returned in the final transaction response after the cardholder completes payment. Example: INV000000050 |
| InputType | Alphanumeric(1) | Must be I for Internet/E-Commerce redirect sessions. |
| MerchantTerminalNumber | Numeric(5) | For redirect sessions, send 5 blank spaces. |
| LanguageCode | Alphanumeric(1) | Language in which the PayFacto hosted payment page will be displayed. 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 system or agent that created the session. Example: USER0001 |
| successUrl | Alphanumeric(240) | URL to which PayFacto redirects the cardholder after a successful pre-authorization. Must be a fully qualified HTTPS address. Example: https://www.example.com/success |
| failureUrl | Alphanumeric(240) | URL to which PayFacto redirects the cardholder after a failed pre-authorization. Must be a fully qualified HTTPS address. Example: https://www.example.com/failure |
⚠️
The example below uses the test endpoint and a sandbox API key. Replace credentials and base URL before going live. This call must be made server-side — never expose the API key to the browser.
cURL
# Redirect: Create Preauth Session — POST /v1/redirect/CreatePreAuthSession
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345\
&MerchantNumber=53400000\
&CustomerNumber=CLIENT12\
&Amount=00000010000\
&InvoiceNumber=INV000000050\
&InputType=I\
&MerchantTerminalNumber= \
&LanguageCode=E\
&CurrencyCode=CAD\
&OperatorID=USER0001\
&SuccessUrl=https://www.example.com/success\
&FailureUrl=https://www.example.com/failure"
# Step 2: Base64-encode the payload
ENCODED=$(echo -n "$PAYLOAD" | base64)
# Step 3: Submit the request (server-side only)
curl -X POST "https://test.api.payfacto.cloud/v1/redirect/CreatePreAuthSession" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"
Response fields
| Field | Type | Description |
|---|
| returnCode | Alphanumeric(4) | 00=session was created successfully and the secureID is ready to use. Any other value indicates the session could not be created. |
| secureID | Alphanumeric(50) | Secure session identifier, valid for 15 minutes. Use this value to build the browser redirect URL that sends the cardholder to the PayFacto hosted payment page. Only present when returnCode is 00. |
5
Response — Code Example
JSON — 200 Session Created
{
"returnCode": "00",
"secureID": "aasdf87a9sdg69sdf8s6d0fg76s9df8g6sd9k2jh"
}JSON — Session Creation Failed
{
"returnCode": "9121"
}Browser redirect URL (after session creation)
# Redirect the cardholder's browser to the PayFacto hosted payment page:
https://<payfacto-hosted-page-url>?secureID=aasdf87a9sdg69sdf8s6d0fg76s9df8g6sd9k2jh
# After the cardholder completes or abandons payment, PayFacto redirects to:
# successUrl (on approval)
# failureUrl (on decline or abandonment)
# Then call Redirect - Get Response with the secureID to retrieve the full result.
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 | Session created | The secure session was created successfully. The secureID is valid for 15 minutes. | Immediately redirect the cardholder's browser to the PayFacto hosted payment page using the secureID. Do not delay — the session expires after 15 minutes. |
| Non-00 | Session creation failed | The session could not be created. Common causes: invalid merchant credentials, a missing required field, or an unreachable successUrl / failureUrl. | Verify all required fields are present and correctly formatted. Confirm the successUrl and failureUrl are valid HTTPS URLs. Refer to the Return Code Index for code-specific guidance. |
| Session expired | secureID no longer valid | The cardholder did not complete the payment page within 15 minutes of session creation. | Create a new session by calling this endpoint again and redirect the cardholder to the new URL. |
Related Articles
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 ...
PayFacto API - v1.0 - POST /v1/refund
POST /v1/refund Refund Returns the value of a purchase in whole or in part. A successful refund credits the cardholder's account and debits the merchant's account. Refunds are not matched to a purchase at the PayFacto host. Version: v1.0 | Last ...
PayFacto API - v1.0 - POST /v1/void
POST /v1/void Void Cancels a previously captured transaction that has not yet been included in a bank deposit. Use this endpoint to void a credit card purchase, refund, completion, or force. A successful void ensures the original transaction is never ...
PayFacto API - v1.0 - POST /v1/refundWithTuid
POST /v1/refundWithTuid Refund with TUID Performs a refund in the same way as the standard Refund endpoint, except that it identifies the original transaction using a TUID (PayFacto switch unique transaction identifier) instead of card data. Use this ...
PayFacto API - v1.0 - POST /v1/purchase
POST /v1/purchase Purchase Obtains a credit card authorization for a financial transaction. Supports E-Commerce (Internet), MOTO (Mail Order / Telephone Order), and Semi-Integrated terminal input types. Version: v1.0 | Last updated: 2026-05-14 | ...