Direct API Integration¶

Payout – API Integration¶

This page provides guidance for integrating Payouts using the Direct API approach. Payouts allow you to transfer funds directly to a beneficiary's bank account.

Your platform is responsible for:

Collecting beneficiary bank account details (account number, account name, IFSC code for INR)
Initiating the payout request with the correct beneficiary type and data
Handling asynchronous webhook callbacks for final transaction status
Verifying the transaction status via the Transaction Status API

Beneficiary Type¶

When initiating a payout request, specify the beneficiary type in the beneficiary.type field:

Type	Description
`bank_account`	Bank account transfer (required for INR payouts)

Required Beneficiary Data (INR Bank Account)¶

Each INR payout must include the following fields in beneficiary.data:

Field	Type	Required	Description
`account_number`	string	Yes	Beneficiary bank account number
`account_name`	string	Yes	Full name of the account holder
`ifsc`	string	Yes	IFSC code — Indian Financial System Code identifying the bank and branch (e.g., `SBIN0001234`)
`bank_code`	string	No	Bank code
`bank_name`	string	No	Name of the bank
`bank_branch`	string	No	Branch name
`bank_address`	string	No	Bank address
`bank_city`	string	No	City of the bank branch
`bank_state`	string	No	State of the bank branch
`mobile`	string	No	Beneficiary mobile number

Example Request¶

{
  "terminal_id": "TERM001",
  "reference": "PAYOUT-INR-20260319-001",
  "description": "INR payout to beneficiary bank account",
  "currency": "INR",
  "amount": 10000,
  "beneficiary": {
    "type": "bank_account",
    "data": {
      "account_number": "000133524852",
      "account_name": "Test User",
      "ifsc": "SBIN0001234"
    }
  },
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "customer_ip": "192.168.1.1"
}

The amount is in minor units. For INR, 10000 represents 100.00 INR.

Example Response (Pending)¶

{
  "result": {
    "id": "PyTxAbCdEfGhIjKlMnOp",
    "merchant_id": "0000000000000fpg-dev",
    "order_id": "ORD_PAYOUT_20260319_001",
    "terminal_id": "TERM001",
    "reference": "PAYOUT-INR-20260319-001",
    "description": "INR payout to beneficiary bank account",
    "currency": "INR",
    "amount": 10000,
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    },
    "processing_result": {
      "payment_provider_id": "PP_T365",
      "payment_provider_account_id": "PPACCT_INR001"
    },
    "approved": false,
    "pending": true,
    "channel": "ecommerce",
    "transaction_type": "PAYOUT",
    "status": "PENDING",
    "payment_method": {
      "method": "****4852",
      "type": "payout_upi",
      "masked": "****4852"
    },
    "normalized_amount": 10000,
    "errors": []
  },
  "action": null,
  "redirect": null,
  "form_submit": null
}

Example Response (Approved)¶

{
  "result": {
    "id": "PyTxAbCdEfGhIjKlMnOp",
    "merchant_id": "0000000000000fpg-dev",
    "order_id": "ORD_PAYOUT_20260319_001",
    "terminal_id": "TERM001",
    "reference": "PAYOUT-INR-20260319-001",
    "description": "INR payout to beneficiary bank account",
    "currency": "INR",
    "amount": 10000,
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    },
    "processing_result": {
      "payment_provider_id": "PP_T365",
      "payment_provider_account_id": "PPACCT_INR001",
      "approval_code": "AUTH789",
      "reference_number": "REF_PAYOUT_001"
    },
    "approved": true,
    "pending": false,
    "channel": "ecommerce",
    "transaction_type": "PAYOUT",
    "status": "APPROVED",
    "payment_method": {
      "method": "****4852",
      "type": "payout_upi",
      "masked": "****4852"
    },
    "normalized_amount": 10000,
    "errors": []
  },
  "action": null,
  "redirect": null,
  "form_submit": null
}

Payment Gateway API - Payout 1.0.0¶

This API processes payout transactions — push payments that transfer funds directly to a beneficiary's bank account or mobile wallet.

