openapi: 3.0.0
info:
  title: Payment Methods
  description: 'The Payment Method APIs provide details about a payment method. You can retrieve, update, and delete payment methods.'
  contact: {}
  version: 1.0.0
servers:
  -
    url: 'https://payments.zoho.com/api/v1'
    description: 'API Endpoint'
tags:
  -
    name: payment-methods
    description: 'Payment Methods Module'
paths:
  /paymentmethods/{payment_method_id}:
    get:
      tags:
        - payment-methods
      summary: 'Retrieve Payment Method Details'
      description: 'This API endpoint allows you to retrieve the details of a specific payment method.'
      parameters:
        - name: payment_method_id
          description: 'A unique identifier for the payment method.'
          in: path
          required: true
          schema:
            type: number
            format: long
          example: 173000002315115
        - $ref: '#/components/parameters/account_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment-method-retrieve-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.paymentmethods.READ
    put:
      tags:
        - payment-methods
      summary: 'Update Payment Method'
      description: 'This API endpoint allows you to update the details of a payment method.'
      parameters:
        - name: payment_method_id
          description: 'A unique identifier for the payment method.'
          in: path
          required: true
          schema:
            type: number
            format: long
          example: 173000002315115
        - $ref: '#/components/parameters/account_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/payment-method-update-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment-method-update-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.paymentmethods.UPDATE
    delete:
      tags:
        - payment-methods
      summary: 'Delete Payment Method'
      description: 'This API endpoint allows you to delete a payment method.'
      parameters:
        - name: payment_method_id
          description: 'A unique identifier for the payment method.'
          in: path
          required: true
          schema:
            type: number
            format: long
          example: 173000002315115
        - $ref: '#/components/parameters/account_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment-method-delete-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.paymentmethods.DELETE
components:
  parameters:
    account_id:
      name: account_id
      description: "The Zoho Payments account ID."
      in: query
      required: true
      schema:
        type: number
        format: long
      example: 23137556
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/payment-method-response'
    payment-method-response:
      type: object
      properties:
        payment_method_id:
          $ref: '#/components/schemas/payment_method_id'
        customer_id:
          $ref: '#/components/schemas/customer_id'
        customer_name:
          $ref: '#/components/schemas/customer_name'
        customer_email:
          $ref: '#/components/schemas/customer_email'
        type:
          $ref: '#/components/schemas/type_response'
        card:
          $ref: '#/components/schemas/card'
        status:
          $ref: '#/components/schemas/status'
        currency:
          $ref: '#/components/schemas/currency'
        created_time:
          $ref: '#/components/schemas/created_time'
        last_modified_time:
          $ref: '#/components/schemas/last_modified_time'
    payment_method_id:
      description: 'A unique identifier for the payment method.'
      type: string
      example: '1987000000724211'
    customer_id:
      description: 'A unique identifier for the customer.'
      type: string
      example: '1987000000724207'
    customer_name:
      description: 'Name of the customer.'
      type: string
      example: 'Charles'
    customer_phone:
      description: 'Phone number associated with the customer.'
      type: string
      example: '+1 555-0100'
    customer_email:
      description: 'Email address of the customer.'
      type: string
      example: 'charles@example.com'
    status:
      description: 'The status of the payment method. (e.g., <code>active</code>, <code>expired</code>, <code>blocked</code>, <code>processing</code>, or <code>deleted</code>)'
      type: string
      example: 'active'
    created_time:
      description: 'The timestamp (milliseconds) indicating when the payment method was created.'
      type: integer
      format: int64
      example: 1708950672
    last_modified_time:
      description: 'The timestamp (milliseconds) indicating when the payment method was last modified.'
      type: integer
      format: int64
      example: 1708950672
    card:
      description: 'Contains card details.'
      type: object
      properties:
        card_holder_name:
          $ref: '#/components/schemas/card_holder_name'
        last_four_digits:
          $ref: '#/components/schemas/last_four_digits'
        expiry_month:
          $ref: '#/components/schemas/expiry_month'
        expiry_year:
          $ref: '#/components/schemas/expiry_year'
        card_checks:
          $ref: '#/components/schemas/card_checks'
    type:
      description: 'The type of payment method. (e.g., <code>card</code> or <code>ach_debit</code> )
      <div style="padding-bottom: 8px;"></div>
    <div class="divider">
    </div>
    <div style="padding-bottom: 6px;"></div>
    <div class="row" id=overview-ach_debit>
    <div class="property-wrapper">
        <div class="table-flex">
            <div class="property"> ach_debit</div>
            <div class="property-datatype"> object</div>
            <div class="property-kind" id="Optional">

            </div>
        </div>
        <details>
            <summary class="link">
                <span class="show-hide-attribute-text" data-showhide="Show Sub-Attributes">Show Sub-Attributes</span>
                <img src="/us/payments/api/v1/images/dropdown-arrow.svg" class="arrow-icon" alt="arrow" width="9px"
                     height="9px"/>
                </span>
            </summary>
            <div class=attribute-wrapper>
                <div class="row attribute small-line" id=overview-meta_data-key>
                    <div class="property-wrapper">
                        <div class="table-flex">
                            <div class="property"> account_holder_type</div>
                            <div class="property-datatype"> string</div>
                            <div class="property-kind" id="Optional">
                            </div>
                        </div>
                        <div class="prop-descrip"> Account holder type. ( eg., <code>individual</code> or <code>company</code>)</div>
                        </div>
                    </div>
                </div>
            </div>
        </details>
    </div>
