APM Payment Flows

When you initiate an APM payment, the response includes an apmResponseData.actionType field that determines what happens next. It takes one of five values — REDIRECTION, QR, REFERENCE, NONE and KYC_REQUIRED — and each one requires different handling on your side.

Every flow starts at the same API endpoint and ends with the same webhook-based final result. The difference is what happens in between. Identity verification is the one flow with a step of its own: the customer's data goes to a separate endpoint, and the payment then continues with the method's usual flow. It is documented on Identity Verification.

The webhook callback is always the source of truth for the final transaction result. Never rely on redirects, QR scanning confirmation, or the initial response status to determine payment outcome.

If a provider route requires APM fields that you do not have at request time, Exirom can return an HPP redirect to collect that data before processing. See APM Data Collection.

---

#Quick Reference

---

#Flow 1: Redirect (actionType = REDIRECTION)

The most common APM flow. The customer is redirected to the payment provider's hosted page to authenticate and authorize the payment.

1. You receive apmResponseData.redirectUrl, and optionally iframeUrl. Full apmResponseData examples: Redirect Flow Payload
2. Redirect the customer to redirectUrl — or embed iframeUrl on desktop if your UX supports it
3. The customer authenticates on the provider's page
4. The provider redirects them back to your successRedirectUrl or failureRedirectUrl
5. You receive the final result via webhook

#Redirect vs Iframe

If both URLs are returned, use the iframe on desktop and fall back to redirect on mobile or if the iframe fails to load.

---

#Flow 2: QR Code (actionType = QR)

Used for payment methods where the customer scans a QR code with their mobile payment app (PIX, Alipay, WeChat Pay, UPI, etc.).

1. You receive apmResponseData.qrData (Base64 QR image), qrDeepLink (opens payment app directly), and/or qrCodeImageUrl (pre-hosted image URL). Full apmResponseData examples: QR Flow Payload
2. On desktop: display the QR code image for the customer to scan with their phone
3. On mobile: use the deep link to open the payment app directly
4. The customer's browser stays on your page while they pay on their phone — you must update the UI when the payment completes
5. You receive the final result via webhook; push the result to the frontend via your preferred mechanism (WebSocket, SSE, or polling your own backend)

#QR Expiration

QR codes typically expire within 1–5 minutes (varies by provider). Your UI should show a countdown and offer a refresh option when expired. Never cache or reuse an expired QR.

---

#Flow 3: No Customer Action (actionType = NONE)

Some APMs process entirely server-side with no customer interaction after the initial request. Common for pre-authorized bank transfers, certain voucher payments, and repeat APM transactions.

The response may be immediately final (SUCCEED or FAILED) or async (PROCESSING / PENDING). In the async case, wait for the webhook — do not poll more frequently than every 5 minutes as a fallback. Full apmResponseData examples: S2S Flow Payload

---

#Flow 4: Reference Data (actionType = REFERENCE)

The provider returns the data the customer needs in order to pay outside your checkout, and the customer pays with it. What the data is depends on the payment method: bank details and a payment reference for a transfer, a code to present at a cash payment point, and so on.

1. You receive apmResponseData.actionType: "REFERENCE" with a references array and customerInstructionsByLanguage
2. Display every entry of references with its label, together with the order amount and currency. The entries differ by payment method, so render the list as it comes rather than expecting particular keys
3. Display the instructions for the customer's language, falling back to en
4. The customer pays with the data shown. Any reference value must be passed on exactly as displayed, otherwise the provider cannot match the payment to the order
5. You receive the final result via webhook

Full apmResponseData examples: PayID Payment Payload, ARS Payment Payload

---

#Flow 5: Identity Verification (actionType = KYC_REQUIRED)

Some payment methods verify the customer's identity before the payment can continue. The verification belongs to the payment: it has its own endpoint, and the payment then continues with the method's usual flow.

1. You receive apmResponseData.actionType: "KYC_REQUIRED" with an iframeUrl
2. Collect the identity data, either with your own form or with the hosted form at iframeUrl
3. Submit it to POST /api/v1/payments/apm/kyc/{transactionId}
4. An accepted submission continues the payment and the response carries the method's usual apmResponseData; input errors come back as kycResponseData.errors for the customer to correct
5. You receive the final result via webhook

Full walkthrough, both form options and the message contract: Identity Verification

---

#Common Patterns

---

#Related

• API Reference: POST /api/v1/payments/apm — Full endpoint spec, Try It
• Handling the Callback — Full webhook schema
• APM Data Collection — HPP collection for provider-required fields
• Checksum Authentication — HMAC verification for requests and callbacks
• APM Payload References — All supported payment methods