{
  "openapi": "3.1.0",
  "info": {
    "title": "ZytePe public integration reference",
    "version": "source-contract",
    "description": "14 source-documented public operations. Examples are not complete schemas. Account enablement and deployment behavior require confirmation. Documentation: https://www.zytepe.com/docs",
    "contact": {
      "email": "support@zytepe.com"
    }
  },
  "servers": [
    {
      "url": "https://api.zytepe.com"
    }
  ],
  "paths": {
    "/payments/create": {
      "post": {
        "operationId": "create_hosted_payment",
        "summary": "Create Hosted Payment",
        "description": "Creates a ZytePe hosted checkout session and returns the checkout URL for customer redirect.",
        "tags": [
          "Plugin signed"
        ],
        "security": [
          {
            "PluginKey": [],
            "PluginTimestamp": [],
            "PluginSignature": []
          }
        ],
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Requiredness reviewed against local request schemas and handler-level checks. Examples remain illustrative; this is not a complete validation schema.",
                "required": [
                  "merchant_id",
                  "order_id",
                  "amount",
                  "customer"
                ]
              },
              "example": {
                "merchant_id": "MERCHANT_001",
                "order_id": "ORDER_123",
                "amount": "499.00",
                "currency": "INR",
                "customer": {
                  "name": "Rahul Sharma",
                  "email": "rahul@example.com",
                  "phone": "9876543210"
                },
                "return_url": "https://store.example.com/zytepe/return",
                "callback_url": "https://store.example.com/wp-json/zytepe/v1/webhook",
                "expires_in_minutes": 1440,
                "metadata": {
                  "platform": "woocommerce"
                }
              }
            }
          }
        },
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "payment_id": "pay_123",
                  "checkout_url": "https://pay.zytepe.com/pay_123",
                  "status": "created",
                  "order_id": "ORDER_123",
                  "amount": "499.0000",
                  "currency": "INR"
                }
              }
            }
          }
        },
        "x-doc-slug": "create-hosted-payment",
        "x-auth-family": "plugin",
        "x-source-notes": "- Sign with X-ZytePe-Api-Key, X-ZytePe-Timestamp, and X-ZytePe-Signature.\n- Canonical string is timestamp + \".\" + METHOD + \".\" + PATH + \".\" + raw_body.\n- Redirect the customer to checkout_url and store payment_id on the order.",
        "x-request-fields": [
          {
            "name": "merchant_id",
            "status": "required",
            "description": "Your merchant identifier."
          },
          {
            "name": "order_id",
            "status": "required",
            "description": "Your order reference."
          },
          {
            "name": "amount",
            "status": "required",
            "description": "Payment amount in the documented currency."
          },
          {
            "name": "customer",
            "status": "required",
            "description": "Customer identity details."
          },
          {
            "name": "customer.name",
            "status": "required",
            "description": "Required customer detail."
          },
          {
            "name": "customer.email",
            "status": "required",
            "description": "Required customer detail."
          },
          {
            "name": "customer.phone",
            "status": "required",
            "description": "Required customer detail."
          },
          {
            "name": "currency",
            "status": "optional",
            "description": "Defaults to INR."
          },
          {
            "name": "return_url",
            "status": "optional",
            "description": "Customer return destination. A return is not payment confirmation."
          },
          {
            "name": "callback_url",
            "status": "optional",
            "description": "Payment callback destination."
          },
          {
            "name": "expires_in_minutes",
            "status": "optional",
            "description": "Defaults to 1440 minutes."
          },
          {
            "name": "metadata",
            "status": "optional",
            "description": "Additional order context."
          }
        ],
        "x-field-source": "Reviewed local Pydantic schemas and API handlers. Confirm the deployed API version before launch."
      }
    },
    "/payments/{payment_id}/status": {
      "get": {
        "operationId": "hosted_payment_status",
        "summary": "Hosted Payment Status",
        "description": "Fetches payment status for recovery polling or support checks.",
        "tags": [
          "Plugin signed"
        ],
        "security": [
          {
            "PluginKey": [],
            "PluginTimestamp": [],
            "PluginSignature": []
          }
        ],
        "parameters": [
          {
            "name": "payment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Use the identifier returned by the corresponding creation operation."
          }
        ],
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "payment_id": "pay_123",
                  "status": "paid",
                  "order_id": "ORDER_123",
                  "transaction_id": "txn_123",
                  "provider_reference": "UTR1234567890",
                  "amount": "499.0000",
                  "currency": "INR"
                }
              }
            }
          }
        },
        "x-doc-slug": "hosted-payment-status",
        "x-auth-family": "plugin",
        "x-source-notes": "- Callbacks should remain the source of truth.\n- Use status polling only when a webhook was delayed or support needs confirmation."
      }
    },
    "/payments/balance": {
      "get": {
        "operationId": "merchant_balance",
        "summary": "Merchant Balance",
        "description": "Returns wallet, collection, settlement-lock, and payout-deposit balances for the merchant identified by the signed API key.",
        "tags": [
          "Plugin signed"
        ],
        "security": [
          {
            "PluginKey": [],
            "PluginTimestamp": [],
            "PluginSignature": []
          }
        ],
        "parameters": [],
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "account_id": "merchant-account-uuid",
                  "available_balance": 1000,
                  "locked_balance": 100,
                  "collection_balance": 5000,
                  "collection_locked_balance": 500,
                  "payout_deposit_balance": 2000,
                  "payout_deposit_locked_balance": 200,
                  "pending_settlements": 500,
                  "currency": "INR"
                }
              }
            }
          }
        },
        "x-doc-slug": "merchant-balance",
        "x-auth-family": "plugin",
        "x-source-notes": "- The merchant is resolved from the API key; do not send a merchant_id.\n- Sign the empty GET body using timestamp + \".GET./payments/balance.\".\n- The request is restricted to an active merchant and its approved source IPs."
      }
    },
    "/refunds/create": {
      "post": {
        "operationId": "create_refund",
        "summary": "Create Refund",
        "description": "Creates a full or partial refund against a paid hosted checkout payment.",
        "tags": [
          "Plugin signed"
        ],
        "security": [
          {
            "PluginKey": [],
            "PluginTimestamp": [],
            "PluginSignature": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 16
            },
            "description": "Required by the reviewed refund handler. At least 16 characters; reuse the saved key for the same refund retry."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Requiredness reviewed against local request schemas and handler-level checks. Examples remain illustrative; this is not a complete validation schema.",
                "required": [
                  "merchant_id",
                  "payment_id",
                  "amount"
                ]
              },
              "example": {
                "merchant_id": "MERCHANT_001",
                "payment_id": "pay_123",
                "amount": "100.00",
                "currency": "INR",
                "reason": "Customer requested partial refund",
                "merchant_refund_id": "refund_ORDER_123_1"
              }
            }
          }
        },
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "refund_id": "refund_ORDER_123_1",
                  "payment_id": "pay_123",
                  "status": "completed",
                  "amount": "100.0000",
                  "currency": "INR",
                  "provider_reference": "RFND123456",
                  "merchant_refund_id": "refund_ORDER_123_1"
                }
              }
            }
          }
        },
        "x-doc-slug": "create-refund",
        "x-auth-family": "plugin",
        "x-source-notes": "- Do not refund more than the captured amount.\n- Send Idempotency-Key when retrying refunds so duplicate requests return the original result.",
        "x-request-fields": [
          {
            "name": "merchant_id",
            "status": "required",
            "description": "Your merchant identifier."
          },
          {
            "name": "payment_id",
            "status": "required",
            "description": "The payment identifier returned by checkout creation."
          },
          {
            "name": "amount",
            "status": "required",
            "description": "Payment amount in the documented currency."
          },
          {
            "name": "currency",
            "status": "optional",
            "description": "Defaults to INR."
          },
          {
            "name": "reason",
            "status": "optional",
            "description": "Reason for the refund."
          },
          {
            "name": "merchant_refund_id",
            "status": "optional",
            "description": "Your refund reference. Retain it for tracking."
          }
        ],
        "x-field-source": "Reviewed local Pydantic schemas and API handlers. Confirm the deployed API version before launch."
      }
    },
    "/api/v1/collections/intents/api": {
      "post": {
        "operationId": "create_payment_link",
        "summary": "Create Payment Link",
        "description": "Creates a collection intent and returns the checkout URL/slug for customer payment.",
        "tags": [
          "Merchant HMAC"
        ],
        "security": [
          {
            "MerchantKey": [],
            "MerchantTimestamp": [],
            "MerchantNonce": [],
            "MerchantSignature": []
          }
        ],
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Requiredness reviewed against local request schemas and handler-level checks. Examples remain illustrative; this is not a complete validation schema.",
                "required": [
                  "title",
                  "amount",
                  "external_id",
                  "customer_context"
                ]
              },
              "example": {
                "title": "Invoice INV-2042",
                "description": "April subscription renewal",
                "usage_limit": 1,
                "amount": 2500,
                "min_limit": 1,
                "max_limit": 50000,
                "currency": "INR",
                "expiry_days": 7,
                "external_id": "INV-2042",
                "notify_url": "https://merchant.example.com/hooks/collection-link",
                "customer_context": {
                  "full_name": "Rahul Sharma",
                  "email_address": "rahul@example.com",
                  "phone_number": "9876543210",
                  "dial_code": "+91"
                },
                "tags": {
                  "source": "merchant-api",
                  "channel": "web"
                }
              }
            }
          }
        },
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "message": "Payment link created via API.",
                  "data": {
                    "id": "49c2ebf2-f651-473e-ab78-6c154665df92",
                    "short_id": "s0oJRkuT6OY",
                    "title": "Invoice INV-2042",
                    "description": "April subscription renewal",
                    "fixed_amount": "2500.0000",
                    "min_limit": "1.0000",
                    "max_limit": null,
                    "currency": "INR",
                    "usage_limit": 1,
                    "current_usage_count": 0,
                    "status": "active",
                    "is_active": true,
                    "expires_at": "2026-05-10T10:30:00Z",
                    "checkout_url": "https://pay.zytepe.com/s0oJRkuT6OY"
                  }
                }
              }
            }
          }
        },
        "x-doc-slug": "create-payment-link",
        "x-auth-family": "hmac",
        "x-source-notes": "- Use notify_url when a single link needs its own callback destination. The merchant profile notify URLs remain the account-level defaults.\n- The returned short_id is the slug used by the checkout flow and the public link-status endpoint.\n**Observed test condition:** This specific merchant received HTTP 400 with `CCAvenue PSP MID is not assigned to this merchant.` despite passing authentication. PSP mapping/merchant enablement must be verified; do not imply a sandbox exists. The sample request sets `max_limit` but the sample response has `max_limit: null`; confirm actual field semantics before writing parameter rules.",
        "x-request-fields": [
          {
            "name": "title",
            "status": "required",
            "description": "Checkout title."
          },
          {
            "name": "amount",
            "status": "required",
            "description": "Payment amount in the documented currency."
          },
          {
            "name": "external_id",
            "status": "required",
            "description": "Your order or invoice reference; required by the API checkout handler."
          },
          {
            "name": "customer_context",
            "status": "required",
            "description": "Customer identity; required by the API checkout handler."
          },
          {
            "name": "customer_context.full_name",
            "status": "required",
            "description": "Required customer detail."
          },
          {
            "name": "customer_context.email_address",
            "status": "required",
            "description": "Required customer detail."
          },
          {
            "name": "customer_context.phone_number",
            "status": "required",
            "description": "Required customer detail."
          },
          {
            "name": "description",
            "status": "optional",
            "description": "Additional checkout description."
          },
          {
            "name": "usage_limit",
            "status": "optional",
            "description": "Defaults to 1."
          },
          {
            "name": "min_limit",
            "status": "optional",
            "description": "Defaults to 1.0000."
          },
          {
            "name": "max_limit",
            "status": "optional",
            "description": "Upper amount limit; source examples do not establish its effect on a fixed-amount checkout."
          },
          {
            "name": "currency",
            "status": "optional",
            "description": "Defaults to INR."
          },
          {
            "name": "expiry_days",
            "status": "optional",
            "description": "Defaults to 7 days."
          },
          {
            "name": "customer_context.dial_code",
            "status": "optional",
            "description": "Defaults to +91."
          },
          {
            "name": "notify_url",
            "status": "optional",
            "description": "Link-specific callback destination."
          },
          {
            "name": "tags",
            "status": "optional",
            "description": "Additional business context."
          }
        ],
        "x-field-source": "Reviewed local Pydantic schemas and API handlers. Confirm the deployed API version before launch."
      }
    },
    "/api/v1/collections/intents/{short_id}/status": {
      "get": {
        "operationId": "public_payment_link_status",
        "summary": "Public Payment Link Status",
        "description": "Checks the latest checkout/link status after the customer starts payment.",
        "tags": [
          "Public checkout"
        ],
        "security": [],
        "parameters": [
          {
            "name": "short_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Use the identifier returned by the corresponding creation operation."
          }
        ],
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "message": "Payment link status retrieved.",
                  "data": {
                    "status": "SUCCESS",
                    "short_id": "s0oJRkuT6OY",
                    "transaction_id": "ca9a58aa-d578-4fc2-a9f4-fb8d090d4b5f",
                    "current_usage_count": 1,
                    "usage_limit": 1,
                    "is_active": false
                  }
                }
              }
            }
          }
        },
        "x-doc-slug": "public-payment-link-status",
        "x-auth-family": "public",
        "x-source-notes": "- This is helpful for the browser checkout experience.\n- For server-to-server reconciliation, merchant notify URLs are the primary source of truth for inbound status updates."
      }
    },
    "/api/v1/collections/checkout/{short_id}": {
      "get": {
        "operationId": "checkout_link_details",
        "summary": "Checkout Link Details",
        "description": "Loads a saved payment link by short id for dashboard-side review and support workflows.",
        "tags": [
          "Public checkout"
        ],
        "security": [],
        "parameters": [
          {
            "name": "short_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Use the identifier returned by the corresponding creation operation."
          }
        ],
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "data": {
                    "id": "49c2ebf2-f651-473e-ab78-6c154665df92",
                    "short_id": "s0oJRkuT6OY",
                    "title": "Invoice INV-2042",
                    "fixed_amount": "2500.0000",
                    "currency": "INR",
                    "status": "active"
                  }
                }
              }
            }
          }
        },
        "x-doc-slug": "checkout-link-details",
        "x-auth-family": "public",
        "x-source-notes": "- This public endpoint is used by hosted checkout and support flows to load safe link metadata.\n- Customers should use the hosted checkout URL returned by the create intent call."
      }
    },
    "/api/v1/payees/external/create": {
      "post": {
        "operationId": "create_payee",
        "summary": "Create Payee",
        "description": "Registers a payout recipient in the merchant payee vault.",
        "tags": [
          "Merchant HMAC"
        ],
        "security": [
          {
            "MerchantKey": [],
            "MerchantTimestamp": [],
            "MerchantNonce": [],
            "MerchantSignature": []
          }
        ],
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Requiredness reviewed against local request schemas and handler-level checks. Examples remain illustrative; this is not a complete validation schema.",
                "required": [
                  "legal_name"
                ]
              },
              "example": {
                "legal_name": "Aditi Traders",
                "email_address": "ops@example.com",
                "phone_number": "9876543210",
                "bank_account_no": "123456789012",
                "routing_id": "HDFC0001234",
                "bank_name": "HDFC Bank",
                "vpa": "aditi.traders@okhdfcbank",
                "category": "business",
                "external_ref": "BENEFICIARY-42"
              }
            }
          }
        },
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "message": "Payee created.",
                  "data": {
                    "id": "d965aa45-1952-4749-aa52-2bed21470ffd",
                    "legal_name": "Aditi Traders",
                    "email_address": "ops@example.com",
                    "phone_number": "9876543210",
                    "bank_account_no": "123456789012",
                    "routing_id": "HDFC0001234",
                    "vpa_address": "aditi.traders@okhdfcbank",
                    "status": "active",
                    "compliance_status": "pending",
                    "created_at": "2026-05-03T10:30:00Z"
                  }
                }
              }
            }
          }
        },
        "x-doc-slug": "create-payee",
        "x-auth-family": "hmac",
        "x-source-notes": "- The same merchant cannot register the same bank account twice.\n- Bank-mode payouts need bank_account_no + routing_id. UPI payouts need vpa.",
        "x-request-fields": [
          {
            "name": "legal_name",
            "status": "required",
            "description": "Recipient legal name."
          },
          {
            "name": "email_address",
            "status": "optional",
            "description": "Recipient email."
          },
          {
            "name": "phone_number",
            "status": "optional",
            "description": "Recipient contact number."
          },
          {
            "name": "bank_name",
            "status": "optional",
            "description": "Bank display name."
          },
          {
            "name": "category",
            "status": "optional",
            "description": "Defaults to individual."
          },
          {
            "name": "external_ref",
            "status": "optional",
            "description": "Your beneficiary reference."
          },
          {
            "name": "bank_account_no",
            "status": "conditional",
            "description": "Required for bank-mode payouts; optional when creating a UPI-only payee."
          },
          {
            "name": "routing_id",
            "status": "conditional",
            "description": "Required with bank details for bank-mode payouts."
          },
          {
            "name": "vpa",
            "status": "conditional",
            "description": "Required for UPI payouts; optional for bank-only recipients."
          }
        ],
        "x-field-source": "Reviewed local Pydantic schemas and API handlers. Confirm the deployed API version before launch."
      }
    },
    "/api/v1/payees/external/list": {
      "get": {
        "operationId": "list_payees",
        "summary": "List Payees",
        "description": "Fetches payees already stored for the merchant backend.",
        "tags": [
          "Merchant HMAC"
        ],
        "security": [
          {
            "MerchantKey": [],
            "MerchantTimestamp": [],
            "MerchantNonce": [],
            "MerchantSignature": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 200
            },
            "example": 50,
            "description": "Optional pagination value. Defaults to 50; supported range 1–200.",
            "required": false
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "example": 0,
            "description": "Optional pagination value. Defaults to 0; must be non-negative.",
            "required": false
          }
        ],
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "data": {
                    "payees": [
                      {
                        "id": "d965aa45-1952-4749-aa52-2bed21470ffd",
                        "legal_name": "Aditi Traders",
                        "email_address": "ops@example.com",
                        "phone_number": "9876543210",
                        "bank_account_no": "123456789012",
                        "routing_id": "HDFC0001234",
                        "vpa_address": "aditi.traders@okhdfcbank",
                        "status": "active",
                        "compliance_status": "verified",
                        "created_at": "2026-05-03T10:30:00Z"
                      }
                    ],
                    "total_count": 1
                  }
                }
              }
            }
          }
        },
        "x-doc-slug": "list-payees",
        "x-auth-family": "hmac",
        "x-source-notes": "- Use this to map your own beneficiary identifiers to ZytePe payee ids before a payout call.\n**Path/query rule:** The portion after `?` is a query string, not part of the URL path. When generating OpenAPI, represent `limit` and `offset` as query parameters."
      }
    },
    "/api/v1/payees/external/{payee_id}/verify/bank": {
      "post": {
        "operationId": "verify_payee_bank_account",
        "summary": "Verify Payee Bank Account",
        "description": "Runs payee bank verification before IMPS/NEFT/RTGS payouts.",
        "tags": [
          "Merchant HMAC"
        ],
        "security": [
          {
            "MerchantKey": [],
            "MerchantTimestamp": [],
            "MerchantNonce": [],
            "MerchantSignature": []
          }
        ],
        "parameters": [
          {
            "name": "payee_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Use the identifier returned by the corresponding creation operation."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Illustrative fields only; requiredness and validation constraints are not exhaustively specified."
              },
              "example": {}
            }
          }
        },
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "message": "Bank verification processed.",
                  "data": {
                    "status": "verified",
                    "name_at_bank": "Aditi Traders"
                  }
                }
              }
            }
          }
        },
        "x-doc-slug": "verify-payee-bank-account",
        "x-auth-family": "hmac",
        "x-source-notes": "- Required when the payout method is IMPS, NEFT, or RTGS.\n**Observed test condition:** A dummy TEST-prefixed IFSC/account returned `status: verified` for this merchant. Do not construe that as proof a real bank verified that account; identify mocks/test fixtures or provider behavior in code before describing verification guarantees."
      }
    },
    "/api/v1/payees/external/{payee_id}/verify/vpa": {
      "post": {
        "operationId": "verify_payee_upi_id",
        "summary": "Verify Payee UPI ID",
        "description": "Verifies a saved UPI payee before a UPI payout.",
        "tags": [
          "Merchant HMAC"
        ],
        "security": [
          {
            "MerchantKey": [],
            "MerchantTimestamp": [],
            "MerchantNonce": [],
            "MerchantSignature": []
          }
        ],
        "parameters": [
          {
            "name": "payee_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Use the identifier returned by the corresponding creation operation."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Illustrative fields only; requiredness and validation constraints are not exhaustively specified."
              },
              "example": {}
            }
          }
        },
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "message": "UPI payee verification processed.",
                  "data": {
                    "status": "verified",
                    "name_at_vpa": "Aditi Traders",
                    "vpa": "aditi.traders@okhdfcbank"
                  }
                }
              }
            }
          }
        },
        "x-doc-slug": "verify-payee-upi-id",
        "x-auth-family": "hmac",
        "x-source-notes": "- Required when the payout method is UPI."
      }
    },
    "/api/v1/payouts/external/initiate": {
      "post": {
        "operationId": "initiate_payout",
        "summary": "Initiate Payout",
        "description": "Creates a payout/disbursement request from the merchant wallet or payout deposit balance.",
        "tags": [
          "Merchant HMAC"
        ],
        "security": [
          {
            "MerchantKey": [],
            "MerchantTimestamp": [],
            "MerchantNonce": [],
            "MerchantSignature": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 16
            },
            "description": "Required. Reuse the same key for retries of the same payout."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Requiredness reviewed against local request schemas and handler-level checks. Examples remain illustrative; this is not a complete validation schema.",
                "required": [
                  "payee_id",
                  "amount",
                  "external_ref"
                ]
              },
              "example": {
                "payee_id": "d965aa45-1952-4749-aa52-2bed21470ffd",
                "amount": 1500,
                "currency": "INR",
                "external_ref": "PAYOUT-2026-00041",
                "payout_method": "IMPS",
                "purpose": "Vendor settlement",
                "custom_notes": {
                  "invoice_no": "INV-882",
                  "batch": "MAY-SETTLEMENT"
                }
              }
            }
          }
        },
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "message": "Payout initiated successfully.",
                  "data": {
                    "message": "Payout initiated successfully.",
                    "transaction_id": "ca9a58aa-d578-4fc2-a9f4-fb8d090d4b5f",
                    "status": "processing"
                  }
                }
              }
            }
          }
        },
        "x-doc-slug": "initiate-payout",
        "x-auth-family": "hmac",
        "x-source-notes": "- Idempotency-Key must be at least 16 characters long.\n- If the same Idempotency-Key is replayed for the same merchant, ZytePe returns the original payout transaction instead of creating a new one.",
        "x-request-fields": [
          {
            "name": "payee_id",
            "status": "required",
            "description": "The saved and verified payee identifier."
          },
          {
            "name": "amount",
            "status": "required",
            "description": "Payment amount in the documented currency."
          },
          {
            "name": "external_ref",
            "status": "required",
            "description": "Your unique business payout reference."
          },
          {
            "name": "currency",
            "status": "optional",
            "description": "Defaults to INR."
          },
          {
            "name": "payout_method",
            "status": "optional",
            "description": "Defaults to IMPS. Verify the payee for your chosen method."
          },
          {
            "name": "purpose",
            "status": "optional",
            "description": "Business reason for the payout."
          },
          {
            "name": "custom_notes",
            "status": "optional",
            "description": "Additional business context."
          }
        ],
        "x-field-source": "Reviewed local Pydantic schemas and API handlers. Confirm the deployed API version before launch."
      }
    },
    "/api/v1/payouts/external/status/{transaction_id}": {
      "get": {
        "operationId": "external_payout_status",
        "summary": "External Payout Status",
        "description": "Retrieves payout/disbursement status for merchant backend recovery polling.",
        "tags": [
          "Merchant HMAC"
        ],
        "security": [
          {
            "MerchantKey": [],
            "MerchantTimestamp": [],
            "MerchantNonce": [],
            "MerchantSignature": []
          }
        ],
        "parameters": [
          {
            "name": "transaction_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Use the identifier returned by the corresponding creation operation."
          }
        ],
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "message": "Payout status retrieved from ZytePe ledger.",
                  "data": {
                    "id": "ca9a58aa-d578-4fc2-a9f4-fb8d090d4b5f",
                    "external_ref": "PAYOUT-2026-00041",
                    "gateway_ref": "BANKREF98344210",
                    "amount_gross": "1500.0000",
                    "amount_fees": "15.0000",
                    "amount_net": "1485.0000",
                    "currency": "INR",
                    "category": "DISBURSEMENT",
                    "method": "IMPS",
                    "status": "COMPLETED",
                    "payee_id": "d965aa45-1952-4749-aa52-2bed21470ffd",
                    "payee_name": "Aditi Traders",
                    "failure_reason": null,
                    "created_at": "2026-05-03T10:42:10.110Z",
                    "updated_at": "2026-05-03T10:43:18.240Z"
                  }
                }
              }
            }
          }
        },
        "x-doc-slug": "external-payout-status",
        "x-auth-family": "hmac",
        "x-source-notes": "- Use this only when a callback was missed or your backend needs final-state confirmation.\n- The transaction_id is returned by Initiate Payout and also appears in outbound callbacks."
      }
    },
    "/api/v1/transactions/external/status/{transaction_id}": {
      "get": {
        "operationId": "external_transaction_status",
        "summary": "External Transaction Status",
        "description": "Fetches a single ledger transaction owned by the merchant backend.",
        "tags": [
          "Merchant HMAC"
        ],
        "security": [
          {
            "MerchantKey": [],
            "MerchantTimestamp": [],
            "MerchantNonce": [],
            "MerchantSignature": []
          }
        ],
        "parameters": [
          {
            "name": "transaction_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Use the identifier returned by the corresponding creation operation."
          }
        ],
        "responses": {
          "default": {
            "description": "Source-documented response example. The source does not establish a complete HTTP status/error contract.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "message": "Transaction status retrieved from ZytePe ledger.",
                  "data": {
                    "id": "ca9a58aa-d578-4fc2-a9f4-fb8d090d4b5f",
                    "internal_ref": "ZY-INT-2042-AX19",
                    "external_ref": "PAYOUT-2026-00041",
                    "gateway_ref": "BANKREF98344210",
                    "amount_gross": "1500.0000",
                    "amount_fees": "15.0000",
                    "amount_net": "1485.0000",
                    "currency": "INR",
                    "category": "DISBURSEMENT",
                    "method": "IMPS",
                    "status": "COMPLETED",
                    "payee_id": "d965aa45-1952-4749-aa52-2bed21470ffd",
                    "payee_name": "Aditi Traders",
                    "failure_reason": null,
                    "created_at": "2026-05-03T10:42:10.110Z",
                    "updated_at": "2026-05-03T10:43:18.240Z"
                  }
                }
              }
            }
          }
        },
        "x-doc-slug": "external-transaction-status",
        "x-auth-family": "hmac",
        "x-source-notes": "- This is the HMAC endpoint merchants should use for server-to-server recovery polling.\n- For payout-only flows, /api/v1/payouts/external/status/{transaction_id} returns the same ledger state with payout wording."
      }
    }
  },
  "components": {
    "securitySchemes": {
      "MerchantKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY-ID",
        "description": "Part of the combined signed-header authentication scheme. See https://www.zytepe.com/docs/get-started/authentication."
      },
      "MerchantTimestamp": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-TIMESTAMP",
        "description": "Part of the combined signed-header authentication scheme. See https://www.zytepe.com/docs/get-started/authentication."
      },
      "MerchantNonce": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-NONCE",
        "description": "Part of the combined signed-header authentication scheme. See https://www.zytepe.com/docs/get-started/authentication."
      },
      "MerchantSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-SIGNATURE",
        "description": "Part of the combined signed-header authentication scheme. See https://www.zytepe.com/docs/get-started/authentication."
      },
      "PluginKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-ZytePe-Api-Key",
        "description": "Part of the combined signed-header authentication scheme. See https://www.zytepe.com/docs/get-started/authentication."
      },
      "PluginTimestamp": {
        "type": "apiKey",
        "in": "header",
        "name": "X-ZytePe-Timestamp",
        "description": "Part of the combined signed-header authentication scheme. See https://www.zytepe.com/docs/get-started/authentication."
      },
      "PluginSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-ZytePe-Signature",
        "description": "Part of the combined signed-header authentication scheme. See https://www.zytepe.com/docs/get-started/authentication."
      }
    }
  }
}