PhonePe Checkout API

openapi: 3.1.0
info:
  title: PhonePe Payment Gateway Checkout API
  description: 'Server-to-server PhonePe Payment Gateway (PG) REST API for creating

    checkout orders, retrieving order status, and processing refunds across

    UPI, cards, netbanking, and wallets.


    Requests are authenticated with a merchant auth token issued by PhonePe

    and sent in the `Authorization: O-Bearer <merchant-auth-token>` header.

    Partner integrations also include the `X-MERCHANT-ID` header naming the

    end merchant.


    Only a representative subset of the PhonePe PG surface (checkout,

    order status, refund initiation, refund status) is modeled here. See

    the PhonePe developer documentation linked under externalDocs for

    the full catalog.

    '
  version: 2.0.0
  contact:
    name: PhonePe Developer Documentation
    url: https://developer.phonepe.com/
  license:
    name: PhonePe Proprietary
servers:
- url: https://api.phonepe.com/apis/pg
  description: PhonePe PG production base URL.
- url: https://api-preprod.phonepe.com/apis/pg-sandbox
  description: PhonePe PG sandbox base URL.
security:
- merchantToken: []
tags:
- name: Checkout
  description: Create payment orders.
paths:
  /checkout/v2/pay:
    post:
      tags:
      - Checkout
      summary: Create a checkout payment
      description: 'Creates a PhonePe checkout order. The response contains a redirect or

        intent URL that the merchant surfaces to the buyer so they can

        authorize the payment.

        '
      operationId: createCheckoutPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
      responses:
        '200':
          description: Order created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
        '400':
          description: Invalid request.
        '401':
          description: Invalid or missing merchant token.
components:
  schemas:
    CheckoutRequest:
      type: object
      required:
      - merchantOrderId
      - amount
      properties:
        merchantOrderId:
          type: string
          description: Merchant-assigned unique order identifier.
        amount:
          type: integer
          description: Order amount in paise.
        expireAfter:
          type: integer
          description: Order TTL in seconds.
        paymentFlow:
          type: object
          additionalProperties: true
          description: Payment flow object (e.g. PG_CHECKOUT, redirectUrl).
        metaInfo:
          type: object
          additionalProperties: true
    CheckoutResponse:
      type: object
      properties:
        orderId:
          type: string
          description: PhonePe order identifier.
        state:
          type: string
          description: Current order state.
        expireAt:
          type: integer
        redirectUrl:
          type: string
          format: uri
          description: URL to redirect the buyer to authorize the payment.
  securitySchemes:
    merchantToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'Bearer-style merchant auth token issued by PhonePe. Sent as

        `Authorization: O-Bearer <merchant-auth-token>`. Partner integrations

        also include `X-MERCHANT-ID: <end-merchant-id>`.

        '
externalDocs:
  description: PhonePe developer documentation
  url: https://developer.phonepe.com/v1/docs/intro