Initiating a Payout

This guide explains how to initiate payouts using the Exirom Alternative Payment Methods (APM) API.
The payout API allows merchants to disburse funds to beneficiaries via multiple methods such as e-wallets, bank accounts, and mobile wallets.

Note: This endpoint mirrors the structure of the APM Payment API but is designed specifically for outbound transactions (payouts) instead of incoming payments.

API Endpoint

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

Request

Headers

Header	Type	Required	Description
`Content-Type`	String	Yes	Must be `application/json`.
`Authorization`	String	Yes	`Bearer <AUTH_TOKEN>` – Token obtained from Authorization Service.
`Referer`	String	Yes	Domain from which the request originates.

Example: Payout Request Body (E-Wallet)

{
  "requestId": "payout-req-10001",
  "accountId": "12345",
  "apmPayload": {
    "paymentMethod": "ExPay",
    "paymentType": "E_WALLET",
    "walletId": "wallet-98765"
  },
  "amount": "250.00",
  "currency": "USD",
  "callbackUrl": "https://merchant.example.com/callbacks/payouts",
  "successRedirectUrl": "https://merchant.example.com/payout/success",
  "failureRedirectUrl": "https://merchant.example.com/payout/failure",
  "billingDetails": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "country": "US"
  }
}

Request Fields Description

Field	Type	Required	Description
`requestId`	String	Yes	Unique identifier for the payout request.
`accountId`	String	Yes	Merchant’s account ID associated with the payout.
`apmPayload`	Object (ApmPayload)	Yes	Contains method-specific fields; structure varies by payout method.
`amount`	String	Yes	Amount to be paid out (as string to preserve decimal precision).
`currency`	String	Yes	Currency code in ISO 4217 format (e.g., `USD`, `EUR`).
`callbackUrl`	String	No	URL where Exirom will POST the final transaction status.
`successRedirectUrl`	String	No	Redirect URL after a successful payout (if user-facing).
`failureRedirectUrl`	String	No	Redirect URL after a failed payout (if user-facing).
`metadata`	Map<String, String>	No	Optional metadata for tracking or reconciliation.
`order`	Object (Order)	No	Optional order-related information.
`billingDetails`	Object (ApmBillingDetails)	No	Beneficiary’s details (may be required for certain payout methods).
`device`	Object (Device)	No	Optional device information for fraud detection and transaction logging.

Successful Response

Example

{
  "requestId": "payout-req-10001",
  "transactionId": "payout-tx-55555",
  "transactionStatus": "PENDING",
  "apmResponseData": {
    "paymentMethod": "ExPay",
    "paymentType": "E_WALLET",
    "providerTransactionId": "ExPay-out-abc123"
  },
  "createdTime": "2025-07-14T10:00:00Z"
}

Response Fields Description

Field	Type	Description
`requestId`	String	Echoed request ID from your payout initiation.
`transactionId`	String	Unique ID assigned to the payout transaction.
`transactionStatus`	Enum (TxStatus)	Status of the transaction: `PENDING`, `COMPLETED`, `DECLINED`.
`declineCode`	Integer	Error code if the transaction was declined.
`declineSubReason`	String	Optional text with additional decline reason.
`apmResponseData`	Object (ApmResponseData)	Provider-specific response data (e.g., payout reference ID).
`createdTime`	String	Timestamp indicating when the transaction was created.

Callback (Webhook)

If a callbackUrl is provided, Exirom will send a POST request to that URL with the final payout transaction status.

Callback Headers

Header	Type	Description
`X-Checksum`	String	HMAC-SHA256 checksum computed using `accountId`, `amount`, `currency`, `transactionId`.

Callback Payload Example

Callback data follows the ApmPaymentTxInfoDto structure:

{
  "transactionId": "payout-tx-55555",
  "requestId": "payout-req-10001",
  "accountId": 12345,
  "transactionStatus": "COMPLETED",
  "orderCurrency": "USD",
  "processedCurrency": "USD",
  "orderAmount": 250.00,
  "processedAmount": 250.00,
  "conversionRate": 1.0,
  "apmRequestPayload": {
    "paymentMethod": "ExPay",
    "paymentType": "E_WALLET",
    "walletId": "wallet-98765"
  },
  "apmResponseData": {
    "paymentMethod": "ExPay",
    "paymentType": "E_WALLET",
    "providerTransactionId": "ExPay-out-abc123"
  },
  "callbackUrl": "https://merchant.example.com/callbacks/payouts",
  "billingDetails": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "country": "US"
  },
  "createdAt": "2025-07-14T10:00:00Z"
}

Fields Description

Field	Type	Description
`transactionId`	String	Unique payout transaction ID.
`requestId`	String	Original request ID sent during payout initiation.
`accountId`	Long	Merchant’s account ID.
`transactionStatus`	Enum	Final status of the payout (e.g., `COMPLETED`).
`declineCode`	Integer	Error code if the payout failed.
`declineSubReason`	String	Detailed decline reason if applicable.
`orderCurrency`	String	Original currency requested.
`processedCurrency`	String	Final processed currency (after conversions).
`orderAmount`	Double	Original payout amount.
`processedAmount`	Double	Final processed amount after conversions.
`conversionRate`	Double	Applied conversion rate (if any).
`apmRequestPayload`	Object	Original `apmPayload` sent with the payout request.
`apmResponseData`	Object	Provider response data.
`callbackUrl`	String	Callback URL provided in the request.
`billingDetails`	Object	Beneficiary billing information.
`order`	Object	Optional order information.
`createdAt`	String	Timestamp when the transaction was created.

Status Codes

HTTP Status	Meaning
`200 OK`	Payout request accepted.
`201 Created`	New payout successfully created.
`400`	Invalid or malformed request.
`401`	Unauthorized request.
`404`	Resource not found.
`500`	Internal server error.

Notes

The payout API is request-response based and supports webhook callbacks for final transaction status.
Certain payout methods may require additional KYC/AML verification depending on the provider.
Always verify the final payout status via the callback or by polling the /info/{transactionId} endpoint (future support).