Skip to content

Payout

Payout Payment Method

A Payout transaction allows merchants to transfer funds directly to a beneficiary's bank account or mobile wallet. Unlike standard purchase or authorization transactions that collect funds from a customer, a payout pushes funds to the recipient. Common use cases include disbursements, withdrawals, seller payments, and payroll.

Payouts are initiated via the Direct API and are processed asynchronously — the transaction may initially return a PENDING status, with the final result delivered via webhook.

Integration Type Limitation

Payouts are only supported via the Direct API integration. Hosted Payment Page (HPP) and Embedded Fields (EF) integration types are not supported for payout transactions.

Key Characteristics

  1. Push Payment

    • A payout sends funds to a beneficiary, rather than collecting funds from a customer.
    • This is an initial transaction type — it does not require a parent transaction.

  2. Beneficiary-Based

    • Instead of payment card details, the request requires a beneficiary object specifying the destination type (e.g., bank_account) and the relevant account details.
    • For INR payouts, the beneficiary must include an IFSC code (Indian Financial System Code) to identify the destination bank branch.

  3. No 3D Secure Authentication

    • Payout transactions do not require 3D Secure authentication.
    • As a result, browser_info is not required in the request.

  4. Terminal ID Specification

    • The terminal_id must be specified in the request. The terminal must be configured to support payout transactions (feature: TRX_TYPE_PAYOUT).

  5. Asynchronous Processing

Request Requirements

Field Required Notes
terminal_id Yes Must support payout transactions
reference Yes Unique payout reference per terminal (max 40 chars). Idempotent — duplicate references with the same amount/currency will return the existing transaction.
description Yes Human-readable payout description (max 100 chars)
currency Yes ISO 4217 currency code (e.g., INR, EUR, USD)
amount Yes Amount in minor units (e.g., 10000 = 100.00 INR)
beneficiary.type Yes Beneficiary type: bank_account or mobile_money
beneficiary.data Yes Beneficiary details (see below)
customer No Customer details
metadata No Arbitrary key-value metadata
customer_ip No Customer IP address (defaults to request IP)
return_url No URL to redirect after successful payout
error_url No URL to redirect after failed payout
cancel_url No URL to redirect after canceled payout
options No Provider-specific options

Beneficiary Data — Bank Account (INR)

When processing INR payouts to Indian bank accounts, the beneficiary object must include the following fields:

Field Required Description
account_number Yes Beneficiary bank account number
account_name Yes Name of the account holder
ifsc Yes IFSC code (Indian Financial System Code) — identifies the bank branch
bank_code No Bank code
bank_name No Name of the bank
bank_branch No Branch name
bank_address No Bank address
bank_city No Bank city
bank_state No Bank state
mobile No Beneficiary mobile number

Processing Flow

sequenceDiagram
    participant Merchant
    participant Gateway
    participant PSP

    Merchant->>Gateway: POST /api/transactions/payout
    Gateway->>Gateway: Validate request & terminal
    Gateway->>Gateway: Resolve payment provider
    Gateway->>PSP: Submit payout
    PSP-->>Gateway: Processing result (PENDING/APPROVED/DECLINED)
    Gateway-->>Merchant: Transaction response

    Note over PSP,Gateway: Asynchronous settlement

    PSP->>Gateway: Callback with final status
    Gateway->>Merchant: Webhook notification (APPROVED/DECLINED)

Supported Transactions

Transaction Type Supported Description
PAYOUT Yes Transfer funds to a beneficiary bank account or wallet
REFUND No Not applicable for payouts
CAPTURE No Not applicable (single-step flow)
VOID No Not supported

Supported Currency

Currency Code Description
Indian Rupee INR Supported for bank account payouts with IFSC

Additional currencies may be supported depending on the configured payment provider. Contact support for details.

Transaction Statuses

Status Description Final State
PENDING Payout submitted and awaiting provider confirmation No
APPROVED Payout successfully processed and funds transferred Yes
DECLINED Payout rejected by the provider or bank Yes

Important Notes

  • The reference field is idempotent per terminal. Sending the same reference with the same amount and currency returns the existing transaction. Different amount/currency values will result in a validation error.
  • For INR payouts, the ifsc field is mandatory in the beneficiary data. Ensure the IFSC code is valid and corresponds to the correct bank branch.
  • Account numbers are masked in API responses (only the last 4 digits are visible) for security purposes.
  • Always subscribe to webhooks to receive the final payout status, as payouts are typically processed asynchronously.