Access Token: Obtain an access token via OpenID Connect using your client credentials (client_id and client_secret are available in your merchant dashboard). See the Authentication guide for details.

Process Payout Transaction: The /api/transactions/payout endpoint initiates a payout and returns detailed response data.

Important: This endpoint requires an Authorization header with a valid Bearer token.

INR Payouts: For Indian Rupee payouts, the beneficiary must include an IFSC code (Indian Financial System Code) to identify the destination bank branch. The beneficiary.type must be bank_account.

Servers¶

Description	URL
https://api.example.com	https://api.example.com

Endpoints¶

POST /api/transactions/payout¶

Execute Payout Transaction

Description

Execute a payout transaction to transfer funds to a beneficiary's bank account.

Requirements: - An Authorization header with a valid Bearer token is required. - The beneficiary object must specify the destination type and account details. - For INR payouts, the ifsc field is mandatory in the beneficiary data.

Key characteristics: - No 3D Secure authentication — the action, redirect, and form_submit fields in the response will always be null. - Payouts may be processed asynchronously. The initial response may have status PENDING, with the final status delivered via webhook.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`bearerAuth`	header	string	N/A	No	JWT Bearer token

Request body

application/json

{
    "terminal_id": "string",
    "reference": "string",
    "description": "string",
    "currency": "INR",
    "amount": 20,
    "beneficiary": {
        "type": "bank_account",
        "data": {
            "account_number": "000133524852",
            "account_name": "Test User",
            "ifsc": "SBIN0001234",
            "bank_code": "string",
            "bank_name": "string",
            "bank_branch": "string",
            "bank_address": "string",
            "bank_city": "string",
            "bank_state": "string",
            "mobile": "string"
        }
    },
    "customer": {
        "first_name": "string",
        "last_name": "string",
        "address": "string",
        "city": "string",
        "country": "string",
        "postal_code": "string",
        "email": "string",
        "phone": "string",
        "id": "string"
    },
    "metadata": {},
    "return_url": "string",
    "options": {},
    "customer_ip": "203.0.113.42"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "description": "Request to initiate a payout transaction.",
    "properties": {
        "terminal_id": {
            "type": "string",
            "description": "Terminal identifier. The terminal must be configured to support payout transactions.",
            "minLength": 5,
            "maxLength": 20
        },
        "reference": {
            "type": "string",
            "description": "Unique payout reference per terminal (max 40 chars). Idempotent — if an order for this reference already exists with the same amount and currency, the existing transaction is returned. Different amount/currency will result in a validation error.\n",
            "minLength": 1,
            "maxLength": 80
        },
        "description": {
            "type": "string",
            "description": "Human-readable payout description.",
            "minLength": 1,
            "maxLength": 100
        },
        "currency": {
            "type": "string",
            "description": "ISO 4217 currency code (e.g., INR, EUR, USD).",
            "example": "INR",
            "minLength": 3,
            "maxLength": 3
        },
        "amount": {
            "type": "integer",
            "format": "int64",
            "description": "Payout amount in minor units (e.g., 10000 = 100.00 INR)."
        },
        "beneficiary": {
            "$ref": "#/components/schemas/BeneficiaryDto"
        },
        "customer": {
            "$ref": "#/components/schemas/CustomerDto"
        },
        "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Arbitrary key-value metadata for the payout transaction."
        },
        "return_url": {
            "type": "string",
            "description": "URL to redirect the customer to after the payout completes (approved, declined, canceled, or error)."
        },
        "options": {
            "type": "object",
            "additionalProperties": true,
            "description": "Provider-specific or payout-type-specific options."
        },
        "customer_ip": {
            "type": "string",
            "nullable": true,
            "description": "Customer's IP address (IPv4 or IPv6). Optional.\n\nIf omitted or empty, the gateway falls back to the IP address of the incoming HTTP request. Provide this field explicitly when the request reaches the gateway through your own backend, so that provider risk checks see the end customer's IP rather than your server's.\n",
            "example": "203.0.113.42"
        }
    },
    "required": [
        "terminal_id",
        "reference",
        "description",
        "currency",
        "amount",
        "beneficiary"
    ]
}

