openapi: 3.0.3
info:
  title: Juspay Express Checkout API
  description: >-
    Server-to-server REST API for the Juspay payments orchestration and checkout
    platform. Merchants create and track orders, process transactions across
    payment methods (cards, UPI, netbanking, wallets), issue refunds, manage
    customers, and initialize the Hyper Checkout / HyperSDK drop-in checkout via
    a payment session. Requests authenticate with an API key over HTTP Basic
    (API key as the username, empty password) plus an `x-merchantid` header;
    Juspay recommends passing an `x-routing-id` (typically the customer id) to
    pin the payment session lifecycle. Most write endpoints accept
    `application/x-www-form-urlencoded` bodies.

    Endpoint paths and methods below are grounded in Juspay's public Express
    Checkout / Hyper Checkout documentation as of 2026-07-12. Request and
    response schemas are modeled from the documented parameters and are marked
    where fields are illustrative rather than exhaustive; verify against the
    live reference before production use.
  version: '1.0'
  contact:
    name: Juspay
    url: https://juspay.io/in
servers:
  - url: https://api.juspay.in
    description: Production
  - url: https://sandbox.juspay.in
    description: Sandbox
security:
  - basicAuth: []
tags:
  - name: Orders
    description: Create orders and read order status.
  - name: Transactions
    description: Server-to-server transaction processing against an order.
  - name: Session
    description: Create a payment session for the Hyper Checkout / HyperSDK.
  - name: Refunds
    description: Refund a charged order.
  - name: Customers
    description: Create and retrieve customers.
