DEVELOPER REFERENCE

ZTake Payment Gateway API Docs

Integrate UPI payment confirmation flows, track order statuses, manage payout distributions, and customize your site-support chatbot.

BASE URL:https://ztake.in

Overview

Welcome to the ZTake API portal. The endpoints described in this guide allow automated system interfaces to update records of bank transaction events, verify instant check-outs, process settlements, and control chatbot configurations.

Our infrastructure is built for high speed and transaction stability, supporting instant merchant QR notifications, webhook status delivery, and AI chatbot modules.

Authentication

The ZTake API verifies requests using Bearer tokens supplied in standard HTTP Authorization headers.

Vendor JWT Token

Obtained by calling `POST /api/auth/login`. This temporary token authenticates frontend vendor operations and dashboard lookups. It must be provided in the header as:

Authorization: Bearer jwt_token_string

Secret API Key (Permanent)

Found inside your dashboard Settings under the API Keys/Credential tab. Secret keys begin with the prefix `pk_`. Use this key for permanent backend services or server-to-server bot integrations.

Authorization: Bearer pk_live_xxxxx

Payments API

POST/api/payments/update

Auth: Bearer pk_key

Update/mark a payment as completed using the transaction UTR. Requires vendor secret key (pk_).

Request Body Properties

Property	Type	Requirement	Description
utr	string	required	12-digit bank reference transaction ID (UTR)
amount	number	required	Transaction amount in INR
vendor_code	string	required	6-character vendor code (e.g., AB1234)

Example Payload

{
  "utr": "652603702065",
  "amount": 500,
  "vendor_code": "ZV1001"
}

Example Response

{
  "success": true,
  "message": "Payment verified and updated successfully",
  "payment": {
    "id": 104,
    "utr": "652603702065",
    "amount": 500,
    "status": "completed",
    "payment_status": "Succeeded"
  }
}

POST/api/payments/check

Auth: Public

Verify payment completion status based on UTR. Publicly accessible endpoint.

Request Body Properties

Property	Type	Requirement	Description
utr	string	required	12-digit transaction UTR to search

Example Payload

{
  "utr": "652603702065"
}

Example Response

{
  "success": true,
  "status": "Succeeded",
  "amount": 500,
  "checked_at": "2026-05-22T20:10:00Z"
}

GET/api/vendor/payment-info

Auth: Vendor JWT

Get the registered payment profile details, active business UPI ID, and payment QR code dynamic components for the active vendor.

Example Response

{
  "success": true,
  "business_name": "TechMart India",
  "upi_id": "techmart@ybl",
  "vendor_code": "ZV1001"
}

GET/api/vendor/payments

Auth: Vendor JWT

List recent transactions with filtering and pagination parameters. Authenticated using JWT token.

Query Parameters

Param	Type	Requirement	Description
page	number	optional	Page number for list (default: 1)
limit	number	optional	Number of rows per page (default: 10)

Example Response

