openapi: 3.0.0
info:
  title: Customers
  description: 'The Customer APIs provide access to create and retrieve customer details in Zoho Payments.'
  contact: {}
  version: 1.0.0
servers:
  -
    url: 'https://payments.zoho.com/api/v1'
    description: 'API Endpoint'
tags:
  -
    name: customers
    description: 'Customers Module'
paths:
  /customers:
    post:
      tags:
        - customers
      summary: 'Create Customer'
      description: 'This API endpoint allows you to create a new customer in Zoho Payments.'
      parameters:
        -
          $ref: '#/components/parameters/account_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customer-create-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer-create-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoPay.customers.CREATE
    get:
      tags:
        - customers
      summary: 'Retrieve Customer List'
      description: 'This API endpoint allows you to retrieve all the customer details.'
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/filter_by'
        - $ref: '#/components/parameters/from_date'
        - $ref: '#/components/parameters/to_date'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customers-retrieve-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.customers.READ
  /customers/{customer_id}:
    get:
      tags:
        - customers
      summary: 'Retrieve Customer'
      description: 'This API endpoint allows you to retrieve the details of a specific customer.'
      parameters:
        - name: customer_id
          description: 'A unique identifier for the customer.'
          in: path
          required: true
          schema:
            type: number
            format: long
          example: 173000002315107
        - $ref: '#/components/parameters/account_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer-retrieve-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.customers.READ
components:
  parameters:
    account_id:
      name: account_id
      description: 'The Zoho Payments account ID.'
      in: query
      required: true
      schema:
        type: number
        format: long
      example: 23137556
    filter_by:
      name: filter_by
      description: 'Filter the customer list using date intervals: <code>Date.Today</code>, <code>Date.ThisMonth</code>, <code>Date.ThisYear</code>, <code>Date.PreviousMonth</code>, <code>Date.PreviousYear</code>, <code>Date.CustomDate</code>, <code>Date.Last_30_Days</code>.'
      in: query
      required: false
      schema:
        type: string
      example: 'Date.Today'
    from_date:
      name: from_date
      description: 'Required if the parameter filter_by is <code>Date.CustomDate</code>. (e.g., <code>2024-08-06</code> )'
      in: query
      required: false
      schema:
        type: string
      example: '2024-08-29'
    to_date:
      name: to_date
      description: 'Required if the parameter filter_by is <code>Date.CustomDate</code>. (e.g., <code>2024-08-10</code> )'
      in: query
      required: false
      schema:
        type: string
      example: '2024-08-30'
    payment_method_type:
      name: payment_method_type
      description: 'Payment method types can be: <code>card</code> or <code>ach_debit</code>.'
      in: query
      required: false
      schema:
        type: string
      example: 'card'
    per_page:
      name: per_page
      description: 'Indicates the number of records to list per page. The default value is 25, and the maximum limit is 200.'
      in: query
      required: false
      schema:
        type: integer
      example: 25
    page:
      name: page
      description: 'Indicates the page number of the list of records. (e.g., <code>1</code> )'
      in: query
      required: false
      schema:
        type: integer
      example: 1
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/customer-response'
    customer-response:
      type: object
      properties:
        customer_id:
          $ref: '#/components/schemas/customer_id'
        name:
          $ref: '#/components/schemas/name'
        email:
          $ref: '#/components/schemas/email'
        phone:
          $ref: '#/components/schemas/phone'
        meta_data:
          $ref: '#/components/schemas/meta_data'
    customer_id:
      description: 'A unique identifier for the customer.'
      type: string
      example: '1987000000724207'
    name:
      description: 'Name of the customer.'
      type: string
      example: 'Charles'
    phone:
      description: 'Phone number associated with the customer.'
      type: string
      example: '+1 555-0100'
    email:
      description: 'Email address of the customer.'
      type: string
      example: 'charles@example.com'
    meta_data:
      description: "Provides metadata for the customer, which can be useful for storing additional information.
       The maximum size of the array can be 5. <br/>
       <ul><li>Customer identifiers for easy reference.</li>
       <li>Any additional identifiers or data stored in key-value pairs that may be helpful for future reference.</li></ul>"
      type: array
      items:
        type: object
        properties:
          key:
            description: 'A unique key used to store metadata for reference. The maximum length of the key can be 20 characters.'
            type: string
            example: 'Key1'
          value:
            description: 'The value associated with the key for reference. The maximum length of the value can be 500 characters.'
            type: string
            example: 'Value1'
    status:
      description: 'The status of the customer. (e.g., <code>active</code>)'
      type: string
      example: 'active'
    created_time:
      description: 'The timestamp (milliseconds) indicating when the customer was created.'
      type: integer
      format: int64
      example: 1708950672
    last_modified_time:
      description: 'The timestamp (milliseconds) indicating when the customer was last modified.'
      type: integer
      format: int64
      example: 1708950672
    payment_methods:
        description: 'The payment methods associated with the customer.'
        type: array
        items:
          type: object
          properties:
            payment_method_id:
              $ref: '#/components/schemas/payment_method_id'
            type:
              $ref: '#/components/schemas/type'
            brand:
              $ref: '#/components/schemas/brand'
            last_four_digits:
              $ref: '#/components/schemas/last_four_digits'
            expiry_month:
              $ref: '#/components/schemas/expiry_month'
            expiry_year:
              $ref: '#/components/schemas/expiry_year'
            card:
              $ref: '#/components/schemas/card'
    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'
    payment_method_id:
      description: 'A unique identifier for the payment method.'
      type: string
      example: '1987000000724209'
    type:
      description: 'The type of payment method. (e.g., <code>card</code> or <code>ach_debit</code> )'
      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'

    customer-create-request:
      required:
        - name
        - email
      type: object
      properties:
        name:
          $ref: '#/components/schemas/name'
        email:
          $ref: '#/components/schemas/email'
        phone:
          $ref: '#/components/schemas/phone'
        meta_data:
          $ref: '#/components/schemas/meta_data'

    customer-create-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'Customer created'
          readOnly: true
        customer:
          $ref: '#/components/schemas/customer-response'

    customer-retrieve-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'success'
          readOnly: true
        customer:
          type: object
          properties:
            customer_id:
              $ref: '#/components/schemas/customer_id'
            name:
              $ref: '#/components/schemas/name'
            email:
              $ref: '#/components/schemas/email'
            phone:
              $ref: '#/components/schemas/phone'
            meta_data:
              $ref: '#/components/schemas/meta_data'
            payment_methods:
                $ref: '#/components/schemas/payment_methods'
            created_time:
              $ref: '#/components/schemas/created_time'
            last_modified_time:
              $ref: '#/components/schemas/last_modified_time'

    customers-retrieve-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'success'
          readOnly: true
        customers:
          type: array
          items:
            type: object
            properties:
              customer_id:
                $ref: '#/components/schemas/customer_id'
              customer_name:
                $ref: '#/components/schemas/name'
              customer_email:
                $ref: '#/components/schemas/email'
              customer_phone:
                $ref: '#/components/schemas/phone'
              customer_status:
                $ref: '#/components/schemas/status'
              created_time:
                $ref: '#/components/schemas/created_time'
              last_modified_time:
                $ref: '#/components/schemas/last_modified_time'

  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'https://accounts.zoho.com/oauth/v2/auth'
          scopes:
            ZohoPay.customers.CREATE: 'Create Customer'
            ZohoPay.customers.READ: 'Fetch Customer Details'
