> ## Documentation Index
> Fetch the complete documentation index at: https://eximpe.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Order

## Overview

The Create Order endpoint is the first step in the payment flow. It creates a new order with all the necessary details including buyer information, product details, and payment preferences.

After creating an order successfully, you'll receive a `session_id` and `order_id`. Use the `session_id` to redirect the customer to the payment gateway for completing the transaction.

## Payment Collection Modes

EximPe supports multiple payment collection modes:

### 1. Hosted Payment (Default)

The standard hosted payment flow where customers are redirected to EximPe's secure payment page.

### 2. S2S UPI Intent

Server-to-server UPI intent flow that generates a UPI intent link for direct app-to-app payments.

### 3. S2S UPI Collection

Server-to-server UPI collection flow that sends a payment request directly to the customer's VPA (Virtual Payment Address).

## Request Parameters

### Required Parameters

* `amount`: Payment amount in decimal format
* `currency`: 3-letter ISO currency code (e.g., INR)
* `reference_id`: Unique identifier for the order
* `buyer`: Buyer details object
* `product`: Product details object

### Optional Parameters

* `collection_mode`: Payment collection mode (`hosted_payment` or `s2s`)
* `mop_type`: Method of payment (`UPI`, `CREDIT_CARD`, `DEBIT_CARD`, `NET_BANKING`, `QR`)
* `upi_flow_type`: UPI flow type (`intent` or `collection`) - required when using S2S with UPI
* `vpa`: Virtual Payment Address - required when `upi_flow_type` is `collection`
* `upi_app_name`: Preferred UPI app - optional, defaults to `others`
* `return_url`: URL to redirect after payment completion
* `invoice`: Invoice details object

## Response

### Hosted Payment Response

For hosted payment mode, the response includes:

* `session_id`: Use this to redirect customers to the payment page
* `order_id`: Unique order identifier

### S2S UPI Intent Response

For S2S UPI Intent mode, the response includes:

* `order_id`: Unique order identifier
* `intent_uri`: UPI intent link that can be used to open UPI apps directly

### S2S UPI Collection Response

For S2S UPI Collection mode, the response includes:

* `order_id`: Unique order identifier
* `message`: Confirmation message about the collection request sent to the VPA

## Examples

<CodeGroup>
  ```json Hosted Payment theme={null}
  {
    "amount": "1000.00",
    "currency": "INR", 
    "reference_id": "ORDER_123456",
    "collection_mode": "hosted_payment",
    "return_url": "https://yourdomain.com/payment/callback",
    "mop_type": "UPI",
    "buyer": {
      "name": "Alice Smith",
      "email": "alice.smith@example.com",
      "phone": "+919812345678",
      "address": {
        "line_1": "221B Baker Street",
        "city": "Mumbai",
        "state": "Maharashtra", 
        "postal_code": "400001"
      }
    },
    "product": {
      "name": "Wireless Headphones",
      "type_of_goods": "goods"
    }
  }
  ```

  ```json S2S UPI Intent theme={null}
  {
    "amount": "1000.00",
    "currency": "INR",
    "reference_id": "ORDER_123457", 
    "collection_mode": "s2s",
    "mop_type": "UPI",
    "upi_flow_type": "intent",
    "upi_app_name": "google_pay",
    "buyer": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+919876543210",
      "address": {
        "line_1": "123 Main Street",
        "city": "Delhi",
        "state": "Delhi",
        "postal_code": "110001"
      }
    },
    "product": {
      "name": "Smartphone", 
      "type_of_goods": "goods"
    }
  }
  ```

  ```json S2S UPI Collection theme={null}
  {
    "amount": "1500.00",
    "currency": "INR",
    "reference_id": "ORDER_123458",
    "collection_mode": "s2s", 
    "mop_type": "UPI",
    "upi_flow_type": "collection",
    "vpa": "customer@paytm",
    "buyer": {
      "name": "Sarah Wilson",
      "email": "sarah.wilson@example.com", 
      "phone": "+919123456789",
      "address": {
        "line_1": "456 Park Avenue",
        "city": "Bangalore",
        "state": "Karnataka",
        "postal_code": "560001"
      }
    },
    "product": {
      "name": "Laptop",
      "type_of_goods": "goods"
    }
  }
  ```
</CodeGroup>

## Response Examples