{
  "success": true,
  "payments": [
    {
      "id": 10,
      "utr": "652603702065",
      "amount": 500,
      "status": "completed",
      "created_at": "2026-05-22T19:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10
  }
}

POST/api/v1/orders/:orderId/submit-utr

Auth: Public

Submit payment proof (UTR reference) for a specific order generated by the system. Publicly accessible endpoint.

Request Body Properties

Property	Type	Requirement	Description
utr	string	required	12-digit payment transaction UTR

Example Payload

{
  "utr": "652603702065"
}

Example Response

{
  "success": true,
  "message": "UTR submitted and pending confirmation",
  "order": {
    "id": "ord_9182398129",
    "amount": 500,
    "status": "Pending",
    "utr": "652603702065"
  }
}

Orders API

POST/api/v1/orders

Auth: Bearer pk_key

Generate a new payment/checkout order for a customer. Returns a unique paymentUrl redirecting the user to the secure checkout page.

Request Body Properties

Property	Type	Requirement	Description
merchantOrderId	string	required	Unique tracking ID from your merchant app
amount	number	required	Order transaction amount in INR
currency	string	required	Standard ISO currency code (INR)
customerName	string	required	Name of the customer paying for the order
returnUrl	string	required	Redirect URL after payment verification
callbackUrl	string	required	Webhook destination URL to receive status notifications
vendorCode	string	required	Your 6-character vendor code (e.g. ZV1001)

Example Payload

{
  "merchantOrderId": "merchant_3289138",
  "amount": 500,
  "currency": "INR",
  "customerName": "Aravind Kumar",
  "returnUrl": "https://myshop.com/payment-result",
  "callbackUrl": "https://api.myshop.com/webhooks/payments",
  "vendorCode": "ZV1001"
}

Example Response

{
  "status": "success",
  "merchantOrderId": "merchant_3289138",
  "ztakeOrderId": "ZTK9182398129",
  "paymentUrl": "https://pay.ztake.in/orders/ZTK9182398129",
  "vendorCode": "ZV1001",
  "authMethod": "api_key_vendor_code"
}

GET/api/v1/orders/:orderId

Auth: Public

Fetch the real-time status of a checkout order generated by the system.

Example Response

{
  "success": true,
  "order": {
    "order_id": "ord_9182398129",
    "merchant_order_id": "merchant_3289138",
    "amount": 500,
    "currency": "INR",
    "status": "Succeeded",
    "customer_name": "Aravind Kumar",
    "payment_time": "2026-05-22T20:10:00Z"
  }
}

Payouts API

GET/api/vendor/payouts

Auth: Vendor JWT

Retrieve a list of processed payouts and current status for the active vendor. Authenticated using JWT token.

Example Response

{
  "success": true,
  "payouts": [
    {
      "id": 42,
      "amount": 15000,
      "status": "completed",
      "beneficiary_name": "Subash Chandra",
      "reference_id": "ref_238913981",
      "utr": "652813098132",
      "created_at": "2026-05-22T15:00:00Z"
    }
  ]
}

ZiBot Chatbot API

POST/api/v2/chat/message

Auth: Bearer pk_key

Send a prompt or support question to your custom ZiBot instance. Integrates Claude API internally.

Request Body Properties

Property	Type	Requirement	Description
message	string	required	The text prompt to submit to ZiBot
session_id	string	optional	Existing session ID to continue discussion thread context

Example Payload

{
  "message": "Where is my order status?",
  "session_id": "sess_1716382910_a2d8s9"
}

Example Response

{
  "success": true,
  "reply": "I checked your details. The payment of Rs. 500 for order tech_3289138 has succeeded. Please reload your merchant portal.",
  "session_id": "sess_1716382910_a2d8s9",
  "bot_name": "ZiBot"
}

GET/api/v2/chat/history

Auth: Bearer pk_key

Fetch chat log details for a session thread using its unique session ID.

Query Parameters

Param	Type	Requirement	Description
session_id	string	required	The session identifier to retrieve

Example Response

{
  "success": true,
  "session_id": "sess_1716382910_a2d8s9",
  "messages": [
    {
      "role": "user",
      "content": "Where is my order status?"
    },
    {
      "role": "assistant",
      "content": "I checked your details. The payment of Rs. 500 for order tech_3289138 has succeeded."
    }
  ],
  "created_at": "2026-05-22T19:00:00Z",
  "updated_at": "2026-05-22T19:02:00Z"
}

GET/api/v2/chat/config

Auth: Bearer pk_key

Fetch the active support bot customizations for the vendor.

Example Response

{
  "success": true,
  "config": {
    "system_prompt": "You are a helpful payment support assistant. Answer questions about payment status.",
    "bot_name": "ZiBot",
    "is_active": true
  }
}

PUT/api/v2/chat/config

Auth: Bearer pk_key

Update support chatbot configurations like names and customized system prompts.

Request Body Properties

Property	Type	Requirement	Description
system_prompt	string	optional	Base context directives for chatbot response styles
bot_name	string	optional	Name of the support chatbot
is_active	boolean	optional	Enable/disable chatbot instance

Example Payload

{
  "system_prompt": "You are custom support bot. Answer questions about UPI payments.",
  "bot_name": "PayHelp",
  "is_active": true
}

Example Response

{
  "success": true,
  "message": "ZiBot config updated"
}

Error Codes

Standard REST API HTTP response statuses returned on process outcomes:

Status Code	Error Name	Typical Reason
400	Bad Request	Missing parameters, invalid types, or request content limit errors.
401	Unauthorized	Bearer token is missing, invalid, or belongs to a disabled account.
403	Forbidden	Resource permissions prevent active user context from accessing.
404	Not Found	Requested resource, payment UTR, or session context key does not exist.
429	Too Many Requests	Rate limits exceeded. Reduce invocation frequencies.
500	Internal Server Error	An unexpected malfunction occurred within payment platform routines.

Interactive API Playground

Test gateway requests live inside your browser