'
      type: string
      example: 'card'
    type_response:
      description: 'The type of payment method. (e.g., <code>card</code> or <code>ach_debit</code> )
     <div style="padding-bottom: 8px;"></div>
<div class="divider">
</div>
<div style="padding-bottom: 6px;"></div>
<div class="row" id=overview-ach_debit>
    <div class="property-wrapper">
        <div class="table-flex">
            <div class="property"> ach_debit</div>
            <div class="property-datatype"> object</div>
            <div class="property-kind" id="Optional">

            </div>
        </div>
        <div class="prop-descrip"> Contains ACH details</div>
        <details>
            <summary class="link">
                <span class="show-hide-attribute-text" data-showhide="Show Sub-Attributes">Show Sub-Attributes</span>
                <img src="/us/payments/api/v1/images/dropdown-arrow.svg" class="arrow-icon" alt="arrow" width="9px"
                     height="9px"/>
                </span>
            </summary>
            <div class=attribute-wrapper>
                <div class="row attribute small-line" id=overview-account_holder_name>
                    <div class="property-wrapper">
                        <div class="table-flex">
                            <div class="property"> account_holder_name</div>
                            <div class="property-datatype"> string</div>
                            <div class="property-kind" id="Optional">
                            </div>
                        </div>
                        <div class="prop-descrip"> Name of the account holder.
                        </div>
                    </div>
                </div>
            </div>
            <div class=attribute-wrapper>
                <div class="row attribute small-line" id=overview-routing_number>
                    <div class="property-wrapper">
                        <div class="table-flex">
                            <div class="property"> routing_number</div>
                            <div class="property-datatype"> string</div>
                            <div class="property-kind" id="Optional">
                            </div>
                        </div>
                        <div class="prop-descrip"> Routing number.
                        </div>
                    </div>
                </div>
            </div>
            <div class=attribute-wrapper>
                <div class="row attribute small-line" id=overview-meta_data-key>
                    <div class="property-wrapper">
                        <div class="table-flex">
                            <div class="property"> account_holder_type</div>
                            <div class="property-datatype"> string</div>
                            <div class="property-kind" id="Optional">
                            </div>
                        </div>
                        <div class="prop-descrip"> Account holder type. ( eg., <code>individual</code> or
                            <code>company</code>)
                        </div>
                    </div>
                </div>
            </div>
            <div class=attribute-wrapper>
                <div class="row attribute small-line" id=overview-bank_name>
                    <div class="property-wrapper">
                        <div class="table-flex">
                            <div class="property"> bank_name</div>
                            <div class="property-datatype"> string</div>
                            <div class="property-kind" id="Optional">
                            </div>
                        </div>
                        <div class="prop-descrip"> Name of the bank.
                        </div>
                    </div>
                </div>
            </div>
            <div class=attribute-wrapper>
                <div class="row attribute small-line" id=overview-account_type>
                    <div class="property-wrapper">
                        <div class="table-flex">
                            <div class="property"> account_type</div>
                            <div class="property-datatype"> string</div>
                            <div class="property-kind" id="Optional">
                            </div>
                        </div>
                        <div class="prop-descrip"> Type of the account. (eg., <code>savings</code>)
                        </div>
                    </div>
                </div>
            </div>
            <div class=attribute-wrapper>
                <div class="row attribute small-line" id=overview-last_four_digits>
                    <div class="property-wrapper">
                        <div class="table-flex">
                            <div class="property"> last_four_digits</div>
                            <div class="property-datatype"> string</div>
                            <div class="property-kind" id="Optional">
                            </div>
                        </div>
                        <div class="prop-descrip"> The last four digits.
                        </div>
                    </div>
                </div>
            </div>
        </details>
    </div>