<CodeGroup>
  ```json Hosted Payment Response theme={null}
  {
    "success": true,
    "message": "Checkout session created successfully",
    "data": {
      "session_id": "session_abc123def456",
      "order_id": "OD2000992103"
    }
  }
  ```

  ```json S2S UPI Intent Response theme={null}
  {
    "success": true,
    "message": "S2S UPI Request created successfully",
    "data": {
      "intent_uri": "pa=kk.payutest@hdfcbank&pn=&tr=403993715534292371&tid=PPPL403993715534292371080725205418&am=1000.00&cu=INR&tn=UPIIntent",
      "order_id": "OD2000992103"
    }
  }
  ```

  ```json S2S UPI Collection Response theme={null}
  {
    "success": true,
    "message": "S2S UPI Request created successfully", 
    "data": {
      "order_id": "OD1927283599",
      "message": "UPI Collection request sent to john.doe@payu"
    }
  }
  ```
</CodeGroup>

## Notes

* For S2S UPI Intent: The response will include a UPI intent link that can be used to open UPI apps directly
* For S2S UPI Collection: A payment request will be sent to the provided VPA, and the customer will receive a notification
* The `upi_app_name` parameter helps optimize the intent link for specific UPI applications
* VPA format must follow the pattern: `username@bank` (e.g., `user@paytm`, `9876543210@ybl`)


## OpenAPI

````yaml openapi.json post /pg/orders/
openapi: 3.0.0
info:
  title: Eximpe Payment Gateway API
  description: >-
    API for payment processing and order management through Eximpe payment
    gateway
  license:
    name: Proprietary
  version: 1.0.0
servers:
  - url: https://api-staging.eximpe.com
    description: Staging server
  - url: https://api.eximpe.com
    description: Production server
security:
  - clientAuth: []
    clientSecretAuth: []
paths:
  /pg/orders/:
    post:
      tags:
        - Orders
      summary: Create Order
      requestBody:
        description: Order creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              hosted_payment:
                summary: Hosted Payment
                description: Standard hosted payment flow
                value:
                  amount: '1000.00'
                  currency: INR
                  reference_id: ORDER_123456
                  return_url: https://yourdomain.com/payment/callback
                  collection_mode: hosted_payment
                  mop_type: UPI
                  buyer:
                    name: Alice Smith
                    email: alice.smith@example.com
                    phone: '+919812345678'
                    address:
                      line_1: 221B Baker Street
                      line_2: Near Central Park
                      city: Mumbai
                      state: Maharashtra
                      postal_code: '400001'
                  product:
                    name: Wireless Headphones
                    description: Noise-cancelling over-ear headphones
                    hs_code: '85183000'
                    hs_code_description: >-
                      Headphones and earphones, whether or not combined with a
                      microphone
                    type_of_goods: goods
                  invoice:
                    number: INV_20240621
                    date: '2024-06-21'
              s2s_upi_intent:
                summary: UPI Intent (S2S)
                description: Server-to-server UPI intent flow
                value:
                  amount: '1000.00'
                  currency: INR
                  reference_id: ORDER_123457
                  collection_mode: s2s
                  mop_type: UPI
                  upi_flow_type: intent
                  upi_app_name: google_pay
                  buyer:
                    name: John Doe
                    email: john.doe@example.com
                    phone: '+919876543210'
                    address:
                      line_1: 123 Main Street
                      city: Delhi
                      state: Delhi
                      postal_code: '110001'
                  product:
                    name: Smartphone
                    description: Latest Android smartphone
                    type_of_goods: goods
              s2s_upi_collection:
                summary: UPI Collection (S2S)
                description: Server-to-server UPI collection flow
                value:
                  amount: '1500.00'
                  currency: INR
                  reference_id: ORDER_123458
                  collection_mode: s2s
                  mop_type: UPI
                  upi_flow_type: collection
                  vpa: customer@paytm
                  buyer:
                    name: Sarah Wilson
                    email: sarah.wilson@example.com
                    phone: '+919123456789'
                    address:
                      line_1: 456 Park Avenue
                      city: Bangalore
                      state: Karnataka
                      postal_code: '560001'
                  product:
                    name: Laptop
                    description: Gaming laptop
                    type_of_goods: goods
        required: true
      responses:
        '200':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
              examples:
                hosted_payment:
                  summary: Hosted Payment
                  description: Response for hosted payment mode
                  value:
                    success: true
                    message: Checkout session created successfully
                    data:
                      session_id: session_abc123def456
                      order_id: OD2000992103
                s2s_upi_intent:
                  summary: UPI Intent (S2S)
                  description: Response for S2S UPI Intent mode
                  value:
                    success: true
                    message: S2S UPI Request created successfully
                    data:
                      intent_uri: >-
                        pa=kk.payutest@hdfcbank&pn=&tr=403993715534292371&tid=PPPL403993715534292371080725205418&am=1000.00&cu=INR&tn=UPIIntent
                      order_id: OD2000992103
                s2s_upi_collection:
                  summary: UPI Collection (S2S)
                  description: Response for S2S UPI Collection mode
                  value:
                    success: true
                    message: S2S UPI Request created successfully
                    data:
                      order_id: OD1927283599
                      message: UPI Collection request sent to customer@paytm
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: ERR_ORDER_002
                  message: Validation error
                  details:
                    reference_id: Reference ID must be unique
        '401':
          description: Unauthorized - Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - clientAuth: []
          clientSecretAuth: []
          merchantAuth: []
