Processing the Payment Response

After you initiate the payment, the Exirom API will immediately return a response indicating the transaction was created. This response includes a transaction ID, status, and potentially additional data needed to proceed.

Typically, for APM transactions, the initial transactionStatus will be PENDING, indicating that the payment is not yet complete and likely requires further customer action (such as redirection to an external site or additional authorization). The response contains an apmResponseData object which provides information on what the next step is (for example, a URL to redirect the customer to, or a URL to load in an iframe).

If the chosen APM requires the user to complete payment on a third-party page, the apmResponseData.redirectUrl field will be present. For methods that embed a payment interface, an iframeUrl may be provided instead. Your integration should check for these and guide the customer appropriately:

If redirectUrl is provided, redirect the user’s browser to that URL (often a payment provider page) to complete the payment.
If iframeUrl is provided, you can load that URL in an iframe on your site to let the user complete the payment inline.

In cases where neither a redirect nor an iframe URL is provided (for example, if the payment method is handled completely via backend or was instantly processed), the transaction might move straight to a final state (e.g., COMPLETED or DECLINED) without additional user steps. In such cases, you would simply await the callback for the final status or poll the status 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 Exirom).
`transactionStatus`	Enum (TxStatus)	Current status of the transaction. Common values include `PENDING` (transaction initiated and awaiting completion), `COMPLETED` (payment succeeded), `DECLINED` (payment was declined), 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.
`redirectUrl`	String	URL to which the customer should be redirected to complete the payment (present only for redirect-based flows).
`iframeUrl`	String	URL that can be embedded in an iframe to complete the payment (present for iframe-based flows).
`providerTransactionId`	String	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.

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 PENDING state, indicating the customer still needs to complete the payment (by being redirected to ExPay):

{
  "requestId": "req-123456789",
  "transactionId": "tx-987654321",
  "transactionStatus": "PENDING",
  "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
    "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.