Payment Intent API Documentation

This document outlines how to initiate a transaction using the Facilero Hosted Payment Page (HPP) via the Payment Intent API. After creating the intent, you will receive a redirectUrl to send the user to a secure Facilero-hosted checkout page. Upon completion, a server-to-server callback will notify your system of the transaction result.

API Endpoint

Live

POST https://live.facilero.com/api/v1/payments/intent

Sandbox

POST https://sandbox.facilero.com/api/v1/payments/intent

Request Headers

Header	Type	Required	Description
`Content-Type`	string	Yes	Must be `application/json`.
`Referer`	string	No	Optional HTTP referrer for context.

Request Body

Field	Type	Required	Description
`requestId`	String	Yes	Unique identifier for this request.
`mid`	String	Yes	Merchant Account ID assigned by Facilero.
`amount`	String	Yes	Payment amount (e.g. `"100.00"`).
`currency`	String	Yes	ISO 4217 currency code (e.g. `"USD"`, `"EUR"`).
`lang`	String	Yes	Language code for displaying the payment page.
`billingDetails`	Object (BillingDetails)	Yes	Customer billing information. See below.
`callbackUrl`	String	Yes	Webhook URL to receive transaction status updates.
`successRedirectUrl`	String	Yes	URL to redirect the user after successful payment.
`failureRedirectUrl`	String	Yes	URL to redirect the user after failed or cancelled payment.
`order`	Object (Order)	Yes	Order-specific information.
`device`	Object (Device)	Yes	Device metadata for risk analysis.
`kycVerified`	Boolean	No	Whether the user is KYC verified.
`previousPaymentCount`	Long	No	Number of previous payments by the user.

BillingDetails Object

Field	Type	Required	Description
`externalUserId`	String	No	External user ID in your system.
`firstName`	String	No	Customer’s first name.
`lastName`	String	No	Customer’s last name.
`address1`	String	No	Billing address line 1.
`city`	String	No	City.
`state`	String	No	State or province.
`country`	String	No	ISO Alpha-2 country code (e.g., `"US"`).
`postalCode`	String	No	Postal/ZIP code.
`phone`	String	No	Phone number.
`email`	String	Yes	Email address.
`dateOfBirth`	String	No	Format: `YYYY-MM-DD`.

Note:
For certain payment methods (such as e-wallets, vouchers, or localized APMs), full billing details may be required to complete the transaction. If any of the required fields are not provided during the API request, the user will be prompted to enter the missing information directly on the Facilero Hosted Payment Page (HPP) before continuing with the payment.

Order Object

Field	Type	Required	Description
`date`	String	No	Date of the order.
`orderId`	String	No	Unique identifier for the order.
`title`	String	No	Title or name of the order.
`siteId`	String	No	Site identifier where the order was placed.
`name`	String	No	Customer's name for the order.
`domainName`	String	No	Domain name where the order was placed.

Device Object

Field	Type	Required	Description
`deviceId`	String	No	Unique identifier for the device.
`fingerprintData`	String	No	Device fingerprint data for risk assessment.
`ip`	String	Yes	Customer's IP address.
`accept`	String	No	Browser's accept header. Required for 3D Secure transactions
`acceptLanguage`	String	No	Language accepted by the browser. Required for 3D Secure transactions
`userAgent`	String	Yes	User-Agent header for identifying the browser.
`javaEnabled`	Boolean	No	Flag indicating whether Java is enabled. Required for 3D Secure transactions
`javaScriptEnabled`	Boolean	No	Flag indicating whether JavaScript is enabled. Required for 3D Secure transactions
`deviceLanguage`	String	No	Language set on the device. Required for 3D Secure transactions
`colorDepth`	String	No	Screen color depth in bits. Required for 3D Secure transactions
`screenHeight`	String	No	Screen height in pixels. Required for 3D Secure transactions
`screenWidth`	String	No	Screen width in pixels. Required for 3D Secure transactions
`deviceTimezone`	String	No	Timezone of the device. Required for 3D Secure transactions

Response Body

Field	Type	Description
`redirectUrl`	String	URL to redirect the user to the Facilero Hosted Payment Page.
`iframeUrl`	String	Reserved for iframe integrations (currently `null`).
`errorCode`	String	Returned if there was an error creating the payment intent.

Example Response

{
  "redirectUrl": "https://checkout.facilero.com/pay/abcde12345",
  "iframeUrl": null,
  "errorCode": null
}

Redirect Flow

After receiving the redirectUrl, redirect the customer to the Facilero Hosted Payment Page (HPP).
The HPP will display payment options based on the user’s region, preferences, and available methods.
If required billing fields were not included in the original request, the user will be prompted to complete them on the HPP.
After the transaction is completed or cancelled:

The customer is redirected to successRedirectUrl or failureRedirectUrl.
A server-to-server callback is sent to your callbackUrl.

Callback Behavior

Upon transaction completion, Facilero will send a server-to-server callback to the callbackUrl you provided in the request.

Callback Structure

The callback will be a POST request with:

A JSON body containing the transaction result (either card or APM format).
An additional query parameter appended to the callback URL:

Query Parameter	Type	Description
`paymentMethod`	String	Indicates the payment method used. One of: `"card"` or `"apm"`

This allows you to determine the structure of the JSON body before deserializing it.

Example

If your original callbackUrl was:

https://merchant.com/payment-status

Facilero will call:

POST https://merchant.com/payment-status?paymentMethod=apm

or:

POST https://merchant.com/payment-status?paymentMethod=card

with the corresponding JSON body in the request payload.

Expected Behavior

If paymentMethod = card → the body will conform to Merchant Callback DTO (used for card payments).
If paymentMethod = apm → the body will conform to ApmPaymentTxInfoDto (used for alternative payment methods).

✅
See also:
Merchant Callback DTO – for card payments ApmPaymentTxInfoDto – for APM payments