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

Creates a hosted session for secure card registration. Returns a sessionUrl that the merchant redirects the cardholder to. Card 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 a token appended to the ReturnUrl.

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 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, terminal numbers, or transaction amounts.

🛡️

Hosted Card Entry — 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. This approach is an alternative to direct card entry via /v1/recur/AddUser.

🔄

Hosted Form Flow

After calling this endpoint, redirect the cardholder to the returned sessionUrl. When they complete the form, PayFacto redirects them to your ReturnUrl with a token query parameter appended. If they cancel, they are redirected to your CancelUrl. Store the token from the redirect for future recurring or token-based billing operations.

Request

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

ℹ️

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, terminal numbers, or transaction amounts.

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`
LanguageCode	Alphanumeric(1)	Language for the hosted card entry form and PayFacto responses. `F` = French, `E` = English.
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 successful card registration. A `token` query parameter is appended by PayFacto to this URL on success. Must be a fully-qualified HTTPS URL. Example: `https://yoursite.com/card-registered`
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/card-cancelled`

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 returned in the response.

cURL

# Create Session -- POST /v1/recur/CreateSession
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&LanguageCode=E&OperatorID=USER0001&ReturnUrl=https://yoursite.com/card-registered&CancelUrl=https://yoursite.com/card-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/recur/CreateSession" \
  -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 to access the PayFacto-hosted card entry 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.

ℹ️

Token delivery via redirect. The token for the registered cardholder is not returned in this API response. It is appended by PayFacto as a query parameter to your ReturnUrl after the cardholder completes the hosted form — for example: https://yoursite.com/card-registered?token=4111110000001111000000000000000001. Read and store this token from the incoming redirect request on your server.

Response — Code Example

JSON — 200 Success

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

JSON — Error

{
  "returnCode":       "9006",
  "errorDescription": "INVALID COMPANY NUMBER",
  "serverNumber":     "0001",
  "timeStamp":        "20240601-09000200"
}

Incoming redirect to ReturnUrl (cardholder browser)

# After the cardholder completes the hosted form, PayFacto redirects their
# browser to your ReturnUrl with the token appended as a query parameter:
GET https://yoursite.com/card-registered?token=4111110000001111000000000000000001

Error / Return Codes

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

Return Code	Meaning	When it occurs	Recommended Action
00	Session created	A hosted card entry session was created successfully.	Redirect the cardholder to the `sessionUrl` immediately. The URL is single-use and time-limited. Read the `token` query parameter from the incoming redirect to your `ReturnUrl` and store it.
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.
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.