</div>
     '
      type: string
      example: 'card'
    brand:
      description: 'The brand of the card. (e.g., <code>visa</code>, <code>master_card</code>, etc.)'
      type: string
      example: 'visa'
    card_holder_name:
      description: 'The name of the cardholder.'
      type: string
      example: 'Charles'
    last_four_digits:
      description: 'The last four digits of the card number.'
      type: string
      example: '3212'
    expiry_month:
      description: 'The month when the card expires, formatted as MM.'
      type: string
      example: '01'
    expiry_year:
      description: 'The year when the card expires, formatted as YY.'
      type: string
      example: '26'
    funding:
      description: 'The funding type of the card. (e.g., <code>credit</code>, <code>debit</code>, etc.)'
      type: string
      example: 'credit'
    country:
      description: 'The country where the card was issued, represented by a <a href="https://www.iso.org/iso-3166-country-codes.html" target="_blank" rel="noopener noreferrer">2-letter ISO country code</a> (e.g., <code class="url">US</code>).'
      type: string
      example: 'US'
    currency:
      description: 'The currency in which the payment method operates, represented by a 3-letter ISO currency code <br>(e.g., <code class="url">USD</code>).'
      type: string
      example: 'USD'
    card_checks:
      description: 'Contains card checks. Card check Status can be <code>pass</code>, <code>fail</code>, <code>unavailable</code>, or <code>unchecked</code>.'
      type: object
      properties:
        address_line_check:
          $ref: '#/components/schemas/address_line_check'
        postal_code_check:
          $ref: '#/components/schemas/postal_code_check'
        cvc_check:
          $ref: '#/components/schemas/cvc_check'
    address_line_check:
      description: 'The result of the address line check.'
      type: string
      example: 'pass'
    postal_code_check:
      description: 'The result of the postal code check.'
      type: string
      example: 'pass'
    cvc_check:
      description: 'The result of the CVC check.'
      type: string
      example: 'pass'
    billing_address:
      description: 'Contains billing address details.'
      required:
        - country
      type: object
      properties:
        name:
          description: 'Billing name.'
          type: string
          example: 'Charles'
        address_line1:
          description: 'First line of the customer’s billing address.'
          type: string
          example: '123 Main St'
        address_line2:
          description: 'Second line of the customer’s billing address.'
          type: string
          example: 'Apt 4B'
        city:
          description: 'City of the customer’s billing address.'
          type: string
          example: 'Detroit'
        state:
          description: 'State of the customer’s billing address.'
          type: string
          example: 'Michigan'
        country:
          description: 'Country of the customer’s billing address, represented by a <a href="https://www.iso.org/iso-3166-country-codes.html" target="_blank" rel="noopener noreferrer">2-letter ISO country code</a> (e.g., <code class="url">US</code>).'
          type: string
          example: 'US'
        postal_code:
          description: 'Postal Code of the customer’s billing address.'
          type: string
          example: '12345'
    payment-method-retrieve-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'success'
          readOnly: true
        payment_method:
          $ref: '#/components/schemas/payment-method-response'
    payment-method-update-request:
      required:
        - type
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type'
        card:
          type: object
          properties:
            expiry_month:
              $ref: '#/components/schemas/expiry_month'
            expiry_year:
              $ref: '#/components/schemas/expiry_year'
        billing_address:
          $ref: '#/components/schemas/billing_address'
    payment-method-update-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'success'
          readOnly: true
        payment_method:
          type: object
          properties:
            payment_method_id:
              $ref: '#/components/schemas/payment_method_id'
            customer_id:
              $ref: '#/components/schemas/customer_id'
            customer_name:
              $ref: '#/components/schemas/customer_name'
            customer_email:
              $ref: '#/components/schemas/customer_email'
            type:
              $ref: '#/components/schemas/type_response'
            card:
              $ref: '#/components/schemas/card'
            status:
              $ref: '#/components/schemas/status'
            currency:
              $ref: '#/components/schemas/currency'
            billing_address:
              $ref: '#/components/schemas/billing_address'
            created_time:
              $ref: '#/components/schemas/created_time'
            last_modified_time:
              $ref: '#/components/schemas/last_modified_time'
    payment-method-delete-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'Payment method deleted'
          readOnly: true

  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'https://accounts.zoho.com/oauth/v2/auth'
          scopes:
            ZohoPay.paymentmethods.READ: 'Fetch Payment Method'
            ZohoPay.paymentmethods.UPDATE: 'Update Payment Method'
            ZohoPay.paymentmethods.DELETE: 'Delete Payment Method'

