PayFacto API - v1.0 - POST /v1/redirect/CreatePurchaseSession

Creates a hosted session for a credit card purchase. Returns a sessionUrl that the merchant redirects the cardholder to. Payment details are entered on a PayFacto-hosted form — the merchant system never handles raw card data. On completion, PayFacto redirects the cardholder back to the merchant with the transaction result appended to the ReturnUrl as query parameters.

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 Create Purchase Session 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}. This endpoint does not require card data or terminal numbers.

🛡️

Hosted Payment Form — PCI Scope Reduction

Card details are entered by the cardholder on a PayFacto-hosted secure form. The merchant system never handles raw card data (PAN, expiry, or CVV), significantly reducing PCI DSS scope. To create a hosted session for card registration only (no immediate charge), use /v1/recur/CreateSession instead.

🔄

Hosted Payment Flow

After calling this endpoint, redirect the cardholder to the returned sessionUrl. When payment is completed, PayFacto redirects to your ReturnUrl with the transaction result appended as query parameters. If the cardholder cancels, they are redirected to your CancelUrl. The sessionUrl is single-use and time-limited.

Request

POST https://test.api.payfacto.cloud/v1/redirect/CreatePurchaseSession

ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. This endpoint does not require card data or terminal numbers.

Required fields

Field	Type	Description
CompanyNumber	Numeric(5)	Identifies the merchant on PayFacto's network. Provided by PayFacto during onboarding. 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 the session with a client record. Example: `CLIENT12`
Amount	Numeric(11)	Amount to charge the cardholder, including the decimal portion, left (0) padded. Displayed on the hosted payment form and charged on approval. Example: `00000010000` = $100.00
InvoiceNumber	Alphanumeric(12)	Merchant-generated invoice number for this purchase. Returned as a query parameter on the redirect to `ReturnUrl`. Example: `PUR000000001`
LanguageCode	Alphanumeric(1)	Language for the hosted payment form and PayFacto responses. `F` = French, `E` = English.
CurrencyCode	Alphanumeric(3)	Currency of the transaction. `CAD` = Canadian dollars, `USD` = US dollars (requires a US merchant number).
OperatorID	Alphanumeric(8)	Identifies the cashier, agent, or system that initiated the request. Example: `USER0001`
ReturnUrl	Alphanumeric	The URL PayFacto redirects the cardholder to after the payment form is completed. Transaction result parameters are appended by PayFacto as query parameters. Must be a fully-qualified HTTPS URL. Example: `https://yoursite.com/payment-complete`
CancelUrl	Alphanumeric	The URL PayFacto redirects the cardholder to if they cancel on the hosted form. Must be a fully-qualified HTTPS URL. Example: `https://yoursite.com/payment-cancelled`

Optional fields

Field	Type	Description
taxAmount	Numeric(11)	Total tax amount included in `Amount`, left (0) padded. Example: `00000001300` = $13.00
TrxOption	Alpha(50)	Adds transaction-level options. For Credential-on-File initial transactions, pass twice: `TrxOption=isCredentialOnFile&TrxOption=isFirst`. Accepted values: `isCredentialOnFile`, `isRecurring`, `isInstallment` (mutually exclusive).

Request — Code Example

⚠️

The example below uses the test endpoint and a sandbox API key. Replace credentials and base URL before going live. After a successful response, redirect the cardholder to the sessionUrl to complete payment.

cURL

# Create Purchase Session -- POST /v1/redirect/CreatePurchaseSession
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&Amount=00000010000&InvoiceNumber=PUR000000001&LanguageCode=E&CurrencyCode=CAD&OperatorID=USER0001&ReturnUrl=https://yoursite.com/payment-complete&CancelUrl=https://yoursite.com/payment-cancelled"

# 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/redirect/CreatePurchaseSession" \
  -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)	Identifies the result of the session creation. `00` = session created successfully. All other values indicate a failure. Refer to Section 6 for endpoint-specific codes.
serverNumber	Alphanumeric(4)	Identifies the PayFacto Network server that processed the request.
timeStamp	Alphanumeric(17)	Date and time the request was processed. Format: `YYYYMMDD-HHMMSSCC`. Example: `20240601-09000100`

