Initiating a Payment

To initiate an APM payment, send an HTTP POST request to the Exirom APM payments endpoint. In production, the endpoint URL will be something like:

POST https://${host}/api/v1/payments/apm

Replace ${host} with the appropriate API hostname (for example, api.exirom.com for the live environment).

Request Headers

Include the following HTTP headers in your payment request:

• Content-Type: application/json
• Authorization: Bearer <AUTH_TOKEN> – Replace <AUTH_TOKEN> with the actual API token obtained from Exirom’s authorization service.
• Referer: <REFERER_URL> – Replace <REFERER_URL> with your website’s URL or the relevant referring page URL (used by Exirom for security and context).

Request Body Fields

The body of the request should be a JSON object containing the following fields:

Note: Fields marked with No* are not required for every integration by default, but certain payment methods or configurations may require them. For example, some APM providers might mandate a callbackUrl to be set, or specific billing details to be provided. Always check the requirements of the specific APM you are integrating.

The billingDetails, device, and order fields in the request body are objects that contain detailed sub-fields as described below:

ApmBillingDetails Object

This object contains information about the customer’s billing details. Fields are typically optional unless required by a specific payment method or regional regulation:

Note: Billing detail fields are generally optional by default, but specific APMs or local regulations may require some of them (for example, certain methods might require firstName/lastName or an identityCode. Refer to the documentation of the specific APM provider to determine which of these fields are necessary.

Device Object

The device object carries information about the customer’s device and browser, often used for fraud prevention or additional authentication:

Note: As with billing details, all device fields are optional by default. However, providing as many as possible can help with risk assessment and may be required by some payment methods for compliance or fraud checks.

Order Object

The order object contains information about the purchase or order related to the payment:

Note: Order fields are optional by default. The items array can be used to pass detailed breakdown of the order (for example, list of products or services purchased), though not all integrations require it. If provided, each item in items can include fields like name, quantity, price (as illustrated in the example below).

Example Payment Request

{
  "requestId": "req-123456789",
  "accountId": "12345",
  "apmPayload": {
    "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
    // Additional ExPay-specific fields would go here
  },
  "amount": "100.00",
  "currency": "USD",
  "callbackUrl": "https://merchant.example.com/callbacks/payments",
  "billingDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "postalCode": "10001"
  },
  "order": {
      "date": "2025-08-06T09:30:30Z",
      "orderId": "order-345678",
      "title": "Affiliate Payment",
      "siteId": "site-123",
      "name": "August Affiliate Payment",
      "domainName": "affiliates.example.com"
    },
  "metadata": {
    "customField1": "value1",
    "customField2": "value2"
  },
  "checksum": "<HMAC-SHA256 signature>"
}

In the above example:

• The paymentMethod and paymentType in apmPayload specify the APM (ExPay e-wallet in this case).
• The checksum would be computed by your server using a secret (not shown) according to Exirom’s checksum guidelines.
• callbackUrl is set so that the merchant’s server will receive a notification when the payment completes.
• successRedirectUrl and failureRedirectUrl are omitted in this example, meaning the customer will remain on the APM’s page or default flow after payment (or you will handle redirection via the response data, explained next).