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

Request Body

BillingDetails Object

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

Device Object

Response Body

Example Response

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

Redirect Flow

1. After receiving the redirectUrl, redirect the customer to the Facilero Hosted Payment Page (HPP).
2. The HPP will display payment options based on the user’s region, preferences, and available methods.
3. If required billing fields were not included in the original request, the user will be prompted to complete them on the HPP.
4. 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.

Below is a single, consolidated section that merges the old and new content, removes duplication, and cleanly explains callback parsing behavior for S2S, HPP, Card, and APM flows.

You can replace the existing callback section with this as-is.

Webhook Callback Behavior (S2S, HPP, Cards, and APMs)

Upon transaction completion, Facilero sends a server-to-server (S2S) webhook callback to the callbackUrl provided during transaction creation.

This applies to:

• Direct S2S integrations
• Hosted Payment Page (HPP) flows
• Card payments
• Alternative Payment Methods (APMs)

All callbacks are delivered as HTTP POST requests with a JSON payload and identifying query parameters.

Why Callback Identification Is Required

In HPP flows, the final payment method is not known at transaction creation time.
The end user selects the payment option later in the checkout flow (Card or a specific APM).

As a result:

• The transaction lifecycle may resolve to different DTOs
• The callback payload structure depends on the payment method actually used

To guarantee deterministic webhook handling, Facilero explicitly identifies the resolved payment method in every callback.

Callback Identification Fields

Facilero provides identifiers that allow merchants to determine the expected payload structure before parsing the request body.

1) paymentMethod (Query Parameter)

All webhook callbacks include the paymentMethod query parameter appended to the callback URL.

This parameter is always present.

2) apmType (Query Parameter and Payload Field)

When paymentMethod=apm, Facilero also provides apmType.

Characteristics:

• Present only when paymentMethod=apm

• Value comes from the Supported Payment Methods (PaymentMethod) enum

• Included both:

  • as a query parameter
  • inside the callback payload

• Enables routing and parsing decisions without inspecting the payload structure

Callback URL Examples

If the original callback URL is:

https://merchant.com/payment-status

Card Payment

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

Payload format:

• Merchant Callback DTO (Card)

APM Payment

POST https://merchant.com/payment-status?paymentMethod=apm&apmType={APM_METHOD}

Example:

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

Payload format:

• ApmPaymentTxInfoDto
• Includes apmResponseData

Expected Callback Payloads

Card Payments

If paymentMethod=card:

• The JSON body conforms to Merchant Callback DTO
• Used for all card-based flows (including HPP)

📘 Reference:
Merchant Callback DTO
https://api.facilero.com/reference/payments#/example-response-body

APM Payments

If paymentMethod=apm:

• The JSON body conforms to ApmPaymentTxInfoDto
• Includes APM-specific response data

The structure of apmResponseData depends on apmType.

📘 Reference:
ApmPaymentTxInfoDto
https://api.facilero.com/reference/payment#/callback-data-object-apmpaymenttxinfodto

Parsing APM Callbacks (apmResponseData)

apmResponseData varies by APM provider and flow type.

Guidelines:

• Use apmType to select the correct parser
• Expect different fields per APM
• Follow the APM-specific UX instructions (redirect, iframe rendering, polling, confirmations)

⚠️ Important
Do not assume a common structure across all APMs.
Parsing and user flow handling must be driven by apmType.

APM-Specific Documentation

Each supported apmType has dedicated documentation describing:

• apmResponseData schema
• Redirect vs iframe behavior
• Required follow-up actions
• Provider-specific notes and edge cases

Use the apmType value from the callback to navigate to the relevant APM documentation page.

Processing Guidance

• Read paymentMethod from the callback URL to determine Card vs APM
• When paymentMethod=apm, read apmType to select the correct APM schema
• Parse the payload using the matching DTO
• For HPP flows, rely on callback identifiers rather than the original request intent

✅ Result
A single webhook endpoint can reliably handle Card and all APM callbacks with predictable parsing and flow control.