Conditionally returned

Field	Type	Description
sessionUrl	Alphanumeric	★ Redirect the cardholder to this URL. Returned on successful session creation. The cardholder must be redirected to this URL immediately to complete payment on the PayFacto-hosted form. The URL is single-use and time-limited.
errorDescription	Alphanumeric(50)	Only returned when the session creation fails. Human-readable description of the failure reason.

ℹ️

Transaction result delivery via redirect. The payment outcome is not returned in this API response. After the cardholder completes the hosted form, PayFacto redirects their browser to your ReturnUrl with the following query parameters appended:

Parameter	Description
returnCode	`00` = approved. All other values indicate the payment was not completed.
authorizationNumber	Authorization code from the issuing bank. Present when approved. Must be displayed on the customer receipt.
transactionNumber	Unique PayFacto gateway transaction identifier. Present when approved.
amount	Echo of the charged amount, left (0) padded.
invoiceNumber	Echo of the request InvoiceNumber.
cardNumber	Masked card number used for the payment.
cardType	Card brand. `A` = Amex, `M` = Mastercard, `V` = Visa, `I` = Diners, `O` = Discover.

Response — Code Example

JSON — 200 Success

{
  "returnCode":  "00",
  "serverNumber": "0001",
  "timeStamp":   "20240601-09000100",
  "sessionUrl":  "https://hosted.payfacto.cloud/session/a1b2c3d4e5f6..."
}

JSON — Error

{
  "returnCode":       "9015",
  "errorDescription": "INVALID AMOUNT",
  "serverNumber":     "0001",
  "timeStamp":        "20240601-09000200"
}

Incoming redirect to ReturnUrl (cardholder browser) — Approved

# After the cardholder completes the hosted payment form and payment is approved,
# PayFacto redirects their browser to your ReturnUrl with result parameters:
GET https://yoursite.com/payment-complete?returnCode=00&authorizationNumber=APPROV01&transactionNumber=000111222333&amount=00000010000&invoiceNumber=PUR000000001&cardNumber=411111XXXXXX1111&cardType=V

Error / Return Codes

The following codes apply to the session creation result returned in the API response. The returnCode delivered via the redirect to ReturnUrl reflects the cardholder's payment outcome and follows the same standard codes (00 = approved, 05 = declined). For the complete catalogue see the Return Code Index.

Return Code	Meaning	When it occurs	Recommended Action
00	Session created	The hosted payment session was created successfully.	Redirect the cardholder to the `sessionUrl` immediately. Read the `returnCode` query parameter on the incoming redirect to your `ReturnUrl` to determine the payment outcome.
9004	"Null" value: company number	`CompanyNumber` is null or blank in the payload.	Check your application. The field must correspond to the specification in the documentation.
9005 / 9006	Invalid / rejected: company number	`CompanyNumber` does not match the required 5-digit length or is not configured in the payment solution.	Make sure the application uses the correct company number provided by PayFacto. If it does, contact PayFacto customer service.
9007	"Null" value: merchant number	`MerchantNumber` is null or blank in the payload.	Check your application. The field must correspond to the specification in the documentation.
9008 / 9009	Invalid / rejected: merchant number	`MerchantNumber` does not match the required 8-digit length or is not configured in the payment solution.	Make sure the application uses the merchant number provided by PayFacto. If it does, contact PayFacto customer service.
9013 / 9014 / 9015	Null / invalid / rejected: amount	`Amount` is null, does not match the required 11-digit length, or does not follow the specification.	Confirm the amount is left (0) padded to 11 digits and includes the decimal portion. If the problem persists, contact PayFacto customer service.
9016 / 9017 / 9018	Null / invalid / rejected: invoice number	`InvoiceNumber` is null, exceeds 12 characters, or does not follow the specification.	Check your application. The field must correspond to the specification in the documentation.
9051	Time out	Request processing timed out.	Retry the request. If the problem persists, contact PayFacto customer service.
9049 / 9050	Fatal error	A critical error occurred while processing the request.	Retry the request. If the problem persists, contact PayFacto customer service.