Processing the Payment Response

After you initiate the payment, the Facilero API immediately returns a response confirming that the transaction was created. This response includes a transactionId, the current transactionStatus, and, when applicable, additional data required to continue the payment flow.

For most APM transactions, the initial transactionStatus will be CUSTOMER_VERIFICATION. This means the payment has been successfully initiated but requires additional customer interaction before it can be finalized. The response includes an apmResponseData object, which defines the next required step.

The required flow is determined by the apmResponseData.actionType field. Your integration must always evaluate actionType first and handle the payment accordingly.

When `actionType = REDIRECTION`

The customer must continue the payment on a provider-hosted interface.

Depending on the APM provider’s capabilities, one of the following fields will be returned:

redirectUrl – a full-page redirect URL
iframeUrl – a URL that can be embedded in an iframe

Both represent a redirection-based flow. The actual field provided depends on whether the provider supports embedded checkout.

Your integration should:

If redirectUrl is provided, perform a full browser redirect to that URL so the customer can complete the payment.
If iframeUrl is provided, load that URL inside an iframe within your checkout page to allow the customer to complete the payment inline.

In some cases, both redirectUrl and iframeUrl may be returned. When both are present, they represent two supported integration options for the same provider flow. You may choose the implementation that best fits your checkout experience (full redirect or embedded iframe).

If only one field is present, that is the only supported option for that transaction.

When `actionType = QR`

The customer must complete the payment using a QR-based flow.

The response may include:

qrData – a Base64-encoded QR image
qrDeepLink – a mobile deep link

Your integration should render the QR image and/or trigger the deep link so the customer can proceed in the relevant payment application.

When `actionType = NONE`

No additional customer interaction is required.

In such cases, the payment may already be in a final state (for example, SUCCEED or FAILED) or will be finalized asynchronously. Your system should rely on the payment callback to receive the final status, or poll the transaction status endpoint if needed.

Response Fields

The JSON response to the payment request will contain the following fields:

Field	Type	Description
`requestId`	String	The `requestId` sent in your original request (echoed back for reference).
`transactionId`	String	The unique identifier for the created transaction (assigned by Facilero).
`transactionStatus`	Enum (TxStatus)	Current status of the transaction. Common values include `CUSTOMER_VERIFICATION` (transaction initiated and awaiting completion), `SUCCEED` (payment succeeded), `FAILED` (payment was failed), etc.
`declineCode`	Integer	A numeric code representing the reason if the transaction was declined (if applicable).
`declineSubReason`	String	A more detailed message or sub-reason for a decline, if available.
`apmResponseData`	Object (ApmResponseData)	Additional data specific to the APM and payment flow (see ApmResponseData below). This often contains the information needed to redirect or present an iframe to the user.
`createdTime`	String	Timestamp indicating when the transaction record was created (e.g., `"2025-07-29T12:00:00Z"`).

ApmResponseData Object

The apmResponseData object provides details required to continue or finalize the payment, particularly for redirect or iframe flows:

Field	Type	Description
`paymentMethod`	Enum (PaymentMethod)	The payment method used for this transaction (e.g., `PAYPAL`, `IDEAL`, `GOOGLE_PAY`, `APPLE_PAY`, `ExPay`, etc.).
`paymentType`	Enum (PaymentType)	The category/type of payment flow (e.g., `BANK_TRANSFER`, `CARD_PAYMENT`, `E_WALLET`, etc.). This helps identify how the payment will be processed.
`actionType`	Enum (PaymentActionType)	The type of action required for the payment (`REDIRECTION` when redirect is required, `QR` - when QR code is to be shown to customer, `NONE` - when payment is in final status)
`redirectUrl`	String (nullable)	URL to which the customer should be redirected to complete the payment (present only for redirect-based flows).
`iframeUrl`	String (nullable)	URL that can be embedded in an iframe to complete the payment (present for iframe-based flows).
`qrData`	String (nullable)	Base64-encoded QR image used to redirect the customer to the selected APM app
`qrDeepLink`	String (nullable)	QR deep link that redirects the customer to the selected APM app on mobile
`providerTransactionId`	String (nullable)	An identifier for this transaction in the APM provider’s system (if provided). This might be useful for tracking the payment on the provider side.
`extra`	Map<String, String> (nullable)	Additional key-value metadata for custom use.

Note: Depending on the APM, additional fields could appear in apmResponseData. Always handle this object flexibly. For example, some payment methods might include QR code data or a payment expiration time.

Example Response

Below is an example of a response for the payment request shown earlier. In this example, the transaction is created and is in a CUSTOMER_VERIFICATION state, indicating the customer still needs to complete the payment (by being redirected to ExPay):

{
  "requestId": "req-123456789",
  "transactionId": "tx-987654321",
  "transactionStatus": "CUSTOMER_VERIFICATION",
  "apmResponseData": {
    "paymentMethod": "ExPay",
    //All the payment methods are defined in the section below
    "paymentType": "E_WALLET",
    //All the payment types are defined in the section below
    extra: null,
    qrData: null,
    iframeUrl: null,
    actionType: "REDIRECTION",
    qrDeepLink: null,
    "redirectUrl": "https://pay.expay.example.com/checkout/tx-987654321",
    "providerTransactionId": "ExPay-tx-12345"
  },
  "createdTime": "2023-01-01T12:00:00Z"
}

Note: The paymentMethod and paymentType in apmResponseData specify the APM (ExPay e-wallet in this case).

In this response, note that redirectUrl is provided. The merchant site should redirect the user’s browser to that URL (which is presumably a secure ExPay checkout page) so the user can log in or authorize the payment. Once the user completes the process at that URL, the final status will be communicated via the callback.

When actionType = REDIRECTION

When actionType = QR

When actionType = NONE