openapi: 3.0.3
info:
  title: 'Make My Payment API Documentation'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'https://api-uat.makemypayment.in'
tags:
  -
    name: Account
    description: ''
  -
    name: Payouts
    description: ''
  -
    name: Webhooks
    description: ''
paths:
  /api/v1/balance:
    get:
      summary: 'Get account balance.'
      operationId: getAccountBalance
      description: "Retrieve the current balance of the authenticated merchant's virtual account.\n\n**Note:**\n- Response will be AES encrypted using the merchant's API secret.\n- API key and secret must be sent in request headers for authentication."
      parameters:
        -
          in: header
          name: X-API-KEY
          description: ''
          example: 'string required Your API key for authentication.'
          schema:
            type: string
        -
          in: header
          name: X-API-SECRET
          description: ''
          example: 'string required Your API secret for encryption and authentication.'
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: true
                  message: 'Account balance retrieved successfully'
                  data:
                    result: 15000.5
                  errors: null
                properties:
                  status:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Account balance retrieved successfully'
                  data:
                    type: object
                    properties:
                      result:
                        type: number
                        example: 15000.5
                  errors:
                    type: string
                    example: null
        400:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: false
                  message: 'API key and secret are required'
                  data: null
                  errors: []
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: 'API key and secret are required'
                  data:
                    type: string
                    example: null
                  errors:
                    type: array
                    example: []
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: false
                  message: 'Invalid API key or secret'
                  data: null
                  errors: []
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: 'Invalid API key or secret'
                  data:
                    type: string
                    example: null
                  errors:
                    type: array
                    example: []
      tags:
        - Account
      security: []
  /api/v1/payouts/initiate:
    post:
      summary: 'Initiate a payout.'
      operationId: initiateAPayout
      description: "Start a new payout transaction for the authenticated merchant.\n\n**Note:** The request body must be:\n - AES encrypted (AES/CBC/PKCS5Padding)\n - Base64 encoded after encryption\n - Raw JSON payload before encryption should include: account_holder, account_number, bank_name, ifsc_code, amount, email, mobile"
      parameters:
        -
          in: header
          name: X-API-KEY
          description: ''
          example: 'string required Your API key for authentication.'
          schema:
            type: string
        -
          in: header
          name: X-API-SECRET
          description: ''
          example: 'string required Your API secret for decryption and authentication.'
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: true
                  message: 'Payout initiated successfully'
                  data: TXN987654321
                  errors: null
                properties:
                  status:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Payout initiated successfully'
                  data:
                    type: string
                    example: TXN987654321
                  errors:
                    type: string
                    example: null
        400:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: ''
                    type: object
                    example:
                      status: false
                      message: 'API key and secret are required'
                      data: null
                      errors: []
                    properties:
                      status:
                        type: boolean
                        example: false
                      message:
                        type: string
                        example: 'API key and secret are required'
                      data:
                        type: string
                        example: null
                      errors:
                        type: array
                        example: []
                  -
                    description: ''
                    type: object
                    example:
                      status: false
                      message: 'Request body is not valid base64 encoded'
                      data: null
                      errors: []
                    properties:
                      status:
                        type: boolean
                        example: false
                      message:
                        type: string
                        example: 'Request body is not valid base64 encoded'
                      data:
                        type: string
                        example: null
                      errors:
                        type: array
                        example: []
                  -
                    description: ''
                    type: object
                    example:
                      status: false
                      message: 'Failed to decrypt data'
                      data: null
                      errors: []
                    properties:
                      status:
                        type: boolean
                        example: false
                      message:
                        type: string
                        example: 'Failed to decrypt data'
                      data:
                        type: string
                        example: null
                      errors:
                        type: array
                        example: []
                  -
                    description: ''
                    type: object
                    example:
                      status: false
                      message: 'Invalid JSON format after decryption'
                      data: null
                      errors: []
                    properties:
                      status:
                        type: boolean
                        example: false
                      message:
                        type: string
                        example: 'Invalid JSON format after decryption'
                      data:
                        type: string
                        example: null
                      errors:
                        type: array
                        example: []
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: false
                  message: 'Invalid API key or secret'
                  data: null
                  errors: []
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: 'Invalid API key or secret'
                  data:
                    type: string
                    example: null
                  errors:
                    type: array
                    example: []
        422:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: false
                  message: 'Validation failed'
                  data: null
                  errors:
                    account_number:
                      - 'The account number field is required.'
                    amount:
                      - 'The amount must be at least 100.'
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: 'Validation failed'
                  data:
                    type: string
                    example: null
                  errors:
                    type: object
                    properties:
                      account_number:
                        type: array
                        example:
                          - 'The account number field is required.'
                        items:
                          type: string
                      amount:
                        type: array
                        example:
                          - 'The amount must be at least 100.'
                        items:
                          type: string
        500:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: false
                  message: 'Failed to initiate payout. Please try again.'
                  data: null
                  errors: []
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: 'Failed to initiate payout. Please try again.'
                  data:
                    type: string
                    example: null
                  errors:
                    type: array
                    example: []
      tags:
        - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account_holder:
                  type: string
                  description: 'The full name of the bank account holder.'
                  example: 'John Doe'
                  nullable: false
                account_number:
                  type: string
                  description: 'The bank account number.'
                  example: '1234567890'
                  nullable: false
                bank_name:
                  type: string
                  description: 'The name of the bank.'
                  example: 'HDFC Bank'
                  nullable: false
                ifsc_code:
                  type: string
                  description: 'The IFSC code of the bank branch.'
                  example: HDFC0001234
                  nullable: false
                amount:
                  type: numeric
                  description: 'The payout amount (must be at least 100).'
                  example: '500'
                  nullable: false
                email:
                  type: string
                  description: 'The email address of the beneficiary.'
                  example: user@example.com
                  nullable: false
                mobile:
                  type: numeric
                  description: 'The mobile number of the beneficiary (10 digits).'
                  example: '9876543210'
                  nullable: false
              required:
                - account_holder
                - account_number
                - bank_name
                - ifsc_code
                - amount
                - email
                - mobile
      security: []
  '/api/v1/payouts/{transaction_id}/status':
    get:
      summary: 'Check payout status.'
      operationId: checkPayoutStatus
      description: "Get the status of a specific payout transaction for the authenticated merchant.\n\n**Note:**\n- Response will be AES encrypted using the merchant's API secret.\n- API key and secret must be sent in request headers for authentication."
      parameters:
        -
          in: header
          name: X-API-KEY
          description: ''
          example: 'string required Your API key for authentication.'
          schema:
            type: string
        -
          in: header
          name: X-API-SECRET
          description: ''
          example: 'string required Your API secret for encryption and authentication.'
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: true
                  message: 'Payout status retrieved successfully'
                  data:
                    transaction_id: TXN123456
                    beneficiary:
                      account_holder: 'John Doe'
                      account_number: '1234567890'
                      bank_name: 'HDFC Bank'
                      ifsc_code: HDFC0001234
                    amount: '1000.00'
                    status: success
                    utr: UTR123456789
                    remarks: 'Payment processed successfully'
                  errors: null
                properties:
                  status:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Payout status retrieved successfully'
                  data:
                    type: object
                    properties:
                      transaction_id:
                        type: string
                        example: TXN123456
                      beneficiary:
                        type: object
                        properties:
                          account_holder:
                            type: string
                            example: 'John Doe'
                          account_number:
                            type: string
                            example: '1234567890'
                          bank_name:
                            type: string
                            example: 'HDFC Bank'
                          ifsc_code:
                            type: string
                            example: HDFC0001234
                      amount:
                        type: string
                        example: '1000.00'
                      status:
                        type: string
                        example: success
                      utr:
                        type: string
                        example: UTR123456789
                      remarks:
                        type: string
                        example: 'Payment processed successfully'
                  errors:
                    type: string
                    example: null
        400:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: false
                  message: 'API key and secret are required'
                  data: null
                  errors: []
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: 'API key and secret are required'
                  data:
                    type: string
                    example: null
                  errors:
                    type: array
                    example: []
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: false
                  message: 'Invalid API key or secret'
                  data: null
                  errors: []
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: 'Invalid API key or secret'
                  data:
                    type: string
                    example: null
                  errors:
                    type: array
                    example: []
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: false
                  message: 'Payout not found'
                  data: null
                  errors: []
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: 'Payout not found'
                  data:
                    type: string
                    example: null
                  errors:
                    type: array
                    example: []
      tags:
        - Payouts
      security: []
    parameters:
      -
        in: path
        name: transaction_id
        description: 'The transaction ID of the payout.'
        example: TXN123456
        required: true
        schema:
          type: string
  /api/webhooks/payout-status:
    post:
      summary: "Job for sending payout webhook to merchant.\n\nThis job handles sending a **POST request** to the merchant's webhook URL whenever a payout status changes to success.\nThe payload is **encrypted** using merchant's `api_secret` and includes the following data:"
      operationId: jobForSendingPayoutWebhookToMerchantThisJobHandlesSendingAPOSTRequestToTheMerchantsWebhookURLWheneverAPayoutStatusChangesToSuccessThePayloadIsencryptedUsingMerchantsapiSecretAndIncludesTheFollowingData
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  transaction_id: TXN12345
                  beneficiary_account_holder: 'John Doe'
                  beneficiary_account_number: '1234567890'
                  beneficiary_bank_name: 'HDFC Bank'
                  beneficiary_ifsc_code: HDFC0001234
                  amount: 1000.5
                  status: success
                  utr: UTR123456789
                  remarks: 'Monthly payout'
                properties:
                  transaction_id:
                    type: string
                    example: TXN12345
                  beneficiary_account_holder:
                    type: string
                    example: 'John Doe'
                  beneficiary_account_number:
                    type: string
                    example: '1234567890'
                  beneficiary_bank_name:
                    type: string
                    example: 'HDFC Bank'
                  beneficiary_ifsc_code:
                    type: string
                    example: HDFC0001234
                  amount:
                    type: number
                    example: 1000.5
                  status:
                    type: string
                    example: success
                  utr:
                    type: string
                    example: UTR123456789
                  remarks:
                    type: string
                    example: 'Monthly payout'
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction_id:
                  type: string
                  description: 'Unique transaction identifier for the payout.'
                  example: consequatur
                  nullable: false
                beneficiary_account_holder:
                  type: string
                  description: "Account holder's name. Nullable."
                  example: consequatur
                  nullable: false
                beneficiary_account_number:
                  type: string
                  description: 'Bank account number of the beneficiary. Nullable.'
                  example: consequatur
                  nullable: false
                beneficiary_bank_name:
                  type: string
                  description: 'Bank name of the beneficiary. Nullable.'
                  example: consequatur
                  nullable: false
                beneficiary_ifsc_code:
                  type: string
                  description: 'IFSC code of the beneficiary bank. Nullable.'
                  example: consequatur
                  nullable: false
                amount:
                  type: number
                  description: 'Payout amount.'
                  example: 11613.31890586
                  nullable: false
                status:
                  type: string
                  description: 'Payout status.'
                  example: '"success"'
                  nullable: false
                utr:
                  type: string
                  description: 'Nullable Unique Transaction Reference.'
                  example: consequatur
                  nullable: false
                remarks:
                  type: string
                  description: 'Nullable Any remarks related to the payout.'
                  example: consequatur
                  nullable: false
              required:
                - transaction_id
                - amount
                - status
      security: []