paths:
  /orders:
    post:
      operationId: createOrder
      tags:
        - Orders
      summary: Create an order
      description: >-
        Creates an order, the unit a payment is attached to. Returns an order
        reference (and, when requested via options.get_client_auth_token, a
        client auth token for SDK use).
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/RoutingId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateOrderInput'
      responses:
        '200':
          description: The created order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{order_id}:
    parameters:
      - $ref: '#/components/parameters/OrderId'
    get:
      operationId: getOrderStatus
      tags:
        - Orders
      summary: Get order status
      description: >-
        Retrieves the status and details of an order by its id. A transaction is
        successful only when `status` is CHARGED.
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/RoutingId'
      responses:
        '200':
          description: The order and its current status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v4/order-status:
    post:
      operationId: getOrderStatusV4
      tags:
        - Orders
      summary: Get order status (encrypted V4)
      description: >-
        Encrypted (JWE/JWT) variant of order status. Accepts an encrypted
        payload as a request body (POST) or query parameter (GET) and returns
        the order status. Modeled from documentation; encrypted payload schema
        not expanded here.
      parameters:
        - $ref: '#/components/parameters/MerchantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The order status (encrypted response envelope).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /txns:
    post:
      operationId: createTransaction
      tags:
        - Transactions
      summary: Create a transaction
      description: >-
        Server-to-server transaction endpoint that processes a payment against
        an existing order with a chosen payment method (card, UPI, netbanking,
        wallet). Documented as exempt from the standard order authentication
        flow. Body fields below are modeled from the documented flow and are not
        exhaustive.
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/RoutingId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TransactionInput'
      responses:
        '200':
          description: Transaction result / next action.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /session:
    post:
      operationId: createSession
      tags:
        - Session
      summary: Create a payment session
      description: >-
        Creates a payment session for the Hyper Checkout / HyperSDK. Accepts
        order parameters and returns an SDK payload and payment links used to
        initialize the drop-in checkout on web or mobile.
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/RoutingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionInput'
      responses:
        '200':
          description: SDK payload and payment links for the session.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{order_id}/refunds:
    parameters:
      - $ref: '#/components/parameters/OrderId'
    post:
      operationId: createRefund
      tags:
        - Refunds
      summary: Refund an order
      description: >-
        Creates a refund for a CHARGED order. `unique_request_id` must be unique
        per refund request and `amount` must not exceed the refundable balance.
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/RoutingId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RefundInput'
      responses:
        '200':
          description: The order with the refund appended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Refund not eligible (e.g. INSTANT with no payment source).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers:
    post:
      operationId: createCustomer
      tags:
        - Customers
      summary: Create a customer
      description: >-
        Creates a customer. `customer_id` should be at least 8 characters and
        unique (typically an email, mobile number, or internal id). Can return a
        15-minute client auth token for client-side SDK authentication.
      parameters:
        - $ref: '#/components/parameters/MerchantId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: The created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{customer_id}:
    parameters:
      - name: customer_id
        in: path
        required: true
        description: The merchant's unique customer identifier.
        schema:
          type: string
    get:
      operationId: getCustomer
      tags:
        - Customers
      summary: Get a customer
      description: Retrieves a customer by id. Can also return a client auth token.
      parameters:
        - $ref: '#/components/parameters/MerchantId'
      responses:
        '200':
          description: The requested customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication. The API key is the username and the password
        is an empty string; the pair is Base64-encoded into
        `Authorization: Basic <credentials>`. An `x-merchantid` header is also
        required on requests.
  parameters:
    MerchantId:
      name: x-merchantid
      in: header
      required: true
      description: Merchant ID issued by Juspay.
      schema:
        type: string
    RoutingId:
      name: x-routing-id
      in: header
      required: false
      description: >-
        Routing key that pins the payment session lifecycle - typically the
        customer_id, or an order/cart id for guest checkout.
      schema:
        type: string
    OrderId:
      name: order_id
      in: path
      required: true
      description: Unique alphanumeric order identifier (up to 21 characters).
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        status:
          type: string
        error_code:
          type: string
        error_message:
          type: string
    CreateOrderInput:
      type: object
      required:
        - order_id
        - amount
      properties:
        order_id:
          type: string
          description: Unique alphanumeric identifier, under 21 characters.
        amount:
          type: number
          format: double
          description: Payment amount with up to two decimal places.
        currency:
          type: string
          default: INR
          description: ISO currency code.
        customer_id:
          type: string
          description: Merchant's customer identifier (empty string for guests).
        customer_email:
          type: string
        customer_phone:
          type: string
        description:
          type: string
        return_url:
          type: string
          format: uri
        product_id:
          type: string
        gateway_id:
          type: integer
        metadata:
          type: object
          additionalProperties: true
        options.get_client_auth_token:
          type: boolean
          description: Request a client auth token for SDK use.
    Order:
      type: object
      properties:
        order_id:
          type: string
        status:
          type: string
          description: Order status; CHARGED indicates a successful payment.
          enum:
            - NEW
            - PENDING_VBV
            - AUTHORIZING
            - CHARGED
            - AUTHENTICATION_FAILED
            - AUTHORIZATION_FAILED
            - JUSPAY_DECLINED
            - REFUNDED
            - PARTIAL_REFUNDED
        amount:
          type: number
          format: double
        currency:
          type: string
        payment_links:
          type: object
          additionalProperties: true
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
    TransactionInput:
      type: object
      required:
        - order_id
        - payment_method_type
      properties:
        order_id:
          type: string
        payment_method_type:
          type: string
          description: e.g. CARD, UPI, NB (netbanking), WALLET.
        payment_method:
          type: string
        redirect_after_payment:
          type: boolean
        format:
          type: string
          description: Response format, e.g. json.
    SessionInput:
      type: object
      required:
        - order_id
        - amount
        - customer_id
      properties:
        order_id:
          type: string
        amount:
          type: number
          format: double
        customer_id:
          type: string
        currency:
          type: string
          default: INR
        return_url:
          type: string
          format: uri
        payment_page_client_id:
          type: string
        action:
          type: string
          description: e.g. paymentPage.
    RefundInput:
      type: object
      required:
        - unique_request_id
        - amount
      properties:
        unique_request_id:
          type: string
          description: Uniquely identifies this refund request (max 255 chars).
        amount:
          type: number
          format: double
          description: Refund amount; must not exceed the refundable balance.
        refundType:
          type: string
          enum:
            - STANDARD
            - INSTANT
            - INSTANT_WITH_FALLBACK
          default: STANDARD
        metaData:
          type: string
          description: Optional context, including a description field for the reason.
    Refund:
      type: object
      properties:
        unique_request_id:
          type: string
        amount:
          type: number
          format: double
        status:
          type: string
        ref:
          type: string
    CustomerInput:
      type: object
      required:
        - customer_id
      properties:
        customer_id:
          type: string
          description: Unique customer id, at least 8 characters.
        mobile_number:
          type: string
        email_address:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        mobile_country_code:
          type: string
        options.get_client_auth_token:
          type: boolean
    Customer:
      allOf:
        - $ref: '#/components/schemas/CustomerInput'
        - type: object
          properties:
            id:
              type: string
              description: Juspay-assigned customer object id.
            juspay:
              type: object
              additionalProperties: true
              description: Container for a returned client_auth_token, when requested.