cashfree-openapi.yaml

openapi: 3.0.3
info:
  title: Cashfree Payments APIs (converted from Postman collection)
  version: "2025-01-01"
  description: |
    This OpenAPI spec was generated from the "Cashfree Payments APIs" Postman
    collection. It focuses on the core Orders, Payments, and Payment Link APIs.
    Schemas are intentionally simplified (you can tighten them based on your
    needs and Cashfree's official docs).

servers:
  - url: "{baseUrl}"
    description: Cashfree Payments API base URL (sandbox or production).
    variables:
      baseUrl:
        default: https://sandbox.cashfree.com/pg
        description: >
          Replace with production base URL when you go live.

tags:
  - name: Orders
  - name: Payments
  - name: Payment Links
  - name: Recon & Settlements

paths:
  /orders:
    post:
      tags: [Orders]
      summary: Create Order
      description: |
        Create an order in Cashfree. Returns an order with `payment_session_id`
        that you can use to collect payments.  [oai_citation:0‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/AcceptJson"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOrderRequest"
            example:
              order_currency: "INR"
              order_id: "{{$randomUUID}}"
              order_amount: 10.34
              customer_details:
                customer_id: "7112AAA812234"
                customer_phone: "9898989898"
      responses:
        "200":
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "4XX":
          description: Client error
        "5XX":
          description: Server error

  /orders/{order_id}:
    get:
      tags: [Orders]
      summary: Get Order
      description: |
        Fetch an order created at Cashfree using `order_id`.
        Useful for checking the order status (`ACTIVE`, `PAID`, `EXPIRED`,
        `TERMINATED`, `TERMINATION_REQUESTED`).  [oai_citation:1‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/AcceptJson"
        - name: order_id
          in: path
          required: true
          schema:
            type: string
          description: Merchant order ID
      responses:
        "200":
          description: Order details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found

  /orders/{order_id}/extended:
    get:
      tags: [Orders]
      summary: Get Order Extended
      description: |
        Fetch extended order data such as address, cart items, offers, and
        customer details.  [oai_citation:2‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/AcceptJson"
        - name: order_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Extended order details
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

    put:
      tags: [Orders]
      summary: Update Order Extended
      description: |
        Update extended order related data such as shipment or charges.  [oai_citation:3‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/ContentTypeJson"
        - $ref: "#/components/parameters/AcceptJson"
        - name: order_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shipment_details:
                  type: array
                  items:
                    type: object
                    properties:
                      tracking_company:
                        type: string
                      tracking_urls:
                        type: array
                        items:
                          type: string
                          format: uri
                      tracking_numbers:
                        type: array
                        items:
                          type: string
                charges:
                  type: object
                  properties:
                    shipping_charges:
                      type: number
                    cod_handling_charges:
                      type: number
      responses:
        "200":
          description: Extended order updated
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /orders/sessions:
    post:
      tags: [Payments]
      summary: Order Pay / Create Payment Session
      description: |
        Process a payment for an existing order using a payment session.
        Supports card, UPI, wallets, etc. The `payment_session_id` comes from
        the Create Order API.  [oai_citation:4‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/ContentTypeJson"
        - $ref: "#/components/parameters/AcceptJson"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentSessionRequest"
            examples:
              card_link:
                summary: Card payment using link channel
                value:
                  payment_session_id: "{{payment_session_id}}"
                  payment_method:
                    card:
                      channel: "link"
                      card_number: "4111111111111111"
                      card_holder_name: "Harshith"
                      card_expiry_mm: "08"
                      card_expiry_yy: "32"
                      card_cvv: "111"
              upi_collect:
                summary: UPI collect
                value:
                  payment_session_id: "{{payment_session_id}}"
                  payment_method:
                    upi:
                      channel: "collect"
                      upi_id: "testsuccess@gocash"
                      upi_redirect_url: true
      responses:
        "200":
          description: Payment session created / payment initiated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentSessionResponse"

  /orders/pay/authenticate/{cf_payment_id}:
    post:
      tags: [Payments]
      summary: Submit or Resend OTP
      description: |
        Submit or resend OTP for card payments that use native OTP auth.  [oai_citation:5‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/ContentTypeJson"
        - $ref: "#/components/parameters/AcceptJson"
        - name: cf_payment_id
          in: path
          required: true
          schema:
            type: string
          description: Cashfree payment ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentOtpRequest"
            examples:
              submit_otp:
                value:
                  otp: "111000"
                  action: "SUBMIT_OTP"
              resend_otp:
                value:
                  action: "RESEND_OTP"
      responses:
        "200":
          description: OTP submitted or resend triggered
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /orders/{order_id}/payments:
    get:
      tags: [Payments]
      summary: Get Payments for an Order
      description: Retrieve all payment attempts for a specific order.  [oai_citation:6‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/AcceptJson"
        - name: order_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of payments for the order
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Payment"

  /orders/{order_id}/payments/{cf_payment_id}:
    get:
      tags: [Payments]
      summary: Get Payment by ID
      description: Fetch details of a single payment for an order.  [oai_citation:7‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/AcceptJson"
        - name: order_id
          in: path
          required: true
          schema:
            type: string
        - name: cf_payment_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Payment details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"

  /orders/{order_id}/settlements:
    get:
      tags: [Recon & Settlements]
      summary: Get Settlements by Order ID
      description: View all settlements for a specific order.  [oai_citation:8‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/AcceptJson"
        - name: order_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Settlements list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true

  /recon:
    post:
      tags: [Recon & Settlements]
      summary: Reconciliation
      description: Get payment gateway reconciliation details in a date range.  [oai_citation:9‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/ContentTypeJson"
        - $ref: "#/components/parameters/AcceptJson"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReconRequest"
      responses:
        "200":
          description: Reconciliation events
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /eligibility/offers:
    post:
      tags: [Payments]
      summary: Get Eligible Offers for an Order
      description: |
        Fetch offers applicable for a given order or amount.  [oai_citation:10‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/ContentTypeJson"
        - $ref: "#/components/parameters/AcceptJson"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                queries:
                  type: object
                  properties:
                    amount:
                      type: number
            example:
              queries:
                amount: 1000
      responses:
        "200":
          description: Eligible offers
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /links:
    post:
      tags: [Payment Links]
      summary: Create Payment Link
      description: |
        Create a new payment link. The generated `link_url` is returned in the
        response.  [oai_citation:11‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/ContentTypeJson"
        - $ref: "#/components/parameters/AcceptJson"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentLinkRequest"
            example:
              customer_details:
                customer_email: "john@cashfree.com"
                customer_name: "John Doe"
                customer_phone: "9999999999"
              link_amount: 100
              link_auto_reminders: true
              link_currency: "INR"
              link_expiry_time: "2025-12-14T15:04:05+05:30"
              link_id: "my_test_link"
              link_meta:
                notify_url: "https://example.com/notify"
                return_url: "https://www.cashfree.com/devstudio/thankyou"
                upi_intent: false
              link_minimum_partial_amount: 20
              link_notes:
                key_1: "value_1"
                key_2: "value_2"
              link_notify:
                send_email: true
                send_sms: false
              link_partial_payments: true
              link_purpose: "Payment for PlayStation 11"
      responses:
        "200":
          description: Payment link created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentLink"

  /links/{link_id}:
    get:
      tags: [Payment Links]
      summary: Fetch Payment Link Details
      description: View all details and status of a payment link.  [oai_citation:12‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/AcceptJson"
        - name: link_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Payment link details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentLink"

  /links/{link_id}/cancel:
    post:
      tags: [Payment Links]
      summary: Cancel Payment Link
      description: |
        Cancel an ACTIVE payment link. No further payments can be made against a
        cancelled link.  [oai_citation:13‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/AcceptJson"
        - name: link_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Payment link cancelled
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /links/{link_id}/orders:
    get:
      tags: [Payment Links]
      summary: Get Orders for a Payment Link
      description: View all orders created from a given payment link.  [oai_citation:14‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      parameters:
        - $ref: "#/components/parameters/XClientId"
        - $ref: "#/components/parameters/XClientSecret"
        - $ref: "#/components/parameters/XApiVersion"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XIdempotencyKey"
        - $ref: "#/components/parameters/AcceptJson"
        - name: link_id
          in: path
          required: true
          schema:
            type: string
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [ALL, PAID]
            default: ALL
          description: Order status to filter by.
      responses:
        "200":
          description: Orders for the payment link
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Order"

components:
  parameters:
    XClientId:
      name: x-client-id
      in: header
      required: true
      schema:
        type: string
      description: Client App ID for the API call.
    XClientSecret:
      name: x-client-secret
      in: header
      required: true
      schema:
        type: string
      description: Client Secret key for the API call.
    XApiVersion:
      name: x-api-version
      in: header
      required: true
      schema:
        type: string
        pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
        example: "2025-01-01"
      description: API version in YYYY-MM-DD format.
    XRequestId:
      name: x-request-id
      in: header
      required: false
      schema:
        type: string
      description: |
        Client-generated request ID for tracing & debugging.
    XIdempotencyKey:
      name: x-idempotency-key
      in: header
      required: false
      schema:
        type: string
      description: |
        Unique key to safely retry calls without duplicating actions.
    ContentTypeJson:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        enum: ["application/json"]
      example: application/json
    AcceptJson:
      name: Accept
      in: header
      required: true
      schema:
        type: string
        enum: ["application/json"]
      example: application/json

  schemas:
    CustomerDetails:
      type: object
      properties:
        customer_id:
          type: string
        customer_name:
          type: string
        customer_email:
          type: string
          format: email
        customer_phone:
          type: string
        customer_bank_account_number:
          type: string
        customer_bank_ifsc:
          type: string
        customer_bank_code:
          type: integer

    CreateOrderRequest:
      type: object
      required:
        - order_currency
        - order_amount
        - customer_details
      properties:
        order_id:
          type: string
          description: Merchant generated order ID.
        order_currency:
          type: string
          example: "INR"
        order_amount:
          type: number
          format: float
        customer_details:
          $ref: "#/components/schemas/CustomerDetails"
        order_meta:
          type: object
          properties:
            return_url:
              type: string
              format: uri
            notify_url:
              type: string
              format: uri
            payment_methods:
              type: string
        cart_details:
          type: object
          description: Cart information (for ecommerce merchants).
        order_tags:
          type: object
          additionalProperties:
            type: string
        order_expiry_time:
          type: string
          format: date-time
        order_note:
          type: string

    Order:
      type: object
      description: |
        Order representation from Cashfree. Shape is simplified; extend as needed.  [oai_citation:15‡Cashfree Payments APIs.postman_collection.json](sediment://file_0000000011c07207ad7ee18b4d1c069d)
      properties:
        cf_order_id:
          type: string
        order_id:
          type: string
        order_amount:
          type: number
        order_currency:
          type: string
        order_status:
          type: string
        order_expiry_time:
          type: string
          format: date-time
        payment_session_id:
          type: string
        customer_details:
          $ref: "#/components/schemas/CustomerDetails"
        order_meta:
          type: object
          additionalProperties: true
        order_tags:
          type: object
          additionalProperties:
            type: string
        cart_details:
          type: object
          additionalProperties: true

    PaymentSessionRequest:
      type: object
      required:
        - payment_session_id
        - payment_method
      properties:
        payment_session_id:
          type: string
        payment_method:
          type: object
          description: One-of card / upi / wallet, etc.
          properties:
            card:
              type: object
              properties:
                channel:
                  type: string
                  example: "link"
                card_number:
                  type: string
                card_holder_name:
                  type: string
                card_expiry_mm:
                  type: string
                card_expiry_yy:
                  type: string
                card_cvv:
                  type: string
            upi:
              type: object
              properties:
                channel:
                  type: string
                  example: "collect"
                upi_id:
                  type: string
                upi_redirect_url:
                  type: boolean

    PaymentSessionResponse:
      type: object
      description: Payment session response (simplified).
      properties:
        payment_method:
          type: string
        channel:
          type: string
        action:
          type: string
        cf_payment_id:
          type: string
        payment_amount:
          type: number
        data:
          type: object
          properties:
            url:
              type: string
              format: uri
            payload:
              type: object
            content_type:
              type: string
            method:
              type: string

    PaymentOtpRequest:
      type: object
      required:
        - action
      properties:
        otp:
          type: string
          description: Required when action is SUBMIT_OTP.
        action:
          type: string
          enum: [SUBMIT_OTP, RESEND_OTP]

    Payment:
      type: object
      description: Simplified payment object.
      properties:
        cf_payment_id:
          type: string
        payment_id:
          type: string
        subscription_id:
          type: string
        payment_amount:
          type: number
        payment_currency:
          type: string
        payment_status:
          type: string
        payment_method:
          type: string
        payment_type:
          type: string
        created_at:
          type: string
          format: date-time

    PaymentLinkRequest:
      type: object
      required:
        - customer_details
        - link_amount
        - link_currency
        - link_purpose
      properties:
        customer_details:
          type: object
          properties:
            customer_email:
              type: string
              format: email
            customer_name:
              type: string
            customer_phone:
              type: string
        link_amount:
          type: number
        link_currency:
          type: string
          example: "INR"
        link_auto_reminders:
          type: boolean
        link_expiry_time:
          type: string
          format: date-time
        link_id:
          type: string
          description: Custom identifier for the link.
        link_meta:
          type: object
          properties:
            notify_url:
              type: string
              format: uri
            return_url:
              type: string
              format: uri
            upi_intent:
              type: boolean
        link_minimum_partial_amount:
          type: number
        link_notes:
          type: object
          additionalProperties:
            type: string
        link_notify:
          type: object
          properties:
            send_email:
              type: boolean
            send_sms:
              type: boolean
        link_partial_payments:
          type: boolean
        link_purpose:
          type: string

    PaymentLink:
      type: object
      description: Payment link representation (simplified).
      properties:
        link_id:
          type: string
        link_url:
          type: string
          format: uri
        link_status:
          type: string
        link_amount:
          type: number
        link_currency:
          type: string
        customer_details:
          type: object
          additionalProperties: true

    ReconRequest:
      type: object
      properties:
        filters:
          type: object
          properties:
            start_date:
              type: string
              format: date-time
            end_date:
              type: string
              format: date-time