Responses

200 OK422 Unprocessable Content401 Unauthorized

application/json

{
    "result": {
        "id": "PyTxAbCdEfGhIjKlMnOp",
        "merchant_id": "0000000000000fpg-dev",
        "order_id": "ORD_PAYOUT_20260319_001",
        "terminal_id": "TERM001",
        "reference": "PAYOUT-INR-20260319-001",
        "description": "INR payout to beneficiary bank account",
        "currency": "INR",
        "amount": 10000,
        "customer": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com"
        },
        "processing_result": {
            "payment_provider_id": "PP_T365",
            "payment_provider_account_id": "PPACCT_INR001",
            "approval_code": "AUTH789",
            "reference_number": "REF_PAYOUT_001"
        },
        "approved": true,
        "pending": false,
        "channel": "ecommerce",
        "transaction_type": "PAYOUT",
        "status": "APPROVED",
        "payment_method": {
            "method": "****4852",
            "type": "payout_upi",
            "masked": "****4852"
        },
        "normalized_amount": 10000,
        "errors": []
    },
    "action": null,
    "redirect": null,
    "form_submit": null
}

{
    "result": {
        "id": "PyTxPeNdInGhIjKlMnOp",
        "merchant_id": "0000000000000fpg-dev",
        "order_id": "ORD_PAYOUT_20260319_002",
        "terminal_id": "TERM001",
        "reference": "PAYOUT-INR-20260319-002",
        "description": "INR payout to beneficiary",
        "currency": "INR",
        "amount": 50000,
        "customer": {
            "first_name": "Jane",
            "last_name": "Smith",
            "email": "jane.smith@example.com"
        },
        "processing_result": {
            "payment_provider_id": "PP_T365",
            "payment_provider_account_id": "PPACCT_INR001"
        },
        "approved": false,
        "pending": true,
        "channel": "ecommerce",
        "transaction_type": "PAYOUT",
        "status": "PENDING",
        "payment_method": {
            "method": "****7890",
            "type": "payout_upi",
            "masked": "****7890"
        },
        "normalized_amount": 50000,
        "errors": []
    },
    "action": null,
    "redirect": null,
    "form_submit": null
}

{
    "result": {
        "id": "PyTxDcLnEdGhIjKlMnOp",
        "merchant_id": "0000000000000fpg-dev",
        "order_id": "ORD_PAYOUT_20260319_003",
        "terminal_id": "TERM001",
        "reference": "PAYOUT-INR-20260319-003",
        "description": "INR payout declined",
        "currency": "INR",
        "amount": 25000,
        "customer": {
            "first_name": "Alex",
            "last_name": "Johnson",
            "email": "alex.johnson@example.com"
        },
        "processing_result": {
            "payment_provider_id": "PP_T365",
            "payment_provider_account_id": "PPACCT_INR001"
        },
        "approved": false,
        "pending": false,
        "channel": "ecommerce",
        "transaction_type": "PAYOUT",
        "status": "DECLINED",
        "payment_method": {
            "method": "****3456",
            "type": "payout_upi",
            "masked": "****3456"
        },
        "normalized_amount": 25000,
        "errors": []
    },
    "action": null,
    "redirect": null,
    "form_submit": null
}

Schema of the response body

{
    "type": "object",
    "properties": {
        "result": {
            "$ref": "#/components/schemas/ExtendedTransactionDto",
            "description": "Extended transaction details."
        },
        "action": {
            "type": "object",
            "nullable": true,
            "description": "Always null for payout transactions (no 3DS authentication required)."
        },
        "redirect": {
            "type": "object",
            "nullable": true,
            "description": "Always null for payout transactions (no redirect required)."
        },
        "form_submit": {
            "type": "object",
            "nullable": true,
            "description": "Always null for payout transactions (no form submission required)."
        }
    },
    "description": "Response payload for a payout transaction."
}

application/json

{
    "errors": [
        {
            "message": "The size of \"reference\" must be less than or equal to 80. The given size is 100",
            "params": [
                "reference",
                "80",
                "100"
            ],
            "property": "reference"
        }
    ],
    "method": "POST",
    "status": 422
}

