Core Endpoints & Response Examples

A. Create Payment Transaction

Initiates a payment session using an APM method. The response structure depends on the selected flow (H2H vs Redirect).

Endpoint: POST /payments

Request Body Example:

{
  "amount": 2500,            // Amount in minor units (e.g., INR cents)
  "currency": "INR",         // Supported: INR, EGP, MAD, DZD
  "merchant_order_id": "ORD_123456789",
  "customer": {
    "id": "cust_43535",  //unique customer identifier on your side
    "name": "Rahul Sharma",
    "email": "rahul@example.com",
    "phone": "+919876543210"
  },
  "payment_method_type": "UPI_IN",
  "return_url": "https://merchant.com/payment/return", // Required for Redirect Flow, Optional for H2H
  "callback_url": "https://merchant.com/webhook/tradex",
}

Success Response (Host-to-Host - 200 Ok):

{
  "transaction_id": "TXN_TW_893745",
  "merchant_order_id": "ORD_123456789",
  "status": "CREATED", 
  "amount": 2500,
  "currency": "INR",
  "payment_method_type": "UPI_IN",
  "created_at": "2026-03-16T06:00:26Z"
}

Success Response (Redirect Flow - 200 Ok): Used when redirect_url is returned.

{
  "transaction_id": "TXN_TW_893746",
  "merchant_order_id": "ORD_123456789",
  "status": "CREATED", 
  "amount": 2500,
  "currency": "INR",
  "payment_method_type": "UPI_IN",
  "created_at": "2026-03-16T06:00:26Z"
  "redirect_url": "https://pay.tradxworld.com/pay/893746" // Redirect user her
}

B. Clarify Payment (H2H Flow)

Used in Host-to-Host flows to receive additional customers data. Payment flow will be continued after receiving clarify request with requested data.

Status response or webhook notification with clarification fields

{
	"transaction_id": "100251",
	"merchant_order_id": "ORD_22345467946",
	"status": "EXTRA_DATA_NEEDED",
	"amount": 25000,
	"payment_method_type": "UPI_IN",
	"currency": "INR",
	"clarify": [
		"name",
		"phone",
		"account_number",
		"email"
	],
	"created_at": "2026-04-21T09:13:35Z"
}

Endpoint: POST /payments/{transaction_id}/clarify

Request Body Example with additional filed collected from customer:

{
  "clarify_data": {
    "name": "Rahul Sharma",
    "email": "rahul@example.com",
    "phone": "+919876543210",
    "account_number":"34534535@upi"
  }
}

C. Confirm Payment (H2H Flow)

Status response or webhook notification with pay data and confirmation fields

{
	"transaction_id": "100251",
	"merchant_order_id": "ORD_22345467946",
	"status": "PAY_CONFIRMATION_NEEDED",
	"amount": 25000,
	"payment_method_type": "UPI_IN",
	"currency": "INR",
	"pay_data": {
		"receiver_account": "mathan0963321@kvb",
		"available_amounts": [
			25100,
			25200,
			25300,
			25400,
			25500
		]
	},
	"confirm": [
		"amount",
		"utr"
	],
	"created_at": "2026-04-21T09:13:35Z"
}

Used in Host-to-Host flows after the user completes a transfer and presses "I have paid". Collects the Transfer Reference ID for validation.

Endpoint: POST /payments/{transaction_id}/confirm

Request Body Example with additional filed collected from customer:

{
  "confirm_data": {
    "utr":"34534535",
    "amount":"3000"
  }
}

Success Response (200 OK):

{
  "transaction_id": "TXN_TW_893745",
  "merchant_order_id": "ORD_123456789",
  "status": "VERIFYING", 
  "message": "Transfer reference validated. Awaiting final settlement confirmation."
}

D. Get Transaction Status (Payments)

Check the status of a specific transaction. Includes decline reasons for failed transactions.

Endpoint: GET /transactions/{transaction_id} Endpoint: GET /transactions?transaction_id={transaction_id} Endpoint: GET /transactions?merchant_order_id={merchant_order_id}

Success Example (Completed):

{
  "transaction_id": "TXN_TW_893745",
  "merchant_order_id": "ORD_123456789",
  "status": "SUCCESS", 
  "payment_method": "UPI_IN",
  "amount": 2500,
  "amount_paid": 2500,
  "currency": "INR",
  "created_at": "2023-10-27T10:30:00Z",
  "finalized_at": "2023-10-27T10:35:00Z"
}

Failure Example (Declined):

{
  "transaction_id": "TXN_TW_893746",
  "merchant_order_id": "ORD_123456789",
  "status": "FAILED", 
  "payment_method": "UPI_IN",
  "amount": 2500,
  "currency": "INR",
  "created_at": "2023-10-27T10:30:00Z",
  "finalized_at": "2023-10-27T10:32:00Z",
  "decline_reason": "INSUFFICIENT_FUNDS" 
}

E. Merchant Balance Inquiry

Retrieve the current available settlement balance in your merchant wallet.

Endpoint: GET /merchant/balance

Success Response (200 OK):

{
  "merchant_id": 1044,
  "balances": [
    {
      "available": 17500,
      "pending": 0,
      "currency": "INR"
    }
  ],
  "last_updated_at": "2023-10-27T10:32:00Z"
}

F. Initiate Payout

Allows merchants to withdraw funds from their Tradex World wallet to a bank account or local wallet.

Endpoint: POST /payouts

Request Body Example:

{
  "amount": 2500,            // Amount in minor units (e.g., INR cents)
  "currency": "INR",         // Supported: INR, EGP, MAD, DZD
  "merchant_order_id": "ORD_123456789",
  "customer": {
    "id": "cust_43535",  //unique customer identifier on your side
    "name": "Rahul Sharma",
    "email": "rahul@example.com",
    "phone": "+919876543210",
    "account_number": "555@imps",
    "bank_code": "indn0ind",
    "bank_name": "indian",
    "bank_branch": "indn"
  },
  "payment_method_type": "IMPS_IN",
  "callback_url": "https://merchant.com/webhook/tradex"
}

Success Response (201 Created):

{
  "transaction_id": "PAY_TW_554433",
  "merchant_order_id": "ORD_123456789",
  "status": "PROCESSING", 
  "amount": 10000,
  "currency": "INR",
  "created_at": "2023-10-27T10:30:00Z"
}

G. Get Payout Status (Withdrawals)

Retrieve the status of a specific payout request. Includes decline reasons for failed payouts.

Endpoint: GET /payouts/{payout_id}

Success Example (Completed):

{
  "transaction_id": "PAY_TW_554433",
  "merchant_order_id": "ORD_123456789",
  "status": "SUCCESS", 
  "amount": 10000,
  "currency": "INR",
  "created_at": "2023-10-27T10:35:00Z",
  "finalized_at": "2023-10-28T09:00:00Z"
}

Failure Example (Declined):

{
  "transaction_id": "PAY_TW_554434",
  "merchant_order_id": "ORD_123456789",
  "status": "FAILED", 
  "amount": 10000,
  "currency": "INR",
  "created_at": "2023-10-27T10:35:00Z",
  "finalized_at": "2023-10-28T09:00:00Z",
  "decline_reason": "INVALID_ACCOUNT_NUMBER" 
}

---