APM Payout API Documentation

Overview

This document outlines how to initiate payouts using the Facilero Alternative Payment Methods (APM) API. This API enables merchants to disburse funds to users through various methods such as e-wallets, bank accounts, and mobile wallets.

Note: This endpoint mirrors the structure and principles of the APM payment API but is used for outbound transactions (payouts) instead of incoming payments.

API Endpoint

🔹 Live

POST https://api.facilero.com/api/v1/payouts/apm

🔸 Sandbox

POST https://sandbox.facilero.com/api/v1/payouts/apm

Request Headers

Header	Type	Required	Description
`Content-Type`	String	Yes	Must be `application/json`
`Authorization`	String	Yes	`Bearer <AUTH_TOKEN>` — the token from the Authorization Service
`Referer`	String	Yes	Referring domain for the request

Request Body

Fields

Field	Type	Required	Description
`requestId`	String	Yes	Unique identifier for the payout request
`accountId`	String	Yes	Merchant account ID to associate the payout
`apmPayload`	Object (ApmPayload)	Yes	Contains method-specific fields; structure depends on payout method
`amount`	String	Yes	Amount to be paid out (as string to maintain precision)
`currency`	String	Yes	ISO 4217 code (e.g., USD, EUR)
`callbackUrl`	String	No	URL to receive transaction status updates
`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
`order`	Object (Order)	No	Optional order-related information
`billingDetails`	Object (ApmBillingDetails)	No	Beneficiary’s personal details (required for certain payout methods)
`device`	Object (Device)	No	Optional device information used for fraud detection and logging

Response

Fields

Field	Type	Description
`requestId`	String	Echoed request ID
`transactionId`	String	Unique ID for the payout transaction
`transactionStatus`	Enum (TxStatus)	Status of the transaction: `PENDING`, `COMPLETED`, `DECLINED`, etc.
`declineCode`	Integer	Error code if declined
`declineSubReason`	String	Optional text describing reason for decline
`apmResponseData`	Object (ApmResponseData)	Provider-specific response data, such as payout reference or redirect URLs
`createdTime`	String	Timestamp of when the transaction was created

Callback (Webhook)

If a callbackUrl is provided, Facilero will POST the final transaction result to it.

Headers

Header	Type	Description
`X-Checksum`	String	HMAC-SHA256 checksum based on `accountId`, `amount`, `currency`, `transactionId`

Body

Follows the ApmPaymentTxInfoDto format:

Field	Type	Description
`transactionId`	String	Unique payout transaction ID
`requestId`	String	Original request ID
`accountId`	Long	Merchant account ID
`transactionStatus`	Enum	Transaction status
`declineCode`	Integer	Error code, if declined
`declineSubReason`	String	Additional explanation if declined
`orderCurrency`	String	Original currency
`processedCurrency`	String	Final currency after conversion (if any)
`orderAmount`	Double	Original payout amount
`processedAmount`	Double	Final processed amount
`conversionRate`	Double	Conversion rate applied
`apmRequestPayload`	Object	Original `apmPayload` sent
`apmResponseData`	Object	Response data from the payout provider
`callbackUrl`	String	Callback URL from the request
`billingDetails`	Object	Beneficiary billing information
`order`	Object	Optional order info
`createdAt`	String	Creation timestamp

Example Request (Payout to 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"
  }
}

Example Response

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

Example Callback

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

Status Codes

HTTP Status	Meaning
`200 OK`	Payout request accepted
`400`	Invalid request
`401`	Unauthorized
`404`	Resource not found
`500`	Internal server error

Notes

This payout API is request-response and callback-based.
Payouts may be subject to additional KYC/AML requirements depending on the provider.
Always verify final status via callback or polling the /info/{transactionId} endpoint (future support).