APM Data Collection

Some APM providers require customer or recipient fields that may not be available when you create the transaction. For supported routes, you can send the APM payment or payout with only the method identifiers in apmPayload. If the selected underlying provider needs more data, Exirom returns a redirect to the Hosted Payment Page so the customer or recipient can provide the missing fields.

This keeps one APM integration usable across providers with different data requirements. Your server creates the payment or payout, redirects the customer when requested, and receives the final result through the normal webhook/status flow.

#When This Applies

APM data collection can apply to both:

The behavior depends on your merchant configuration, selected APM method, country, currency, and the underlying provider route. If the selected route does not require additional fields, Exirom processes the request normally.

#Example: Bank Transfer Payout

Suppose your routing configuration includes a branch for SMART_BANK_TRANSFER_PAYOUT. The same payout can work in two ways depending on whether you already have the bank transfer fields required by the underlying APM solution provider.

For payments, the same pattern applies to POST /api/v1/payments/apm: if apmPayload already contains the provider-required fields, Exirom uses them; if provider-required fields are missing, Exirom can return an HPP redirect to collect them.

#Case 1: Send Provider-Required Fields

When the request contains all fields required by the selected provider route, Exirom uses those fields and passes them to the underlying APM solution provider. No data collection redirect is needed.

{
  "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"
}

The response is non-interactive: apmResponseData.actionType is NONE, and the transaction continues asynchronously with a status such as PENDING or PROCESSING.

{
  "requestId": "payout-1002",
  "transactionId": "839134051673863240",
  "transactionStatus": "PENDING",
  "apmResponseData": {
    "paymentMethod": "SMART_BANK_TRANSFER_PAYOUT",
    "paymentType": "BANK_TRANSFER",
    "providerTransactionId": "288700",
    "actionType": "NONE"
  },
  "paymentType": "APM"
}

#Case 2: Let HPP Collect Missing Fields

If you do not have the provider-required bank transfer fields at payout creation time, send only the method identifiers. Exirom returns an HPP redirect so the recipient can provide the missing fields.

{
  "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"
}

The response uses the same redirect pattern as other APM redirect flows:

{
  "requestId": "payout-1002",
  "transactionId": "837792634904173233",
  "transactionStatus": "CUSTOMER_VERIFICATION",
  "apmResponseData": {
    "paymentMethod": "SMART_BANK_TRANSFER_PAYOUT",
    "paymentType": "BANK_TRANSFER",
    "redirectUrl": "https://checkout.com?token=837792635105499691%3A1777582129645%3Afe3173075e267eb0262e73784e13ffa4%3AjOsi8jFkZ4Bw7Ec40YtbJhqqhFSSiAz6lDic_8ESlM8",
    "iframeUrl": null,
    "providerTransactionId": null,
    "accountHolderName": null,
    "maskedAccountNumber": null,
    "branchCode": null,
    "bankCode": null,
    "iban": null,
    "bic": null,
    "routingNumber": null,
    "sortCode": null,
    "swiftCode": null,
    "accountNumber": null,
    "institutionNumber": null,
    "transitNumber": null,
    "bankName": null,
    "bankCity": null,
    "country": null,
    "bankAccountType": null,
    "bankCleaningSystemId": null,
    "securityQuestion": null,
    "securityAnswer": null,
    "bankMetadata": null,
    "actionType": "REDIRECTION",
    "qrData": null,
    "qrDeepLink": null
  },
  "paymentType": "APM"
}

Redirect the recipient to apmResponseData.redirectUrl. Exirom HPP collects the provider-required fields and continues the payout by passing the collected payload to the underlying APM solution provider.

See Redirect Flow Payload for the response field structure and standard redirect handling recommendations.

#Final Result

Do not treat the redirect itself as the final transaction result. The customer or recipient may close the browser, abandon the page, or return before the provider has completed processing.

Use the same completion rules as other APM flows:

#Related

• APM Payment Flow - Redirect, QR, and server-to-server payment flows
• APM Payout Flow - End-to-end APM payout processing
• Redirect Flow Payload - actionType: REDIRECTION payload structure
• APM Payload References - Supported payload fields per method