Havale Payout Payload

Direct and data-collection payloads for Havale payouts.

Payment Method Identifier: HAVALE_PAYOUT | Payment Type: BANK_TRANSFER

Havale Payout is a TRY bank-transfer payout. For direct S2S processing, submit the beneficiary's account-holder name and IBAN in apmPayload.

If these fields are omitted and data collection is enabled for the configured route, Facilero returns a customer-verification redirect. The customer enters the missing details on Facilero page, and the payout then continues.

Currently supported for payouts via POST /api/v1/payouts/apm.

Choose One Submission Mode

Direct S2S: Send both accountHolderName and iban. No customer redirect is required.
Facilero data collection: Omit both fields. The route's external MID must have data collection enabled.

Important: Do not send only one beneficiary field. A partial payload does not start data collection and fails validation.

Requirements

Currency must be TRY.
Amount must be a positive whole number.
The account-holder name and IBAN are required to process the payout. They may be supplied directly or collected by Facilero.
The IBAN is normalized and validated before the payout is sent.

Payload Structure

{
  "paymentMethod": "HAVALE_PAYOUT",
  "paymentType": "BANK_TRANSFER",
  "accountHolderName": "Demo Customer",
  "iban": "TR000000000000000000000000"
}

Payload Fields

Field	Type	Required	Description
`paymentMethod`	Enum	Yes	Must be `HAVALE_PAYOUT`
`paymentType`	Enum	Yes	Must be `BANK_TRANSFER`
`accountHolderName`	String	Conditional	Required for direct S2S processing; omit only when using Facilero data collection
`iban`	String	Conditional	Required for direct S2S processing; omit only when using Facilero data collection

Direct S2S Response

{
  "paymentMethod": "HAVALE_PAYOUT",
  "paymentType": "BANK_TRANSFER",
  "actionType": "NONE",
  "providerTransactionId": "39662324"
}

Response Fields

Field	Type	Description
`paymentMethod`	Enum	Always `HAVALE_PAYOUT`
`paymentType`	Enum	Always `BANK_TRANSFER`
`actionType`	Enum	`NONE` for direct processing; `REDIRECTION` when Facilero must collect data
`providerTransactionId`	String	Provider transaction identifier

With complete beneficiary data, the initial payout response is normally PROCESSING.

Direct Payout Request Example

Use dummy data only in examples. This is a direct S2S request with all beneficiary data present:

{
  "accountId": "123456789012345678",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "amount": "5000",
  "currency": "TRY",
  "callbackUrl": "https://merchant.example/webhooks/apm",
  "device": {
    "ip": "203.0.113.10"
  },
  "billingDetails": {
    "email": "[email protected]"
  },
  "apmPayload": {
    "paymentMethod": "HAVALE_PAYOUT",
    "paymentType": "BANK_TRANSFER",
    "accountHolderName": "Demo Customer",
    "iban": "TR000000000000000000000000"
  }
}

Rejected Direct Payout Example

A provider can reject a direct payout before it is accepted for processing. In that case, Facilero returns FAILED and no customer action is required:

{
  "requestId": "00000000-0000-4000-8000-000000000001",
  "transactionId": "900000000000000001",
  "paymentType": "APM",
  "transactionStatus": "FAILED",
  "declineCode": 82,
  "apmResponseData": {
    "paymentMethod": "HAVALE_PAYOUT",
    "paymentType": "BANK_TRANSFER",
    "actionType": "NONE"
  }
}

Transaction Details After Rejection

The transaction-details response can retain the sanitized request and final rejection data for troubleshooting:

{
  "requestBody": {
    "accountId": "123456789012345678",
    "createdAt": "2026-08-31T12:00:00Z",
    "requestId": "00000000-0000-4000-8000-000000000001",
    "transactionId": "900000000000000001",
    "callbackUrl": "https://merchant.example/webhooks/apm",
    "transactionStatus": "FAILED",
    "declineCode": "82",
    "declineSubReason": "Payout was rejected",
    "apmRequestPayload": {
      "paymentMethod": "HAVALE_PAYOUT",
      "paymentType": "BANK_TRANSFER",
      "accountHolderName": "Demo Customer",
      "iban": "TR000000000000000000000000"
    },
    "apmResponseData": {
      "paymentMethod": "HAVALE_PAYOUT",
      "paymentType": "BANK_TRANSFER",
      "actionType": "NONE"
    }
  }
}

This is transaction detail data, not the provider callback. Use the merchant callbackUrl for final asynchronous status updates.

Data-Collection Redirect

To request Facilero collection, submit only the method identifiers in apmPayload:

{
  "paymentMethod": "HAVALE_PAYOUT",
  "paymentType": "BANK_TRANSFER"
}

Facilero returns the payout in customer verification:

{
  "transactionId": "869898069059073246",
  "transactionStatus": "CUSTOMER_VERIFICATION",
  "apmResponseData": {
    "paymentMethod": "HAVALE_PAYOUT",
    "paymentType": "BANK_TRANSFER",
    "actionType": "REDIRECTION",
    "redirectUrl": "https://checkout.example.com/?token=..."
  }
}

The merchant must open apmResponseData.redirectUrl in the customer's browser. Facilero cannot redirect a server-to-server API call automatically.

After the customer submits the account-holder name and IBAN on Facilero's checkout page, the same payout continues to the provider.

If the merchant cannot redirect the customer, it must collect both fields itself and use direct S2S mode. If the returned URL is not opened and completed, the payout remains in CUSTOMER_VERIFICATION.

Use the callback as the authoritative final result. Duplicate callbacks must not be processed more than once.

For provider-independent routing, send the same beneficiary fields with paymentMethod: SMART_BANK_TRANSFER_PAYOUT.