Schema of the response body

{
    "type": "object",
    "properties": {
        "errors": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string"
                    },
                    "params": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "property": {
                        "type": "string"
                    }
                }
            }
        },
        "method": {
            "type": "string"
        },
        "status": {
            "type": "integer"
        }
    }
}

application/json

{
    "error": "Unauthorized"
}

Schema of the response body

{
    "type": "object",
    "properties": {
        "error": {
            "type": "string"
        }
    }
}

Schemas¶

BeneficiaryBankAccountData¶

Name	Type	Description
`account_name`	string	Full name of the account holder.
`account_number`	string	Beneficiary bank account number.
`bank_address`	string	Bank address.
`bank_branch`	string	Branch name.
`bank_city`	string	City of the bank branch.
`bank_code`	string	Bank code.
`bank_name`	string	Name of the bank.
`bank_state`	string	State of the bank branch.
`ifsc`	string	IFSC code (Indian Financial System Code). Required for INR payouts. Identifies the bank and branch.
`mobile`	string	Beneficiary mobile number.

BeneficiaryDto¶

Name	Type	Description
`data`	BeneficiaryBankAccountData
`type`	string	Beneficiary type. Determines the expected fields in `data`.

CustomerDto¶

Name	Type	Description
`address`	string \| null
`city`	string \| null
`country`	string \| null
`email`	string \| null
`first_name`	string \| null
`id`	string \| null
`last_name`	string \| null
`phone`	string \| null
`postal_code`	string \| null

ExecuteTransactionResponseDto¶

Name	Type	Description
`action`		Always null for payout transactions (no 3DS authentication required).
`form_submit`		Always null for payout transactions (no form submission required).
`redirect`		Always null for payout transactions (no redirect required).
`result`	ExtendedTransactionDto	Extended transaction details.

ExtendedTransactionDto¶

Name	Type	Description
`amount`	integer(int64)
`approved`	boolean
`channel`	string
`currency`	string
`customer`	CustomerDto
`description`	string
`errors`	Array<>
`id`	string
`merchant_id`	string
`normalized_amount`	integer(int64)
`order_id`	string
`payment_method`	PaymentMethodDataDto
`pending`	boolean
`processing_result`	ProcessingResultDto
`redirect_url`	string \| null
`reference`	string
`status`	TransactionStatus
`terminal_id`	string
`transaction_type`	string

PaymentMethodDataDto¶

Name	Type	Description
`brand`	string \| null
`hash`	string \| null
`masked`	string	Masked account number (last 4 digits visible).
`method`	string	Masked account identifier.
`token`	string \| null
`type`	string	Payment method type (e.g., payout_upi).

PayoutRequestDto¶

Name	Type	Description
`amount`	integer(int64)	Payout amount in minor units (e.g., 10000 = 100.00 INR).
`beneficiary`	BeneficiaryDto
`currency`	string	ISO 4217 currency code (e.g., INR, EUR, USD).
`customer`	CustomerDto
`customer_ip`	string \| null	Customer's IP address (IPv4 or IPv6). Optional. If omitted or empty, the gateway falls back to the IP address of the incoming HTTP request. Provide this field explicitly when the request reaches the gateway through your own backend, so that provider risk checks see the end customer's IP rather than your server's.
`description`	string	Human-readable payout description.
`metadata`		Arbitrary key-value metadata for the payout transaction.
`options`		Provider-specific or payout-type-specific options.
`reference`	string	Unique payout reference per terminal (max 40 chars). Idempotent — if an order for this reference already exists with the same amount and currency, the existing transaction is returned. Different amount/currency will result in a validation error.
`return_url`	string	URL to redirect the customer to after the payout completes (approved, declined, canceled, or error).
`terminal_id`	string	Terminal identifier. The terminal must be configured to support payout transactions.

ProcessingResultDto¶

TransactionStatus¶

Type: string

Security schemes¶

Name	Type	Scheme	Description
bearerAuth	http	bearer