APM Data Collection

Some Alternative Payment Method (APM) providers require customer or recipient information that may not be available when a transaction is initially created. For supported routes, you can submit an APM payment or payout request with only the method identifiers in apmPayload.

If the selected underlying provider requires additional information, Facilero returns a redirect to the Hosted Payment Page (HPP), where the customer or recipient can provide the missing fields.

This approach allows a single APM integration to work across multiple providers with different data requirements. Your server creates the payment or payout, redirects the customer or recipient when necessary, and receives the final transaction outcome through the standard webhook and status-check flow.

Overview

APM data collection can apply to both payment and payout transactions.

Whether data collection is required depends on:

• Your merchant routing configuration
• The selected APM method
• Country and currency
• The underlying provider route selected by Facilero

If the selected route does not require additional information, Facilero processes the request normally without any customer interaction.

How It Works

When Facilero receives an APM payment or payout request, it evaluates the selected route and determines whether all required provider-specific fields are already present.

If all required fields are available

Facilero forwards the payload directly to the underlying provider and continues processing the transaction.

Result: No redirect is required.

If required fields are missing

Facilero returns a redirect URL that points to the Hosted Payment Page (HPP).

Result: The customer or recipient is redirected to HPP, where the missing information is collected before processing continues.

Example: Bank Transfer Payout

Assume your routing configuration includes a route for:

SMART_BANK_TRANSFER_PAYOUT

The payout can be processed in two different ways depending on whether you already have the bank account information required by the selected provider.

The same pattern also applies to APM payments created through:

POST /api/v1/payments/apm

If apmPayload already contains the provider-required fields, Facilero uses them directly. Otherwise, Facilero can return an HPP redirect to collect the missing information.

Case 1: Provider-Required Fields Included

When the request contains all fields required by the selected provider route, Facilero uses those fields and forwards them to the underlying APM provider.

No HPP interaction is required.

Request

{
  "requestId": "payout-1002",
  "accountId": "merchant_001",
  "amount": "100.00",
  "currency": "USD",
  "apmPayload": {
    "paymentMethod": "SMART_BANK_TRANSFER_PAYOUT",
    "paymentType": "BANK_TRANSFER",
    "accountNumber": "4051111222",
    "bankName": "ABSA",
    "accountHolderName": "John Doe",
    "bankAccountType": "cheque"
  },
  "callbackUrl": "https://merchant.example.com/webhooks/payout",
  "successRedirectUrl": "https://merchant.example.com/payout/success",
  "failureRedirectUrl": "https://merchant.example.com/payout/failure"
}

Response

{
  "status": "PENDING",
  "apmResponseData": {
    "actionType": "NONE"
  }
}

Behavior

The response is non-interactive.

apmResponseData.actionType = NONE

The transaction continues asynchronously and typically enters a status such as:

• PENDING
• PROCESSING

No redirect URL is returned.

Case 2: Collect Missing Fields Through HPP

If you do not have the provider-required bank transfer details when creating the payout, you can submit only the payment method identifiers.

Facilero returns an HPP redirect so the recipient can provide the missing information.

Request

{
  "requestId": "payout-1002",
  "accountId": "merchant_001",
  "amount": "100.00",
  "currency": "USD",
  "apmPayload": {
    "paymentMethod": "SMART_BANK_TRANSFER_PAYOUT",
    "paymentType": "BANK_TRANSFER"
  },
  "callbackUrl": "https://merchant.example.com/webhooks/payout",
  "successRedirectUrl": "https://merchant.example.com/payout/success",
  "failureRedirectUrl": "https://merchant.example.com/payout/failure"
}

Response

{
  "status": "PENDING",
  "apmResponseData": {
    "actionType": "REDIRECT",
    "redirectUrl": "https://hpp.exirom.com/session/abc123"
  }
}

Behavior

The response contains an HPP redirect action.

Typical flow:

1. Facilero returns a redirect URL in apmResponseData.redirectUrl.
2. Redirect the recipient to the provided URL.
3. The Hosted Payment Page collects the required bank transfer information.
4. Facilero submits the collected data to the underlying APM provider.
5. Transaction processing continues asynchronously.

For details about redirect responses and payload structure, see Redirect Flow Payload.

Payment Flow Example

The same mechanism is available for APM payments.

Payment Request With Complete Provider Data

If all required provider fields are present in apmPayload, Facilero processes the payment immediately without any HPP interaction.

Payment Request With Missing Provider Data

If required fields are missing, Facilero returns an HPP redirect and collects the missing information from the customer before continuing the payment flow.

Redirect Handling

When an HPP redirect is returned:

1. Store the transaction identifier.
2. Redirect the customer or recipient to apmResponseData.redirectUrl.
3. Wait for asynchronous transaction updates.
4. Do not assume the redirect result represents the final transaction outcome.

The customer or recipient may:

• Close the browser
• Abandon the flow
• Return before provider processing completes
• Experience delays in provider-side processing

Because of this, the redirect itself should never be used as the final transaction status.

Determining the Final Result

Use the same completion strategy as all other APM redirect flows.

Recommended Status Handling

Treat webhook notifications as the authoritative source for final transaction states.

Typical final states include:

• SUCCEED
• FAILED

If webhook delivery fails or is delayed, query the transaction status endpoint to retrieve the latest status.

Summary

Facilero's APM data collection flow allows merchants to create payments and payouts even when provider-specific customer or recipient information is not yet available.

• Submit a complete apmPayload when you already have the required provider fields.
• Submit only the APM method identifiers when you do not have the required fields.
• Facilero automatically determines whether additional information is needed.
• If required, Facilero redirects the customer or recipient to the Hosted Payment Page (HPP) to collect the missing information.
• Final transaction results are always determined through webhooks or status checks, not by the redirect itself.

This enables a single APM integration to support multiple providers while accommodating different provider-specific data requirements.