components:
  schemas:
    CreateOrderRequest:
      type: object
      required:
        - amount
        - currency
        - reference_id
        - buyer
        - product
      properties:
        amount:
          type: string
          description: Amount in decimal format (e.g., "100.00")
          pattern: ^\d+\.\d{2}$
        currency:
          type: string
          description: 3-letter ISO currency code (e.g., INR, USD)
          pattern: ^[A-Z]{3}$
        reference_id:
          type: string
          description: Unique identifier for the order
        return_url:
          type: string
          format: uri
          description: URL to redirect after payment
        collection_mode:
          type: string
          description: Payment collection mode
          enum:
            - hosted_payment
            - s2s
        mop_type:
          type: string
          description: Method of payment type (e.g., UPI)
          enum:
            - UPI
            - CREDIT_CARD
            - NETBANKING
            - DEBIT_CARD
            - QR
        upi_flow_type:
          type: string
          description: >-
            UPI flow type (required when collection_mode is s2s and mop_type is
            UPI)
          enum:
            - intent
            - collection
        vpa:
          type: string
          description: Virtual Payment Address (required when upi_flow_type is collection)
          pattern: ^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+$
        upi_app_name:
          type: string
          description: UPI app name (optional, defaults to 'others')
          enum:
            - bhim
            - paytm
            - google_pay
            - phonepe
            - cred
            - amazon_pay
            - whatsapp
            - others
        buyer:
          $ref: '#/components/schemas/Buyer'
        product:
          $ref: '#/components/schemas/Product'
        invoice:
          $ref: '#/components/schemas/Invoice'
    CreateOrderResponse:
      type: object
      required:
        - success
        - message
        - data
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        message:
          type: string
          description: Response message
        data:
          $ref: '#/components/schemas/OrderData'
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        error:
          $ref: '#/components/schemas/ErrorDetails'
    Buyer:
      type: object
      required:
        - name
        - address
      properties:
        name:
          type: string
          description: Buyer's full name
        email:
          type: string
          format: email
          description: Buyer's email address
        phone:
          type: string
          description: Buyer's phone number with country code
          pattern: ^\+[1-9]\d{1,14}$
        address:
          $ref: '#/components/schemas/Address'
    Product:
      type: object
      required:
        - name
        - type_of_goods
      properties:
        name:
          type: string
          description: Product name
        description:
          type: string
          description: Product description
        hs_code:
          type: string
          description: Harmonized System code
        hs_code_description:
          type: string
          description: Description of the HS code
        type_of_goods:
          type: string
          description: Type of goods (e.g., goods)
          enum:
            - goods
            - services
    Invoice:
      type: object
      properties:
        number:
          type: string
          description: Invoice number
        date:
          type: string
          format: date
          description: Invoice date in YYYY-MM-DD format
    OrderData:
      type: object
      required:
        - order_id
      properties:
        session_id:
          type: string
          description: >-
            Unique session identifier for payment processing (for hosted payment
            mode)
        order_id:
          type: string
          description: Unique order identifier
        intent_uri:
          type: string
          description: UPI intent URI for direct app opening (for S2S UPI Intent mode)
        message:
          type: string
          description: Status message (for S2S UPI Collection mode)
    ErrorDetails:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code (e.g., ERR_ORDER_002)
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Detailed validation error information with field-specific errors
          additionalProperties:
            type: string
            description: Error message for the specific field
    Address:
      type: object
      required:
        - line_1
        - city
        - state
        - postal_code
      properties:
        line_1:
          type: string
          description: Address line 1
        line_2:
          type: string
          description: Address line 2
        city:
          type: string
          description: City name
        state:
          type: string
          description: State name
        postal_code:
          type: string
          description: Postal/ZIP code
  securitySchemes:
    clientAuth:
      type: apiKey
      name: X-Client-ID
      in: header
      description: Client app ID. You can find your app id in the merchant dashboard.
    clientSecretAuth:
      type: apiKey
      name: X-Client-Secret
      in: header
      description: Client secret key. You can find your secret in the merchant dashboard.
    merchantAuth:
      type: apiKey
      name: X-Merchant-ID
      in: header
      description: >-
        Merchant ID. You can find your merchant ID in the merchant section of
        the merchant dashboard.

````