openapi: 3.1.0
info:
  version: 1.0.0
  title: API specification for Glomo
  termsOfService: https://www.glomopay.com/legal#terms-and-conditions
  contact:
    name: ''
    email: developer@glomopay.com
    url: ''
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  x-logo:
    url: https://redocly.github.io/openapi-template/logo.png
  description: >
    The Glomo API follows REST architecture, utilizing resource-oriented URLs
    for clarity. It handles form-encoded request bodies, delivers responses in
    JSON format, and operates with standard HTTP methods, authentication, and
    response codes.


    You can download the complete API collection by using the download options
    on the right.
tags:
  - name: balance_conversions
    x-displayName: Balance Conversions
    description: >-
      Balance Conversion resource represents the details of the balance
      conversion. The balance conversion is the conversion of the balance from
      one supported currency to another supported currency.
    x-group: Multi Currency Account
  - name: payment_link
    x-displayName: Payment Link
    description: >-
      A payment link is a shareable URL that will take your customers to a
      Glomo-hosted payment page. The payment page can only be accessed by your
      customer after the completion of 1FA via their email.
    x-group: Payin
  - name: Customer
    description: >-
      This resource represents a customer of your business. The customer can be
      an individual or a business from whom you will receive payments.
    x-group: Payin
  - name: Document
    description: >-
      Document resource represents the documents details uploaded. This document
      is used in payin, payout, etc.
    x-group: Payin
  - name: Payment
    description: >-
      This resource represents a payment attempt made by your customer. The
      payment can either be successfully completed or failed, depending on
      various factors.
    x-group: Payin
  - name: Refund
    description: >-
      This resource represents a refund transaction from your Glomo account to
      your customer. You can retrieve it to see the details of the refund
      transaction.
    x-group: Payin
  - name: Payout
    description: >-
      This resource represents the disbursement transactions from your Glomo
      account to your beneficiaries.
    x-group: Payout
  - name: Balance
    description: >-
      This resource represents your Glomo balance. You can retrieve it to see
      the current balance on your Glomo account in all currencies enabled for
      your account.
    x-group: Multi Currency Account
  - name: bank_account_validation
    x-displayName: Bank Account Validation
    description: >-
      Bank Account Validation resource represents the validation details of a
      bank account.
    x-group: Payout
  - name: Beneficiary
    description: >-
      This resource represents a payee of a payout initiated by your business.
      The beneficiary can be an individual or a business to whom you will send
      funds.
    x-group: Payout
  - name: Price
    description: >-
      This resource represents the pricing details of the payin or payout. The
      pricing details include the fees and the pricing type
    x-group: Payin
  - name: Withdrawal
    description: >-
      This resource represents the withdrawal transaction from your Glomo
      account to your withdrawal account.
    x-group: Withdrawal
  - name: withdrawal_account
    x-displayName: Withdrawal Account
    description: >-
      This resource represents the withdrawal account details. The withdrawal
      account is the bank account where the withdrawal amount will be credited.
    x-group: Withdrawal
  - name: Orders
    description: >-
      This resource represents the order details. The order is the request to
      receive payment from your customer.
    x-group: Payin
  - name: Subscription
    description: >-
      This resource represents a recurring billing agreement for a customer.
      Subscriptions allow businesses to automatically charge customers on a
      regular schedule according to a defined billing plan.
    x-group: Subscription
  - name: Webhook
    x-displayName: Webhook
    description: >-
      This resource represents the webhook details. The webhook is the endpoint
      where the webhook events will be sent.
    x-group: Webhook
  - name: Settlement
    description: >-
      This resource represents the settlement details. The settlement is the
      process of transferring funds from your Glomo account to your bank
      account.
    x-group: Settlement
x-tagGroups:
  - name: Multi Currency Account
    tags:
      - Balance
      - balance_conversions
  - name: Payin
    tags:
      - payment_link
      - Orders
      - Customer
      - Document
      - Payment
      - Refund
      - Price
  - name: Subscription
    tags:
      - Subscription
  - name: Payout
    tags:
      - Payout
      - Beneficiary
      - bank_account_validation
  - name: Withdrawal
    tags:
      - Withdrawal
      - withdrawal_account
  - name: Settlement
    tags:
      - Settlement
servers:
  - url: https://api.glomopay.com/api/v1
    description: Production server
paths:
  /balances:
    get:
      tags:
        - Balance
      summary: Retrieve balances
      description: |
        Retrieves available balances for all currencies.
      operationId: getBalance
      security:
        - JWT: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/AllBalances'
        '401':
          description: Unauthorized
  /balance_conversions:
    post:
      tags:
        - balance_conversions
      summary: Convert balances
      description: >
        Converts balance from one currency to another. In the API you can either
        send `target_amount` or `source_amount` and the API will calculate the
        other amount for you.
      operationId: createBalanceConversion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    source_currency:
                      type: string
                      format: iso-4217
                      description: >
                        The currency code in [ISO
                        4217](https://en.wikipedia.org/wiki/ISO_4217) format.
                        Supported currencies: USD,EUR and GBP.
                      example: USD
                    target_currency:
                      type: string
                      format: iso-4217
                      description: >
                        The currency code in [ISO
                        4217](https://en.wikipedia.org/wiki/ISO_4217) format.
                        Supported currencies: USD,EUR and GBP.
                      example: USD
                    source_amount:
                      type: number
                      minimum: 1
                      description: >
                        The amount you want to convert. A positive integer
                        representing the smallest currency unit.  For example,
                        if the amount is $299.00, then pass 29900 in this
                        field.  In the case of three decimal currencies, such as
                        KWD, BHD and OMR, to represent an amount of 295.991,
                        pass the value as 295990.  And in the case of zero
                        decimal currencies such as JPY, for amount ￥295, pass
                        the value as 295. ``` Only one of `source_amount` or
                        `target_amount` can be sent. ```
                      example: 1000
                  required:
                    - source_currency
                    - target_currency
                    - source_amount
                  additionalProperties: false
                - type: object
                  properties:
                    source_currency:
                      type: string
                      format: iso-4217
                      description: >
                        The currency code in [ISO
                        4217](https://en.wikipedia.org/wiki/ISO_4217) format.
                        Supported currencies: USD,EUR and GBP.
                      example: USD
                    target_currency:
                      type: string
                      format: iso-4217
                      description: >
                        The currency code in [ISO
                        4217](https://en.wikipedia.org/wiki/ISO_4217) format.
                        Supported currencies: USD,EUR and GBP.
                      example: USD
                    target_amount:
                      type: number
                      minimum: 1
                      description: >
                        The amount you want to receive. A positive integer
                        representing the smallest currency unit.  For example,
                        if the amount is $299.00, then pass 29900 in this
                        field.  In the case of three decimal currencies, such as
                        KWD, BHD and OMR, to represent an amount of 295.991,
                        pass the value as 295990.  And in the case of zero
                        decimal currencies such as JPY, for amount ￥295, pass
                        the value as 295. ``` Only one of `source_amount` or
                        `target_amount` can be sent. ```
                      example: 1000
                  required:
                    - source_currency
                    - target_currency
                    - target_amount
                  additionalProperties: false
      responses:
        '201':
          description: Refund created successfully
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/BalanceConversion'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: |
                      Error message.
                    example: >-
                      You can only send source_amount or target_amount, not
                      both.
      security:
        - JWT: []
    get:
      tags:
        - balance_conversions
      summary: List all Balance Conversions
      description: >
        Returns a list of your balance conversions. The balance conversions are
        returned sorted by creation date, with the most recent beneficiary
        appearing first.
      operationId: getBalanceConversions
      parameters:
        - in: query
          name: source_currency
          schema:
            type: string
            format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported
            currencies: USD,EUR and GBP.
          example: USD
        - in: query
          name: target_currency
          schema:
            type: string
            format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported
            currencies: USD,EUR and GBP.
          example: USD
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of balance conversions matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BalanceConversion'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: Error message indicating which parameter was invalid
      security:
        - JWT: []
  /bank_account_validation:
    post:
      tags:
        - bank_account_validation
      summary: Validate any bank account
      operationId: validateBankAccount
      security:
        - JWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/BankAccount'
                  required:
                    - country
                    - holder_name
                    - account_number
                    - bic_primary
                    - bic_secondary
                - type: object
                  title: BankAccountReference
                  properties:
                    id:
                      type: string
                      description: The ID of an already saved beneficiary bank account
                      example: bene_5JU9yv0lGSUP
                  required:
                    - id
      responses:
        '200':
          description: Bank account validation successful
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/BankAccountValidation'
        '400':
          description: Bad request
    get:
      tags:
        - bank_account_validation
      summary: List all bank account validations
      operationId: getBankAccountValidations
      security:
        - JWT: []
      parameters:
        - in: query
          name: beneficiary_account_id
          schema:
            type: string
          description: The ID of the beneficiary bank account to filter validations
          example: bene_5JU9yv0lGSUP
        - in: query
          name: country
          schema:
            type: string
            format: iso-3166-1-alpha-3, case-insensitive
            description: >
              The country where the customer is located. Country should be sent
              as a [ISO 3166-1
              alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
            example: Ind
          description: The ISO 3166-1 alpha-3 code of the country to filter validations
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of bank account validations matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BankAccountValidation'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: Error message indicating which parameter was invalid
  /beneficiaries:
    post:
      tags:
        - Beneficiary
      summary: Create a Beneficiary
      description: >
        Creates a beneficiary with information such as name, contact, address,
        and banking information.
      operationId: createBeneficiary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Beneficiary'
              required:
                - beneficiary_type
                - account_number
                - holder_name
                - bic_primary
                - bic_secondary
                - bank_name
                - address_line1
                - email
                - city
                - state
                - country
                - pincode
                - nickname
      responses:
        '201':
          description: Beneficiary created successfully
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Beneficiary'
        '400':
          description: Bad request
      security:
        - JWT: []
    get:
      tags:
        - Beneficiary
      summary: List all Beneficiaries
      description: >
        Returns a list of your beneficiaries. The beneficiaries are returned
        sorted by creation date, with the most recent beneficiary appearing
        first.
      operationId: getBeneficiaries
      parameters:
        - in: query
          name: beneficiary_type
          schema:
            type: string
            enum:
              - individual
              - business
          description: Type of beneficiary to filter
        - in: query
          name: country
          schema:
            type: string
            format: iso-3166-1-alpha-3, case-insensitive
            description: >
              The country where the customer is located. Country should be sent
              as a [ISO 3166-1
              alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
            example: IND
          description: The ISO 3166-1 alpha-3 code of the country to filter validations
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of beneficiaries matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Beneficiary'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: Error message indicating which parameter was invalid
      security:
        - JWT: []
  /beneficiaries/{id}:
    get:
      tags:
        - Beneficiary
      summary: Retrieve a beneficiary
      description: |
        Retrieves details of a beneficiary.
      operationId: getBeneficiaryById
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the beneficiary
      responses:
        '200':
          description: Beneficiary details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Beneficiary'
        '404':
          description: Beneficiary not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
      security:
        - JWT: []
  /customer:
    post:
      tags:
        - Customer
      summary: Create a new customer
      description: >
        Creates a customer with basic information such as name, contact
        information, and address.
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
              required:
                - name
                - customer_type
                - email
                - phone
                - address
                - city
                - state
                - country
                - pincode
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Customer'
        '400':
          description: Bad request
      security:
        - JWT: []
    get:
      tags:
        - Customer
      summary: List all customers
      description: >
        Returns a list of your customers. The customers are returned sorted by
        creation date, with the most recent customers appearing first.
      operationId: getCustomers
      parameters:
        - in: query
          name: customer_type
          schema:
            type: string
            enum:
              - individual
              - business
          description: Type of customer to filter
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of customers matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: Error message indicating which parameter was invalid
      security:
        - JWT: []
  /customer/{id}:
    get:
      tags:
        - Customer
      summary: Retrieve a customer
      description: |
        Retrieves details of a Customer.
      operationId: getCustomerById
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the customer
          example: cust_5JU9yv0lGSUP
      responses:
        '200':
          description: Customer retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
      security:
        - JWT: []
  /document:
    post:
      tags:
        - Document
      summary: Create a new document
      operationId: createDocument
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document_name:
                  type: string
                  description: |
                    The name of the document
                  example: invoice
                file:
                  type: string
                  format: binary
                  description: >
                    The file to be uploaded. This should be sent as a binary in
                    the multipart/form-data request.
              required:
                - file
                - document_name
      responses:
        '201':
          description: Document created successfully
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/DocumentResponse'
        '400':
          description: Bad request
      security:
        - JWT: []
    get:
      tags:
        - Document
      summary: List all documents
      description: >
        Returns a list of your documents. The documents are returned sorted by
        creation date, with the most recent documents appearing first.
      operationId: getDocuments
      parameters:
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of documents matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DocumentResponse'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad request
      security:
        - JWT: []
  /orders:
    post:
      tags:
        - Orders
      summary: Create a new order
      description: |
        Creates an order for checkout.
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Orders'
              required:
                - amount
                - currency
                - customer_id
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Orders'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: |
                      Error message.
                    example: Currency not supported
      security:
        - JWT: []
    get:
      tags:
        - Orders
      summary: List all orders
      description: >
        Returns a list of your orders. The orders are returned sorted by
        creation date, with the most recent order appearing first.
      operationId: getOrders
      parameters:
        - in: query
          name: customer_id
          schema:
            type: string
          description: Orders of customer to filter
        - in: query
          name: status
          schema:
            type: string
            enum:
              - active
              - paid
              - failed
              - action_required
              - cancelled
              - under_review
          description: Status of order to filter
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of orders matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Orders'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: |
                      Error message.
                    example: Invalid customer_id
      security:
        - JWT: []
  /orders/{id}:
    get:
      tags:
        - Orders
      summary: Retrieve an order
      description: |
        Retrieve details of an order.
      operationId: getOrderById
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the order
          example: order_678a4c88hpAjf
      responses:
        '200':
          description: Payment link retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders'
        '404':
          description: Payment link not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
      security:
        - JWT: []
  /payin:
    post:
      tags:
        - payment_link
      summary: Create a new Payment Link
      description: |
        Creates a shareable URL for a hosted payment page.
      operationId: createPayin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentLink'
              required:
                - amount
                - currency
                - customer_id
                - purpose_code
                - expires_at
      responses:
        '201':
          description: Payment link created successfully
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/PaymentLink'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: |
                      Error message.
                    example: >-
                      You can only send source_amount or target_amount, not
                      both.
      security:
        - JWT: []
    get:
      tags:
        - payment_link
      summary: List all payment links
      description: >
        Returns a list of your payment links. The payment links are returned
        sorted by creation date, with the most recent payment link appearing
        first.
      operationId: getPayins
      parameters:
        - in: query
          name: customer_id
          schema:
            type: string
          description: Payment links of customer to filter
        - in: query
          name: status
          schema:
            type: string
            enum:
              - active
              - paid
              - failed
              - action_required
              - cancelled
              - partially_paid
              - under_review
              - expired
          description: Status of payment link to filter
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of payment links matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentLink'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: |
                      Error message.
                    example: Invalid customer_id
      security:
        - JWT: []
  /payin/{id}:
    get:
      tags:
        - payment_link
      summary: Retrieve a payment link
      description: |
        Retrieve details of a payment link.
      operationId: getPayinById
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the payin
          example: payin_678a4c88hpAjf
      responses:
        '200':
          description: Payment link retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '404':
          description: Payment link not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
      security:
        - JWT: []
    patch:
      tags:
        - payment_link
      summary: Update an existing payment link
      operationId: updatePayin
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the payment link to update.
          schema:
            type: string
            example: e092be15-e614-4401-8cea-7ca3df7da987
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reminder_frequency:
                  type: number
                  description: >
                    The frequency at which you want to remind customers, valid
                    values  are 1 (remind every day), 2 (remind every alternate
                    day), 7  (remind every week), 14 (remind every alternate
                    week).
                  example: 1
                expires_at:
                  type: string
                  format: timestamp
                  description: >
                    The new expiry date for the payin. Expiry cannot be less
                    than or  equal to the current date and can be up to 6 months
                    in the future.
                  example: '2025-02-15T00:00:00.000Z'
              additionalProperties: false
      responses:
        '200':
          description: Payment link updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '400':
          description: Bad request
        '404':
          description: Payment link not found
      security:
        - JWT: []
  /payin/{id}/cancel:
    patch:
      tags:
        - payment_link
      summary: Cancel a payment link
      description: |
        Invalidate payment link and prevent further transactions
      operationId: cancelPayin
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the payment link to cancel
          example: e092be15-e614-4401-8cea-7ca3df7da987
      responses:
        '200':
          description: Payment link canceled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '404':
          description: Payment link not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
      security:
        - JWT: []
  /payin/{id}/mock_mark_reviewed:
    patch:
      tags:
        - payment_link
      summary: Mock review a payment link
      description: |
        Mark an under_review payment link reviewed
      operationId: mockReviewPaymentLink
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the payment link to review
          example: payin_E602dMzgjpDC
      responses:
        '200':
          description: Payment link successfully marked reviewed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: |
                      Error message.
                    example: Payment link is not under review.
        '404':
          description: Payment link not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
      security:
        - JWT: []
  /payouts:
    post:
      tags:
        - Payout
      summary: Create a new payout
      operationId: createPayout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CreatePayoutRequest'
                  required:
                    - destination_currency
                    - source_currency
                    - beneficiary_id
                    - purpose_code
                    - documents
      responses:
        '201':
          description: Payout created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
      security:
        - JWT: []
    get:
      tags:
        - Payout
      summary: List all payouts
      operationId: getPayouts
      parameters:
        - in: query
          name: beneficiary_id
          schema:
            type: string
          description: The unique identifier of the beneficiary
          example: bene_5JU9yv0lGSUP
        - in: query
          name: status
          schema:
            type: string
            enum:
              - in_progress
              - success
              - failed
              - action_required
              - cancelled
              - under_review
          description: Status of payout to filter
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of payouts matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payout'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
      security:
        - JWT: []
  /payouts/{id}:
    get:
      tags:
        - Payout
      summary: |
        Retrieve a payout
      operationId: getPayoutById
      security:
        - JWT: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier for the payout.
          example: pout_E602dMzgjpDC
      responses:
        '200':
          description: Payout found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '404':
          description: Payout not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
  /payouts/{id}/cancel:
    patch:
      tags:
        - Payout
      summary: Cancel a payout
      operationId: cancelPayout
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the payout to cancel.
          schema:
            type: string
            example: pout_DdWp_HUbOnlg
      responses:
        '200':
          description: Payout cancelled successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Payout'
                  - type: object
                    properties:
                      status:
                        type: string
                        description: |
                          The status of the payout.
                        example: cancelled
        '400':
          description: Bad request
        '404':
          description: Payout not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
      security:
        - JWT: []
  /payouts/{id}/update_rfi:
    patch:
      tags:
        - Payout
      summary: Update RFI for Payout
      operationId: updateRfiPayout
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: The unique identifier for the payout.
            example: payout_E602dMzgjpDC
      security:
        - JWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                documents:
                  type: array
                  items:
                    $ref: '#/components/schemas/AttachedDocument'
                    required:
                      - rfi_doc_id
                      - id
              required:
                - documents
      responses:
        '200':
          description: Document attached successfully
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Payout'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
  /payouts/mock:
    patch:
      tags:
        - Payout
      summary: Mock update a payout status
      operationId: mockUpdatePayoutStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/MockUpdatePayoutStatusRequest'
                  required:
                    - id
                    - status
      responses:
        '200':
          description: Payout updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
      security:
        - JWT: []
  /payment:
    get:
      tags:
        - Payment
      summary: List all payments
      operationId: getPayments
      parameters:
        - in: query
          name: customer_id
          schema:
            type: string
          description: The unique identifier for the customer.
          example: cust_E602sMzgjpDC
        - in: query
          name: status
          schema:
            type: string
            enum:
              - success
              - failed
              - action_required
              - in_progress
          example: success
          description: Status of payin to filter
        - in: query
          name: payin_id
          schema:
            type: string
          description: The unique identifier for the payin.
          example: payin_E602dMzgjpDC
        - in: query
          name: subscription_id
          schema:
            type: string
          description: The unique identifier for the subscription.
          example: sub_68877570b5zeE
        - in: query
          name: currency
          schema:
            type: string
            format: iso-4217, case-insensitive
            description: >
              The currency in which the payment is made. The currency code is in
              [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
              example, USD.
          example: USD
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of payments matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
      security:
        - JWT: []
  /payment/mock:
    post:
      tags:
        - Payment
      summary: Create a mock payment
      description: >
        This API is only available in sandbox mode. Creates a mock payment of
        specified amount for any given Payment link.
      operationId: createMockPayment
      security:
        - JWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  minimum: 1
                  description: >
                    The amount you want to convert in main unit. For example, 10
                    is $10.00.
                  example: 10
                currency:
                  type: string
                  format: iso-4217
                  description: >
                    The currency code in [ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
                    example, USD.  Keep this currency same as that in Payment
                    link to create a successful payment. A different currency
                    will create a payment in RFI(Action Required) state
                  example: USD
                payin_id:
                  type: string
                  description: >
                    The unique identifier for the payin. This is the identifier
                    of the Payment link.
                  example: payin_E602dMzgjpDC
              required:
                - amount
                - currency
                - payin_id
      responses:
        '201':
          description: Payment created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Payment'
        '400':
          description: Bad request
  /payment/{id}:
    get:
      tags:
        - Payment
      summary: |
        Retrieve a payment
      operationId: getPaymentById
      security:
        - JWT: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier for the payment.
          example: payt_E602dMzgjpDC
      responses:
        '200':
          description: Payment found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
  /payment/{id}/update_rfi:
    patch:
      tags:
        - Payment
      summary: Update RFI for Payment
      operationId: updateRfiPayment
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: The unique identifier for the payment.
            example: payt_E602dMzgjpDC
      security:
        - JWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                documents:
                  type: array
                  items:
                    $ref: '#/components/schemas/AttachedDocument'
                    required:
                      - rfi_doc_id
                      - id
              required:
                - documents
      responses:
        '200':
          description: Document attached successfully
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Payment'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
  /refunds:
    post:
      tags:
        - Refund
      summary: Create refund for a payment
      description: >
        Creates refund for a payment entity if the payment is in success state
        and no other refund exists.
      operationId: createRefund
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  enum:
                    - Requested By Customer
                    - Duplicate
                    - Fradulent
                    - Others
                  description: |
                    The reason for the refund.
                payment_id:
                  type: string
                  description: |
                    The unique identifier of payment linked to refund.
                  example: payt_E602dMzgjpDC
                document_id:
                  type: string
                  description: |
                    The id of document that is uploaded for refund.
                  example: doc_E602dMd2adDC
                document_url:
                  type: string
                  description: |
                    The url of document that is uploaded for refund.
                  example: https://www.example.com/documents/invoice.pdf
                file_name:
                  type: string
                  description: |
                    The name of document that is uploaded for refund.
                  example: invoice
              required:
                - payment_id
                - reason
      responses:
        '201':
          description: Refund created successfully
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Refund'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: |
                      Error message.
                    example: Refund is already in progress.
      security:
        - JWT: []
    get:
      tags:
        - Refund
      summary: List all refunds
      description: >
        Returns a list of refunds in response. The refunds are returned sorted
        by creation date, with the most recent refund appearing first.
      operationId: getRefunds
      parameters:
        - in: query
          name: customer_id
          schema:
            type: string
          description: Refunds of customer to filter
        - in: query
          name: payment_method
          schema:
            type: string
          description: Refunds of payment_methods to filter
        - in: query
          name: payment_id
          schema:
            type: string
          description: Refunds of payment_id to filter
        - in: query
          name: status
          schema:
            type: string
            enum:
              - success
              - failed
              - action_required
              - pending
              - under_review
          description: Refund status to filter
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of Refunds matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Refund'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '401':
          description: Unauthorized
      security:
        - JWT: []
  /refunds/{id}:
    get:
      tags:
        - Refund
      summary: |
        Retrieve a refund
      operationId: getRefundById
      security:
        - JWT: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier for the payout.
          example: pout_E602dMzgjpDC
      responses:
        '200':
          description: Refund found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '404':
          description: Refund not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
  /refunds/{id}/update_rfi:
    patch:
      tags:
        - Refund
      summary: Update RFI for Refund
      operationId: updateRfiRefund
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: The unique identifier for the refund.
            example: refu_E602dMzgjpDC
      security:
        - JWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                documents:
                  type: array
                  items:
                    $ref: '#/components/schemas/AttachedDocument'
                    required:
                      - rfi_doc_id
                      - id
              required:
                - documents
      responses:
        '200':
          description: Document attached successfully
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Refund'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
  /refunds/{id}/mock_update_status:
    patch:
      tags:
        - Refund
      summary: Mock update a refund
      description: |
        Mark an in_progress refund as successful
      operationId: mockUpdateRefund
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the refund
          example: refund_E602dMzgjpDC
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  description: >-
                    The new status of the refund. You can only mark a refund as
                    `success`
                  example: success
      responses:
        '200':
          description: Refund updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: |
                      Error message.
                    example: Refund cannot be marked success.
        '404':
          description: Refund not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
      security:
        - JWT: []
  /prices:
    post:
      tags:
        - Price
      summary: Create a new price
      operationId: createPrice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Price'
                - type: object
                  required:
                    - pricing_type
                  oneOf:
                    - properties:
                        pricing_type:
                          enum:
                            - fixed
                      required:
                        - fees_currency
                        - fees_amount
                    - properties:
                        pricing_type:
                          enum:
                            - percentage
                      required:
                        - bps
      responses:
        '201':
          description: Payout created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Price'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
      security:
        - JWT: []
    get:
      tags:
        - Price
      summary: List all prices
      operationId: getPrices
      parameters:
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of prices matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Price'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
      security:
        - JWT: []
  /prices/{id}:
    get:
      tags:
        - Price
      summary: |
        Retrieve a price
      operationId: getPriceById
      security:
        - JWT: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier for the payout.
          example: price_E602dMzgjpDC
      responses:
        '200':
          description: Price found
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Price'
                  - example:
                      bps: null
        '404':
          description: Price not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
  /withdrawals:
    post:
      tags:
        - Withdrawal
      summary: Create a new withdrawal
      operationId: createWithdrawal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWithdrawalRequest'
              required:
                - amount
                - balance_currency
      responses:
        '201':
          description: Withdrawal created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Withdrawal'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
      security:
        - JWT: []
    get:
      tags:
        - Withdrawal
      summary: List all withdrawals
      operationId: getWithdrawals
      parameters:
        - in: query
          name: withdrawal_account_id
          schema:
            type: string
          description: The unique identifier of the beneficiary
          example: accwith_162843c10333
        - in: query
          name: status
          schema:
            type: string
            enum:
              - in_progress
              - success
              - failed
              - action_required
              - cancelled
              - under_review
          description: Status of withdrawal to filter
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of withdrawals matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Withdrawal'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
      security:
        - JWT: []
  /withdrawal_accounts:
    get:
      tags:
        - withdrawal_account
      summary: List all Withdrawal Accounts
      description: >
        Returns a list of your Withdrawal accounts. The accounts are returned
        sorted by creation date, with the most recently created account
        appearing first.
      operationId: getWithdrawalAccounts
      parameters:
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of withdrawal accounts matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WithdrawalAccount'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: Error message indicating which parameter was invalid
      security:
        - JWT: []
  /withdrawal_accounts/{id}:
    get:
      tags:
        - withdrawal_account
      summary: Retrieve Withdrawal Account
      description: |
        Returns the respective Withdrawal account.
      operationId: getWithdrawalAccountById
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the withdrawal account
      responses:
        '200':
          description: Withdrawal account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalAccount'
        '404':
          description: Withdrawal account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
      security:
        - JWT: []
  /subscriptions:
    get:
      tags:
        - Subscription
      summary: List subscriptions
      description: >
        Returns a list of subscriptions matching some criteria. The
        subscriptions are returned sorted by creation date, with the most recent
        subscriptions appearing first.
      operationId: getSubscriptions
      parameters:
        - in: query
          name: status
          schema:
            type: string
            enum:
              - created
              - active
              - paused
              - expired
              - failed
              - halted
              - cancelled
              - completed
          description: Filter subscriptions by status.
          example: active
        - in: query
          name: customer_id
          schema:
            type: string
          description: Filter subscriptions by customer ID.
          example: cust_5JU9yv0lGSUP
        - in: query
          name: start_date
          schema:
            type: string
            format: date
          description: >-
            Filter subscriptions with a particular start date, in UTC timezone
            and ISO 8601 format (YYYY-MM-DD).
          example: '2024-01-01'
        - in: query
          name: end_date
          schema:
            type: string
            format: date
          description: >-
            Filter subscriptions with a particular end date, in UTC timezone and
            ISO 8601 format (YYYY-MM-DD).
          example: '2024-12-31'
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of subscriptions matching the criteria.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: Error message indicating why the request failed
      security:
        - JWT: []
    post:
      tags:
        - Subscription
      summary: Create a new subscription
      description: >
        Creates a new subscription for a customer with specified billing plan
        and schedule. The subscription will be created in 'created' status and
        will be activated when the customer completes the first payment.
      operationId: createSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
      responses:
        '201':
          description: Subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          description: Bad Request - validation error or invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: Error message describing the validation failure
                    example: Customer not found
      security:
        - JWT: []
  /subscriptions/{id}:
    get:
      tags:
        - Subscription
      summary: Retrieve a subscription by ID
      description: >
        Retrieves the details of a specific subscription by its unique
        identifier.
      operationId: getSubscriptionById
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique identifier of the subscription
          example: sub_5JU9yv0lGSUP
      responses:
        '200':
          description: Subscription details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '404':
          description: Subscription not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Not Found
                  message:
                    type: string
                    example: Subscription not found
      security:
        - JWT: []
  /subscriptions/{id}/pause:
    patch:
      tags:
        - Subscription
      summary: Pause a subscription
      description: >
        Pauses an active subscription. While paused, the subscription will not
        process any payments. A paused subscription can be resumed later using
        the resume endpoint.
      operationId: pauseSubscription
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique identifier of the subscription to pause
          example: sub_5JU9yv0lGSUP
      responses:
        '200':
          description: Subscription paused successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Subscription'
                  - type: object
                    properties:
                      status:
                        example: paused
                      next_payment_date:
                        example: null
        '400':
          description: Bad Request - subscription cannot be paused from current state
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    example: >-
                      Subscription cannot be paused from current state:
                      cancelled
        '404':
          description: Subscription not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Not Found
                  message:
                    type: string
                    example: Subscription not found
      security:
        - JWT: []
  /subscriptions/{id}/resume:
    patch:
      tags:
        - Subscription
      summary: Resume a paused subscription
      description: >
        Resumes a paused subscription. Once resumed, the subscription will
        continue processing payments according to its original schedule. Only
        subscriptions in 'paused' status can be resumed.
      operationId: resumeSubscription
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique identifier of the subscription to resume
          example: sub_5JU9yv0lGSUP
      responses:
        '200':
          description: Subscription resumed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          description: Bad Request - subscription cannot be resumed from current state
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    example: 'Subscription cannot be resumed from current state: active'
        '404':
          description: Subscription not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Not Found
                  message:
                    type: string
                    example: Subscription not found
      security:
        - JWT: []
  /subscriptions/{id}/cancel:
    patch:
      tags:
        - Subscription
      summary: Cancel a subscription
      description: >
        Cancels a subscription. Once cancelled, the subscription will stop
        processing future payments. This action cannot be undone, but you can
        create a new subscription if needed.
      operationId: cancelSubscription
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique identifier of the subscription to cancel
          example: sub_5JU9yv0lGSUP
      responses:
        '200':
          description: Subscription cancelled successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Subscription'
                  - type: object
                    properties:
                      status:
                        example: cancelled
                      next_payment_date:
                        example: null
        '400':
          description: Bad Request - subscription cannot be cancelled from current state
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    example: >-
                      Subscription cannot be cancelled from current state:
                      completed
        '404':
          description: Subscription not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Not Found
                  message:
                    type: string
                    example: Subscription not found
      security:
        - JWT: []
  /settlements:
    get:
      tags:
        - Settlement
      summary: List all settlements
      description: >
        Returns a list of your settlements. The settlements are returned sorted
        by creation date, with the most recent settlement appearing first.
      operationId: getSettlements
      parameters:
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of withdrawals matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Settlement'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: Error message indicating which parameter was invalid
      security:
        - JWT: []
  /settlements/{id}:
    get:
      tags:
        - Settlement
      summary: Retrieve a settlement
      description: |
        Returns a specific settlement by its unique identifier.
      operationId: getSettlementById
      parameters:
        - in: path
          required: true
          name: id
          schema:
            type: string
          description: The unique identifier of the settlement
          example: setl_6878e266jt1P3
      responses:
        '200':
          description: Settlement found
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Settlement'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: Error message indicating which parameter was invalid
        '404':
          description: Settlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
      security:
        - JWT: []
  /settlements/{id}/transactions:
    get:
      tags:
        - Settlement
      summary: Retrieve transactions linked to a settlement
      description: >
        Returns a list of transactions that are linked to a specific settlement
        by its unique identifier.
      operationId: getTransactionsLinkedToSettlement
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the settlement
          example: setl_6878e266jt1P3
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: List of Transactions matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                  page_meta:
                    $ref: '#/components/schemas/PageMeta'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Bad Request
                  message:
                    type: string
                    description: Error message indicating which parameter was invalid
        '404':
          description: Settlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNotFound'
      security:
        - JWT: []
components:
  securitySchemes:
    JWT:
      description: >-
        Your secret token to access the API. If you don't have one, please
        contact support.
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    AllBalances:
      type: object
      x-tags:
        - Balance
      properties:
        available:
          description: |
            The available balance for all currencies.
          type: array
          items:
            type: object
            properties:
              currency:
                type: string
                format: iso-4217
                description: >
                  The currency code in [ISO
                  4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
                  example, USD.
                example: USD
              amount:
                type: number
                description: >
                  The balance amount in the smallest currency unit. For example,
                  if the amount is $299.00, then 29900 is passed in  this field.
                  In the case of three decimal currencies, such as KWD, BHD and
                  OMR, to represent an amount of 295.991, pass the value as
                  295990. And in the case of zero decimal currencies such as
                  JPY, for amount ￥295, pass the value as 295.
                example: 1000
        pending:
          description: |
            The pending balance for all currencies.
          type: array
          items:
            type: object
            properties:
              currency:
                type: string
                format: iso-4217
                description: >
                  The currency code in [ISO
                  4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
                  example, USD.
                example: USD
              amount:
                type: number
                description: >
                  The balance amount in the smallest currency unit. For example,
                  if the amount is $299.00, then 29900 is passed in  this field.
                  In the case of three decimal currencies, such as KWD, BHD and
                  OMR, to represent an amount of 295.991, pass the value as
                  295990. And in the case of zero decimal currencies such as
                  JPY, for amount ￥295, pass the value as 295.
                example: 1000
    Money:
      type: object
      properties:
        amount:
          type: number
          description: >
            A positive integer representing the smallest currency unit.  For
            example, if the amount is $299.00, then pass 29900 in this field. 
            In the case of three decimal currencies, such as KWD, BHD and OMR,
            to represent an amount of 295.991, pass the value as 295990.  And in
            the case of zero decimal currencies such as JPY, for amount ￥295,
            pass the value as 295.
          example: 1000
        currency:
          type: string
          format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example,
            USD.
          example: USD
    ConversionRate:
      type: object
      x-tags:
        - ConversionRate
      properties:
        currency:
          type: string
          format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example,
            USD.
          example: USD
        rate:
          type: number
          description: >
            The the conversion rate used for the currency(ies) for a given
            transaction.
          example: 1.4
    BalanceConversion:
      type: object
      x-tags:
        - balance_conversions
      properties:
        id:
          type: string
          format: string
          readOnly: true
          description: |
            The unique identifier for the balance balance.
          example: conv_6776d57dnbTWj
        from:
          type: object
          $ref: '#/components/schemas/Money'
          description: |
            the amount and currency of the balance used for conversion
        to:
          type: object
          $ref: '#/components/schemas/Money'
          description: |
            the amount and currency of the balance after conversion
        fees:
          type: object
          $ref: '#/components/schemas/Money'
          description: |
            Total fees for the conversion
        mid_market_rate:
          type: object
          $ref: '#/components/schemas/ConversionRate'
          description: |
            The mid-market rate at the time of conversion
        status:
          type: string
          readOnly: true
          enum:
            - success
            - failed
            - pending
          description: |
            The status of the balance conversion.
          example: success
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: |
            The date and time the balance conversion was created.
          example: '2021-01-01T00:00:00Z'
    PageMeta:
      type: object
      properties:
        current:
          type: integer
          description: |
            The current page number.
          example: 2
        previous:
          type:
            - integer
            - 'null'
          description: |
            The previous page number.
          example: 1
        next:
          type:
            - integer
            - 'null'
          description: |
            The next page number.
          example: 3
        per_page:
          type: integer
          description: |
            The number of items per page.
          example: 20
        pages:
          type: integer
          description: |
            The total number of pages.
          example: 10
        count:
          type: integer
          description: |
            The total number of items.
          example: 200
    BankAccountValidation:
      type: object
      x-tags:
        - bank_account_validation
      properties:
        id:
          type: string
          readOnly: true
          description: |
            The unique identifier for the bank account validation.
          example: aval_5JU9yv0lGSUP
        status:
          type: string
          enum:
            - success
            - failed
          description: >
            The status of the bank account validation. This does not mean the
            bank account is valid or invalid. It means the validation process
            was successful or failed.
        validation_message:
          type: string
          description: |
            The message returned by the bank account validation process.
          example: The account is registered to John Doe
        fee_charged:
          $ref: '#/components/schemas/Money'
          description: |
            The fee charged for the bank account validation process.
    BankAccount:
      type: object
      x-tags:
        - bank_account
      properties:
        country:
          type: string
          format: iso-3166-1-alpha-3, case-insensitive
          description: >
            The country where the customer is located. Country should be sent as
            a [ISO 3166-1
            alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
          example: Ind
        holder_name:
          type: string
          description: |
            The name of the account holder.
          example: John Doe
        account_number:
          type: string
          description: |
            The account number of the bank account as provided by the bank.
          example: '987654321001'
        bic_primary:
          type: string
          description: >
            The primary BIC of the bank account. This is the BIC of the bank
            where the account is held. This is also known as the SWIFT code.
          example: QWERIN000
        bic_secondary:
          type: string
          description: >
            The `local routing code` or `domestic clearing code` of the bank
            account. For reference, this is the `IFSC` code in India, `SORT` in
            UK, `ABA` in the US, etc.
          example: YESB0000002
    Beneficiary:
      type: object
      x-tags:
        - Beneficiary
      properties:
        id:
          type: string
          readOnly: true
          description: |
            The unique identifier for the beneficiary.
          example: bene_5JU9yv0lGSUP
        holder_name:
          type: string
          description: |
            The name of the beneficiary.
          example: Test Arts & Crafts Pvt Ltd
        account_number:
          type: string
          description: |
            The account number of the beneficiary.
          example: '1234567890'
        bank_name:
          type: string
          description: |
            The name of the bank where the account is held.
          example: Yes Bank
        beneficiary_type:
          type: string
          enum:
            - individual
            - business
          description: |
            The type of beneficiary
        bic_primary:
          type: string
          description: >
            The primary BIC of the bank account. This is the BIC of the bank
            where the account is held. This is also known as the SWIFT code.
          example: QWERIN000
        bic_secondary:
          type: string
          description: >
            The `local routing code` or `domestic clearing code` of the bank
            account. For reference, this is the `IFSC` code in India, `SORT` in
            UK, `ABA` in the US, etc.
          example: YESB0000002
        email:
          type: string
          format: email
          description: |
            The email address of the beneficiary.
          example: prabhat+beneficiaryArt@glomopay.com
        address_line1:
          type: string
          description: |
            The street address of the beneficiary.
          example: 123 Main St
        address_line2:
          type: string
          description: |
            The second line of street address of the beneficiary.
          example: Near Apts
        city:
          type: string
          description: |
            The city where the beneficiary is located.
          example: Anytown
        state:
          type: string
          description: |
            The state where the beneficiary is located.
          example: Anystate
        country:
          type: string
          format: iso-3166-1-alpha-3
          description: >
            The country where the beneficiary is located. Country should be sent
            as a [ISO 3166-1
            alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
          example: Ind
        pincode:
          type: string
          description: |
            The postal code of the beneficiary's address.
          example: '560048'
        nickname:
          type: string
          description: |
            A nickname for the beneficiary.
          example: Test Beneficiary
        intermediate_bank_name:
          type: string
          description: |
            The name of the intermediate bank, if any.
          example: Intermediate Bank
        intermediate_bank_country:
          type: string
          format: iso-3166-1-alpha-3
          description: >
            The country of the intermediate bank, if any. Country should be sent
            as a [ISO 3166-1
            alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
          example: IND
        intermediate_bank_swift_code:
          type: string
          description: |
            The SWIFT code of the intermediate bank, if any.
          example: INTBANKSWIFT
        created_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the beneficiary was created
          example: '2021-06-01T12:00:00Z'
        updated_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the beneficiary was last updated
          example: '2021-06-01T12:00:00Z'
    EntityNotFound:
      type: object
      properties:
        error:
          type: string
          enum:
            - Not found
        message:
          type: string
          description: Entity not found
          enum:
            - Entity not found
    Customer:
      type: object
      x-tags:
        - Customer
      properties:
        id:
          type: string
          readOnly: true
          description: |
            The unique identifier for the customer.
          example: cust_5JU9yv0lGSUP
        name:
          type: string
          description: |
            The name of the customer.
          example: Prabhat's Arts & Crafts Pvt Ltd
        customer_type:
          type: string
          enum:
            - individual
            - business
          description: |
            The type of customer
        email:
          type: string
          format: email
          description: |
            The email address of the customer.
          example: prabhat+customerArt@glomopay.com
        phone:
          type: string
          description: |
            The phone number of the customer, with country code
          example: +91-9023456789
        address:
          type: string
          description: |
            The street address of the customer.
          example: 123 Main St
        city:
          type: string
          description: |
            The city where the customer is located.
          example: Anytown
        state:
          type: string
          description: |
            The state where the customer is located.
          example: Anystate
        country:
          type: string
          format: iso-3166-1-alpha-3
          description: >
            The country where the customer is located. Country should be sent as
            a [ISO 3166-1
            alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
          example: Ind
        pincode:
          type: string
          description: >
            The postal code/pincode of the customer's address. [List of
            countries where pincode is
            mandatory](/api-documentation/countries#countries-requiring-pincode)
            are listed here.
          example: '560048'
        status:
          type: string
          readOnly: true
          description: |
            The status of the customer.
          example: active
        created_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the customer was created
          example: '2021-06-01T12:00:00Z'
        updated_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the customer was last updated
          example: '2021-06-01T12:00:00Z'
    DocumentResponse:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: |
            The unique identifier for the Document.
          example: doc_nYUqLpuYQ0M8
        document_name:
          type: string
          description: |
            The name of document
          example: invoice
        file_name:
          type: string
          readOnly: true
          description: |
            The name of the file you uploaded.
          example: invoice_BC8tFdE.pdf
        status:
          type: string
          readOnly: true
          description: >
            The status of file you uploaded. Values can be uploaded, approved
            and rejected.
          example: uploaded
        created_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the document was created
          example: '2021-06-01T12:00:00Z'
        updated_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the document was last updated
          example: '2021-06-01T12:00:00Z'
    Product:
      type: object
      description: |
        Details of the product that the payment is related to.
      properties:
        name:
          type: string
          description: Name of the product
        description:
          type: string
          description: Description of the product
      required:
        - name
      example:
        name: ShieldGuard Insurance
        description: >-
          Flexible insurance for belongings, travel, and digital assets; easy to
          manage
    Orders:
      type: object
      x-tags:
        - Orders
      properties:
        id:
          type: string
          format: string
          readOnly: true
          description: |
            The unique identifier for the order.
          example: order_678a4c88hpAjf
        customer_id:
          type: string
          description: |
            The unique identifier of customer linked to order.
          example: cust_E602dMzgjpDC
        document_id:
          type: string
          description: >
            The unique identifier of document linked to order. This document
            entity should contain the required documents to process incoming
            payments. Refer this [Document](#tag/Document) entity for more
            details.
          example: doc_nYUqLpuYQ0M8
        status:
          type: string
          readOnly: true
          enum:
            - active
            - paid
            - failed
            - action_required
            - cancelled
            - under_review
          description: |
            The status of the Order.
          example: success
        currency:
          type: string
          format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported
            currencies: USD,EUR and GBP.
          example: USD
        amount:
          type: number
          minimum: 1
          description: >
            The amount you want to receive, a positive integer representing the
            smallest currency unit. For example, if the amount is $299.00, then
            pass 29900 in this field. In the case of three decimal currencies,
            such as KWD, BHD and OMR, to represent an amount of 295.991, pass
            the value as 295990. And in the case of zero decimal currencies such
            as JPY, for amount ￥295, pass the value as 295.
          example: 1000
        purpose_code:
          type: string
          description: |
            Purpose code for why you want to receive this payment
          example: P1401
        invoice_number:
          type: string
          description: |
            Number/Id of the invoice submitted with order.
          example: RG12FF590
        invoice_description:
          type: string
          description: |
            Description about the invoice submitted with order
          example: Payment requested for services provided
        invoice_amount:
          type: number
          description: >
            The amount in cents for which invoice was generated. It can be more 
            than the amount requested in this order
          example: 1000
        product:
          $ref: '#/components/schemas/Product'
        notes:
          type: object
          description: |
            Any additional notes for the order
          example:
            key1: value1
            key2: value2
        created_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the order was created
          example: '2021-06-01T12:00:00Z'
        updated_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the order was last updated
          example: '2021-06-01T12:00:00Z'
    PaymentLink:
      type: object
      x-tags:
        - payment_link
      properties:
        id:
          type: string
          format: string
          readOnly: true
          description: |
            The unique identifier for the payment link.
          example: payin_678a4c88hpAjf
        customer_id:
          type: string
          description: |
            The unique identifier of customer linked to payment_link.
          example: cust_E602dMzgjpDC
        document_id:
          type: string
          description: >
            The unique identifier of document linked to payment_link. This
            document entity should contain the required documents to process
            incoming payments. Refer this [Document](#tag/Document) entity for
            more details.
          example: doc_nYUqLpuYQ0M8
        status:
          type: string
          readOnly: true
          enum:
            - active
            - paid
            - failed
            - action_required
            - cancelled
            - partially_paid
            - under_review
            - expired
          description: |
            The status of the payment_link.
          example: success
        currency:
          type: string
          format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported
            currencies: USD,EUR and GBP.
          example: USD
        amount:
          type: number
          minimum: 1
          description: >
            The amount you want to receive, a positive integer representing the
            smallest currency unit. For example, if the amount is $299.00, then
            pass 29900 in this field. In the case of three decimal currencies,
            such as KWD, BHD and OMR, to represent an amount of 295.991, pass
            the value as 295990. And in the case of zero decimal currencies such
            as JPY, for amount ￥295, pass the value as 295.
          example: 1000
        purpose_code:
          type: string
          description: |
            Purpose code for why you want to receive this payment
          example: P1401
        invoice_number:
          type: string
          description: |
            Number/Id of the invoice submitted with payment_link.
          example: RG12FF590
        invoice_description:
          type: string
          description: |
            Description about the invoice submitted with payment_link
          example: Payment requested for services provided
        expires_at:
          type: string
          format: timestamp
          description: >
            Date when the payment_link will expire. Expiry can not be less than
            or equal  to current date and can be upto 6 months in future.
          example: '2025-02-15T00:00:00.000Z'
        last_reminder_sent_at:
          type: string
          format: timestamp
          readOnly: true
          description: >
            Last time when the customer was reminded to complete the payment by 
            visiting the link
          example: '2024-09-13T06:32:34.340Z'
        invoice_amount:
          type: number
          description: >
            The amount in cents for which invoice was generated. It can be more 
            than the amount requested in this payment_link
          example: 1000
        payment_link:
          type: string
          readOnly: true
          description: >
            Sharable link which should be shared with customer you want to
            receive  money from. ``` This link gets generated only after the
            payin has been reviewed and moved to in_progress ```
          example: >-
            https://staging-api.glomopay-eng.com/v1/payin/pl/8f31597d-e085-497a-b80f-ae97ea9422a0
        reminder_frequency:
          type: number
          description: >
            The frequency at which you want to remind customers, valid values
            are 1(remind everyday), 2(remind every alternate day), 7(remind
            every week), 14(remind every alternate week).
          example: 7
        price_id:
          type: string
          description: >
            The price_id of the price to be used for the payment link.  Note: If
            you are a platform user then price_id is a required field.
          example: price_E602dMzgjpDC
        product:
          $ref: '#/components/schemas/Product'
        created_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the payment_link was created
          example: '2021-06-01T12:00:00Z'
        updated_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the payment_link was last updated
          example: '2021-06-01T12:00:00Z'
    AttachedDocument:
      type: object
      properties:
        id:
          type: string
          description: |
            The unique identifier for the Document.
          example: doc_nYUqLpuYQ0M8
        type:
          type: string
          readOnly: true
          description: |
            The type of the Document.
          example: invoice
        status:
          type: string
          readOnly: true
          enum:
            - pending
            - uploaded
            - rejected
            - approved
        rfi_doc_id:
          type:
            - string
            - 'null'
          description: >
            The unique identifier for the RFI Document. This will be `null` if
            the document is not an RFI Document.
          example: rfidoc_nYUqLpuYQ0M8
    Payout:
      type: object
      x-tags:
        - Payout
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: |
            The unique identifier for the payin.
          example: payout_DdWp_HUbOnlg
        status:
          type: string
          readOnly: true
          description: |
            The status of the payout.
          example: success
        destination_amount:
          type: number
          minimum: 1
          description: >
            The amount the beneficiary will receive, expressed in the smallest
            unit of the specified currency (e.g., cents for USD, paisa for
            INR). 
                  For example, 1000 represents $10.00 in USD. The actual currency is determined by the currency field. Note: "cents" is used generically to denote 
                  the minimal currency unit, not necessarily USD.
          example: 1000
        destination_currency:
          type: string
          format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example,
            USD.
          example: USD
        source_amount:
          type: number
          minimum: 1
          description: >
            The amount you intend to send, also specified in the smallest unit
            of the selected currency. For example, 1000 equates to $10.00 in
            USD. The currency field determines which currency is used. As with
            destination_amount, "cents" is a placeholder for the minimal unit,
            not specifically USD.
          example: 1000
        source_currency:
          type: string
          format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example,
            USD.
          example: USD
        beneficiary_id:
          type: string
          format: uuid
          description: |
            The unique identifier for the beneficiary.
          example: bene_5JU9yv0lGSUP
        documents:
          type: array
          items:
            $ref: '#/components/schemas/AttachedDocument'
          description: |
            The attached documents for the payout.
        purpose_code:
          type: string
          description: |
            Purpose code for why you want to receive this payment
          example: S0017
        mid_market_rate:
          type: number
          readOnly: true
          example: 1
          description: |
            The mid-market rate at the time of payout creation.
        fees:
          type: object
          readOnly: true
          properties:
            fx:
              type: object
              properties:
                currency:
                  type: string
                  format: iso-4217
                  description: The currency code for the FX fee
                  example: USD
                amount:
                  type: number
                  description: The amount of the FX fee
                  example: 200
              description: The foreign exchange fees applied to the payout
            transaction:
              type: object
              properties:
                currency:
                  type: string
                  format: iso-4217
                  description: The currency code for the transaction fee
                  example: USD
                amount:
                  type: number
                  description: The amount of the transaction fee
                  example: 100
              description: The transaction fees applied to the payout
          description: |
            The fees applied to this payout
        created_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the payout was created
          example: '2021-06-01T12:00:00Z'
        updated_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the payout was last updated
          example: '2021-06-01T12:00:00Z'
    CreatePayoutRequest:
      type: object
      properties:
        source_currency:
          type: string
          format: iso-4217
          description: >
            The currency from which you want the amount to be deducted from
            source balance.
          example: USD
        source_amount:
          type: number
          minimum: 1
          description: >
            The amount you intend to send, also specified in the smallest unit
            of the selected currency. For example, 1000 equates to $10.00 in
            USD. The currency field determines which currency is used. As with
            destination_amount, "cents" is a placeholder for the minimal unit,
            not specifically USD.
          example: 1000
        destination_currency:
          type: string
          format: iso-4217
          description: >
            The currency in which recipient will receive the payout. The
            currency code should be in  [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example,
            USD.
          example: USD
        destination_amount:
          type: number
          minimum: 1
          description: >
            The amount the beneficiary will receive, expressed in the smallest
            unit of the specified currency (e.g., cents for USD, paisa for
            INR).  For example, 1000 represents $10.00 in USD. The actual
            currency is determined by the currency field. Note: "cents" is used
            generically to denote  the minimal currency unit, not necessarily
            USD.
          example: 1000
        beneficiary_id:
          type: string
          format: uuid
          description: |
            The unique identifier for the beneficiary.
          example: bene_5JU9yv0lGSUP
        purpose_code:
          type: string
          description: |
            Purpose code for why you want to receive this payment
          example: S0017
        documents:
          type: array
          items:
            type: string
          description: |
            List of documents to attach to the payout
          example:
            - doc_5JU9yv0lGSUP
            - doc_678a5aa9SKkEr
    MockUpdatePayoutStatusRequest:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: |
            The unique identifier for the payout.
          example: payout_E602dMzgjpDC
        status:
          type: string
          enum:
            - success
            - failed
            - action_required
          description: |
            The status of the payout.
        rfi_document_ids:
          type: array
          items:
            type: string
          description: |
            List of documents to attach to the payout
          example:
            - rfidoc_5JU9yv0lGSUP
            - rfidoc_678a5aa9SKkEr
    Payment:
      type: object
      x-tags:
        - Payment
      properties:
        id:
          type: string
          readOnly: true
          description: |
            The unique identifier for the payment.
          example: payt_E602dMzgjpDC
        payin_id:
          type: string
          nullable: true
          description: >
            The unique identifier for the payin. This is set only for payments
            associated to a payin.
          example: payin_E602dMzgjpDC
        payin_type:
          type: string
          nullable: true
          description: >
            The type of the payin. This is set only for payments associated to a
            payin.
          enum:
            - payment_link
            - orders
            - add_funds
        subscription_id:
          type: string
          nullable: true
          description: >
            The unique identifier for the subscription. This is set only for
            subscription-related payments.
          example: sub_68877570b5zeE
        status:
          type: string
          readOnly: true
          enum:
            - success
            - failed
            - action_required
            - in_progress
          description: |
            The status of the payment.
        payment_currency:
          type: string
          format: iso-4217, case-insensitive
          description: >
            The currency in which the payment is made. The currency code is in
            [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
            example, USD.
          example: USD
        payment_amount:
          type: number
          minimum: 1
          description: >
            The amount of the payment in cents. For example, 1000 cents is
            $10.00. The currency is determined by the `currency` field.
        converted_currency:
          type: string
          format: iso-4217, case-insensitive
          description: >
            The currency in which the payment is made. The currency code is in
            [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
            example, USD.
          example: USD
        converted_amount:
          type: number
          minimum: 1
          description: >
            The amount of the payment in cents. For example, 1000 cents is
            $10.00. The currency is determined by the `currency` field.
        purpose_code:
          type: string
          description: >
            The purpose code of the payment. This should match the purpose code
            of the payin.
          example: S0001
        transaction_reference_number:
          type: string
          description: |
            The transaction reference number. This should match the payin id.
          example: payin_E602dMzgjpDC
        sender_name:
          type: string
          description: |
            The name of the sender.
          example: John Doe
        metadata:
          type: object
          additionalProperties: true
          description: |
            Additional metadata for the payment.
        error_message:
          type: string
          readOnly: true
          description: |
            The error message, if any.
        error_code:
          type: string
          readOnly: true
          description: >
            The error code for the respective error. Error code mappings can be
            found in the [product
            guide](../../../../product-guide/payin/payment#error-codes).
          example: PAYMENT_DECLINED
        error_description:
          type: string
          readOnly: true
          description: |
            The error description corresponding to error code.
          example: >-
            The payment attempt was declined. This could be due to issuer
            rejection, risk assessment, or restrictions on the card or account.
            The customer should contact their bank or try a different payment
            method.
        payment_date:
          type: string
          format: date-time
          description: |
            The date of the payment.
          example: '2024-12-06T11:38:37.130Z'
        fee_bearer:
          type: string
          description: |
            Fee bearer of the payment.
          example: merchant
        created_at:
          type: string
          readOnly: true
          format: date-time
          description: |
            The creation timestamp of the payment.
          example: '2024-12-06T11:38:37.130Z'
        updated_at:
          type: string
          readOnly: true
          format: date-time
          description: |
            The last update timestamp of the payment.
          example: '2024-12-06T11:38:37.130Z'
        customer_id:
          type: string
          description: |
            The unique identifier for the customer.
          example: cust_E602sMzgjpDC
        product_name:
          type: string
          nullable: true
          readOnly: true
          description: |
            The name of the product associated with the payment.
          example: ShieldGuard Insurance
        product_description:
          type: string
          nullable: true
          readOnly: true
          description: |
            The description of the product associated with the payment.
          example: >-
            Simple, monthly insurance plan that covers your basic belongings and
            key digital assets
        country:
          type: string
          format: iso-3166-1-alpha-3, case-insensitive
          description: >
            The country of the sender. Country should be sent as a [ISO 3166-1
            alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
          example: Ind
        ordered_amount:
          type: integer
          description: |
            The ordered amount.
          example: 1000
        ordered_currency:
          type: string
          description: |
            The ordered currency.
          example: USD
        fx_fee:
          $ref: '#/components/schemas/Money'
          description: |
            The foreign exchange fee charged for the payment.
        txn_fee:
          $ref: '#/components/schemas/Money'
          description: |
            The transaction fee charged for the payment.
        documents:
          type: array
          items:
            $ref: '#/components/schemas/AttachedDocument'
          description: |
            The attached documents for the payment.
        settlement_id:
          type: string
          description: >
            A unique identifier generated by Glomo for the settlement batch in
            which this payment is included. This ID can be used to track and
            reconcile payments against corresponding settlements.
        funds_available:
          type: boolean
          description: >
            Indicates whether the funds for this payment are currently available
            with Glomo.


            **Values:**


            - `true` - Funds are available with Glomo and can be included in a
            payout or settlement

            - `false` - Funds are still in transit with Glomo's payment partners
            and are not yet available for use
        payment_method:
          type: object
          description: >
            Specifies the method used by the customer to complete the payment.
            This can include various options such as swift_transfer, card, and
            other payment methods.
          properties:
            type:
              type: string
              enum:
                - swift_transfer
                - card
              description: |
                The type of payment method used for the transaction.
              example: swift_transfer
            id:
              type: string
              description: |
                The unique identifier for the payment method instance.
              example: swift_6883291fT7Rfw
            details:
              type: object
              description: >
                Additional details specific to the payment method type. The
                structure varies based on the payment method type.
              oneOf:
                - title: Swift Transfer Details
                  properties:
                    sender_name:
                      type: string
                      description: >
                        The name of the sender as provided by the payment
                        method.
                      example: Vaibhav LRS
                    sender_country:
                      type: string
                      description: |
                        The country code of the sender.
                      example: IND
                    sender_account_number:
                      type: string
                      description: |
                        The account number of the sender (for bank transfers).
                      example: '5454545454'
                    sender_bank_name:
                      type: string
                      description: |
                        The name of the sender's bank (for bank transfers).
                      example: HDFC Bank
                    remittance_information:
                      type: string
                      nullable: true
                      description: >
                        Additional remittance information provided with the
                        payment.
                      example: PaymentForLrs
                - title: Card Details
                  properties:
                    card_network:
                      type: string
                      description: >
                        The card network (e.g., Visa, Mastercard, American
                        Express).
                      example: Visa
                    card_type:
                      type: string
                      description: |
                        The type of card (e.g., credit, debit).
                      example: credit
                    end_digits:
                      type: string
                      description: >
                        The last few digits of the card number for
                        identification.
                      example: '1234'
                    country_code:
                      type: string
                      description: |
                        The country code associated with the card.
                      example: US
                    card_holder_name:
                      type: string
                      description: |
                        The name of the card holder.
                      example: John Doe
          examples:
            swift_transfer:
              summary: Swift Transfer Payment Method
              value:
                type: swift_transfer
                id: swift_6883291fT7Rfw
                details:
                  sender_name: Vaibhav LRS
                  sender_country: IND
                  sender_account_number: '5454545454'
                  sender_bank_name: HDFC Bank
                  remittance_information: PaymentForLrs
            card:
              summary: Card Payment Method
              value:
                type: card
                id: card_6883291fT7Rfw
                details:
                  card_network: Visa
                  card_type: credit
                  end_digits: '1234'
                  country_code: US
                  card_holder_name: John Doe
        auto_debit:
          type: boolean
          nullable: true
          readOnly: true
          description: >
            Indicates whether the payment was made via auto-debit for
            subscription payments.  Returns `true` if it's an auto-debit
            payment, `false` if it's a manual payment for a subscription,  or
            `null` if the payment is not associated with a subscription.
          example: true
    Refund:
      type: object
      x-tags:
        - Refund
      properties:
        id:
          type: string
          format: string
          readOnly: true
          description: |
            The unique identifier for the refund.
          example: refund_6776d57dnbTWj
        customer_id:
          type: string
          description: |
            The unique identifier of customer linked to refund.
          example: cust_E602dMzgjpDC
        payment_id:
          type: string
          description: |
            The unique identifier of payment linked to refund.
          example: payt_E602dMzgjpDC
        reason:
          type: string
          description: |
            The reason for the refund.
          example: Requested by Customer
        fx_fee:
          $ref: '#/components/schemas/Money'
          description: |
            The foreign exchange fee charged for the refund.
        txn_fee:
          $ref: '#/components/schemas/Money'
          description: |
            The transaction fee charged for the refund.
        documents:
          type: array
          items:
            anyOf:
              - type: object
                description: |
                  The document attached to the refund.
                properties:
                  id:
                    type: string
                    readOnly: true
                    description: |
                      The unique identifier for the Document.
                    example: doc_nYUqLpuYQ0M8
                  type:
                    type: string
                    description: |
                      The type of the document.
                    example: rfi
                  status:
                    type: string
                    enum:
                      - pending
                      - uploaded
                      - approved
                      - rejected
                    description: |
                      The status of the document.
                    example: pending
              - type: object
                description: |
                  The document required to be uploaded to respond to rfi.
                properties:
                  id:
                    type: string
                    readOnly: true
                    description: |
                      The unique identifier for the Document.
                    example: null
                  rfi_doc_id:
                    type: string
                    description: >
                      The identifier that needs to be sent when responding to
                      rfi.
                    example: rfidoc_nYUqLpuYQ0M8
                  type:
                    type: string
                    description: |
                      The type of the document.
                    example: rfi
                  status:
                    type: string
                    enum:
                      - pending
                      - uploaded
                      - approved
                      - rejected
                    description: |
                      The status of the document.
                    example: pending
        status:
          type: string
          readOnly: true
          enum:
            - success
            - failed
            - action_required
            - pending
            - under_review
          description: |
            The status of the refund.
          example: success
        currency:
          type: string
          format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example,
            USD.
          example: USD
        amount:
          type: number
          minimum: 1
          description: >
            The amount you want to receive in cents. For example, 1000 cents is
            $10.00.  The currency is determined by the `currency` field. `Cents`
            is a general  term for the smallest unit of currency in any
            currency. It does not  necessarily mean USD cents.
          example: 1000
        created_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the refund was created
          example: '2021-06-01T12:00:00Z'
        updated_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the refund was last updated
          example: '2021-06-01T12:00:00Z'
    Price:
      type: object
      x-tags:
        - Price
      properties:
        id:
          type: string
          readOnly: true
          description: |
            The unique identifier for the payin.
          example: price_DdWp_HUbOnlg
        pricing_type:
          type: string
          enum:
            - fixed
            - percentage
          description: |
            The type of pricing to be applied.
          example: fixed
        fees_amount:
          type: number
          minimum: 1
          description: >
            The amount that will be deducted from your balance for this pricing.
            A positive integer representing the smallest currency unit. For
            example, if the amount is $299.00, then pass 29900 in this field. In
            the case of three decimal currencies, such as KWD, BHD and OMR, to
            represent an amount of 295.991, pass the value as 295990. And in the
            case of zero decimal currencies such as JPY, for amount ￥295, pass
            the value as 295
          example: 1000
        fees_currency:
          type: string
          format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format.
          example: USD
        bps:
          type: number
          minimum: 1
          description: |
            Basis points for the pricing.
          example: 1000
        created_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the payin was created
          example: '2021-06-01T12:00:00Z'
        updated_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the payin was last updated
          example: '2021-06-01T12:00:00Z'
    Balance:
      type: object
      x-tags:
        - Balance
      properties:
        currency:
          type: string
          format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example,
            USD.
          example: USD
        amount:
          type: number
          description: >
            The balance amount in the smallest currency unit. For example, if
            the amount is $299.00, then 29900 is passed in  this field. In the
            case of three decimal currencies, such as KWD, BHD and OMR, to
            represent an amount of 295.991, pass the value as 295990. And in the
            case of zero decimal currencies such as JPY, for amount ￥295, pass
            the value as 295.
          example: 1000
    Withdrawal:
      type: object
      x-tags:
        - Withdrawal
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: |
            The unique identifier for the withdrawal.
          example: payout_DdWpHUbOnlg
        status:
          type: string
          enum:
            - in_progress
            - success
            - failed
            - action_required
            - cancelled
            - under_review
          readOnly: true
          description: |
            The status of the withdrawal.
          example: success
        currency:
          type: string
          format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example,
            USD.
          example: USD
        amount:
          type: number
          minimum: 1
          description: >
            The amount you want to receive in cents. For example, 1000 cents is
            $10.00.  The currency is determined by the `currency` field. `Cents`
            is a general  term for the smallest unit of currency in any
            currency. It does not  necessarily mean USD cents.
          example: 1000
        withdrawal_account_id:
          type: string
          format: uuid
          description: |
            The unique identifier for the withdrawal account.
          example: accwith_5JU9yv0lGSUP
        payment_method:
          type: string
          enum:
            - bank_transfer
          description: |
            The payment method to use for the withdrawal.
          example: bank_transfer
        balance_used:
          type: array
          readOnly: true
          items:
            type: object
            $ref: '#/components/schemas/Balance'
          description: >
            The amount in cents that was deducted from your balance for this
            withdrawal.
        purpose_code:
          type: string
          description: |
            Purpose code for why you want to receive this payment
          example: S0017
        mid_market_rate:
          type: array
          readOnly: true
          items:
            type: object
            $ref: '#/components/schemas/ConversionRate'
          description: |
            The mid-market rate at the time of withdrawal creation.
        fx_fees:
          type: array
          readOnly: true
          items:
            type: object
            $ref: '#/components/schemas/Balance'
          description: |
            The FX fees applied to the withdrawal.
        txn_fees:
          type: array
          readOnly: true
          items:
            type: object
            $ref: '#/components/schemas/Balance'
          description: |
            The transaction fees applied to the withdrawal.
        created_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the payin was created
          example: '2021-06-01T12:00:00Z'
        updated_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the payin was last updated
          example: '2021-06-01T12:00:00Z'
    CreateWithdrawalRequest:
      type: object
      properties:
        amount:
          type: number
          minimum: 1
          description: |
            The amount you want to receive.
          example: 1000
        balance_currency:
          type: string
          format: iso-4217
          description: >
            The balance which you want use to make the withdrawal. For example,
            USD. This is the currency in which the amount will be deducted from
            your balance. The target currency in which the amount will be
            settled will be the currency set in the withdrawal account.
          example: USD
        withdrawal_account_id:
          type: string
          description: |
            The unique identifier for the withdrawal account.
          example: accwith_5JU9yv0lGSUP
    WithdrawalAccount:
      type: object
      x-tags:
        - withdrawal_account
      properties:
        id:
          type: string
          readOnly: true
          description: |
            The unique identifier for the withdrawal account.
          example: accwith_5JU9yv0lGSUP
        holder_name:
          type: string
          description: |
            The name of the merchant that owns the withdrawal account.
          example: Test Arts & Crafts Pvt Ltd
        account_number:
          type: string
          description: |
            The account number.
          example: '1234567890'
        bank_name:
          type: string
          description: |
            The name of the bank where the account is held.
          example: Yes Bank
        bic_primary:
          type: string
          description: >
            The primary BIC of the bank account. This is the BIC of the bank
            where the account is held. This is also known as the SWIFT code.
          example: QWERIN000
        bic_secondary:
          type: string
          description: >
            The `local routing code` or `domestic clearing code` of the bank
            account. For reference, this is the `IFSC` code in India, `SORT` in
            UK, `ABA` in the US, etc.
          example: YESB0000002
        currency:
          type: string
          format: iso-4217
          description: >
            The currency code in [ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example,
            USD.
          example: USD
        email:
          type: string
          format: email
          description: |
            The email address of the primary user associated with the merchant.
          example: john@mybusiness.com
        address_line1:
          type: string
          description: |
            The street address of the primary merchant user.
          example: 123 Main St
        address_line2:
          type: string
          description: |
            The second line of street address of the primary merchant user.
          example: Near Apts
        city:
          type: string
          description: |
            The city where the primary merchant user is located.
          example: Anytown
        state:
          type: string
          description: |
            The state where the primary merchant user is located.
          example: Anystate
        country:
          type: string
          format: iso-3166-1-alpha-3
          description: >
            The country where the primary merchant user is located. Country
            should be sent as a [ISO 3166-1
            alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
          example: Ind
        pincode:
          type: string
          description: |
            The postal code of the primary merchant user's address.
          example: '560048'
        created_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the withdrawal account was created
          example: '2021-06-01T12:00:00Z'
        updated_at:
          type: string
          format: timestamp
          readOnly: true
          description: |
            Timestamp representing when the withdrawal account was last updated
          example: '2021-06-01T12:00:00Z'
    Amount:
      type: number
      description: >
        The amount in the smallest currency unit. For example, if the amount is
        $299.00, then 29900 is passed in  this field. In the case of three
        decimal currencies, such as KWD, BHD and OMR, to represent an amount of
        295.991, pass the value as 295990. And in the case of zero decimal
        currencies such as JPY, for amount ￥295, pass the value as 295.
      example: 1000
    Currency:
      type: string
      format: iso-4217
      description: >
        The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
        format.
      example: USD
    IntervalType:
      type: string
      description: >-
        Used in combination with interval_count to define the billing cycle
        frequency.
      enum:
        - month
        - year
    IntervalCount:
      type: integer
      description: >
        Number of intervals between a billing cycle, used in combination with
        interval_type.

        Valid combinations:

        - Monthly: interval_type='month', interval_count=1

        - Quarterly: interval_type='month', interval_count=3

        - Half-yearly: interval_type='month', interval_count=6

        - Yearly: interval_type='year', interval_count=1
      enum:
        - 1
        - 3
        - 6
    Subscription:
      x-tags:
        - Subscription
      type: object
      description: >-
        Subscription resource represents a recurring billing agreement for a
        customer
      properties:
        id:
          type: string
          description: Unique identifier for the subscription.
          example: sub_5JU9yv0lGSUP
        customer_id:
          type: string
          description: Unique identifier of the customer associated with this subscription.
          example: cust_5JU9yv0lGSUP
        product_name:
          type: string
          description: Name of the product being subscribed to.
          example: ShieldGuard Insurance
        product_description:
          type: string
          description: Description of the product.
          example: >-
            Flexible, monthly insurance for belongings, travel, and digital
            assets; easy to manage
        plan_name:
          type: string
          description: Name of the subscription plan.
          example: ShieldGuard Lite
        plan_description:
          type: string
          description: Description of the subscription plan.
          example: >-
            Simple, monthly insurance plan that covers your basic belongings and
            key digital assets
        status:
          type: string
          description: Current status of the subscription.
          enum:
            - created
            - active
            - paused
            - expired
            - failed
            - halted
            - cancelled
            - completed
          example: active
        amount:
          $ref: '#/components/schemas/Amount'
        currency:
          $ref: '#/components/schemas/Currency'
        interval_type:
          $ref: '#/components/schemas/IntervalType'
        interval_count:
          $ref: '#/components/schemas/IntervalCount'
        billing_cycles:
          type: integer
          description: Total number of billing cycles for the subscription.
          example: 12
        start_date:
          type: string
          format: date
          description: >-
            Start date of the subscription in UTC timezone and ISO 8601 format
            (YYYY-MM-DD).
          example: '2025-01-01'
        end_date:
          type: string
          format: date
          description: >-
            The date on which the subscription ends in UTC timezone and ISO 8601
            format (YYYY-MM-DD).
          example: '2025-12-01'
        expires_at:
          type: string
          format: date
          description: >-
            Expiration date for the subscription payment link in UTC timezone
            and ISO 8601 format (YYYY-MM-DD).
          example: '2025-01-07'
        next_payment_date:
          type:
            - string
            - 'null'
          format: date
          description: >-
            Date of the next scheduled payment in UTC timezone and ISO 8601
            format (YYYY-MM-DD).
          example: '2025-02-01'
        subscription_link_url:
          type: string
          format: uri
          description: >-
            URL for the subscription payment page. Your customer can use this
            URL to make the first payment and activate the subscription.
          example: https://checkout.glomopay.com/subscription/sub_5JU9yv0lGSUP
        cancelled_at:
          type:
            - string
            - 'null'
          format: date
          description: >-
            Date when the subscription was cancelled in UTC timezone and ISO
            8601 format (YYYY-MM-DD). This field is null unless the subscription
            status is 'cancelled'.
          example: '2025-01-15'
      required:
        - id
        - customer_id
        - product_name
        - product_description
        - status
        - amount
        - currency
        - interval_type
        - interval_count
        - billing_cycles
        - start_date
        - end_date
        - expires_at
        - subscription_link_url
    CreateSubscriptionRequest:
      type: object
      description: Request payload for creating a new subscription
      properties:
        customer_id:
          type: string
          description: Unique identifier of the customer associated with this subscription.
          example: cust_5JU9yv0lGSUP
        product_name:
          type: string
          maxLength: 128
          description: Name of the product being subscribed to.
          example: ShieldGuard Insurance
        product_description:
          type: string
          maxLength: 512
          description: Description of the product.
          example: >-
            Flexible, monthly insurance for belongings, travel, and digital
            assets; easy to manage
        plan_name:
          type: string
          maxLength: 128
          description: Name of the subscription plan.
          example: ShieldGuard Lite
        plan_description:
          type: string
          maxLength: 512
          description: Description of the subscription plan.
          example: >-
            Simple, monthly insurance plan that covers your basic belongings and
            key digital assets
        amount:
          $ref: '#/components/schemas/Amount'
        currency:
          $ref: '#/components/schemas/Currency'
        interval_type:
          $ref: '#/components/schemas/IntervalType'
        interval_count:
          $ref: '#/components/schemas/IntervalCount'
        billing_cycles:
          type: integer
          minimum: 2
          description: >
            Total number of billing cycles for the subscription. A subscription
            can have a lifetime of 10 years.

            Maximum billing cycles therefore depend on interval:

            - Monthly (interval_type='month', interval_count=1): max 120 cycles

            - Quarterly (interval_type='month', interval_count=3): max 40 cycles

            - Half-yearly (interval_type='month', interval_count=6): max 20
            cycles

            - Yearly (interval_type='year', interval_count=1): max 10 cycles
          example: 12
        start_date:
          type: string
          format: date
          description: >-
            Start date of the subscription in UTC timezone and ISO 8601 format
            (YYYY-MM-DD). Must be today or in the future.
          example: '2025-01-01'
        expires_at:
          type: string
          format: date
          description: >-
            Expiration date for the subscription payment link in UTC timezone
            and ISO 8601 format (YYYY-MM-DD). Must be >= start_date and cannot
            be more than 6 months from start_date.
          example: '2025-01-07'
        notify_customer:
          type: boolean
          description: >-
            Whether to send notification e-mails to customers for subscription
            lifecycle changes.
          example: true
        starts_with_first_payment:
          type: boolean
          description: >-
            Whether the subscription payment schedule should get synchronized
            with the first payment.
          example: true
      required:
        - customer_id
        - product_name
        - product_description
        - amount
        - currency
        - interval_type
        - interval_count
        - billing_cycles
        - start_date
        - expires_at
        - notify_customer
        - starts_with_first_payment
    Settlement:
      type: object
      x-tags:
        - Settlement
      properties:
        id:
          type: string
          readOnly: true
          description: |
            The unique identifier for the settlement.
          example: setl_6878e266jt1P3
        status:
          type: string
          description: |
            The status of the settlement.
          example: success
        payment_method:
          type: string
          description: |
            The payment method used for the settlement.
          example: swift_transfer
        amount:
          type: number
          minimum: 1
          description: >
            The amount of the settlement in cents. For example, 1000 cents is
            $10.00. The currency is determined by the `currency` field.
          example: 1000
        currency:
          type: string
          format: iso-4217, case-insensitive
          description: >
            The currency in which the settlement is made. The currency code is
            in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
            example, USD.
          example: USD
        fees:
          type: object
          description: |
            The fees associated with the settlement.
          properties:
            fx_fee:
              type: object
              description: |
                The foreign-exchange fee charged for the settlement in cents.
              properties:
                amount:
                  type: number
                  minimum: 0
                  description: >
                    The amount of the foreign exchange fee in cents. For
                    example, 1000 cents is $10.00.
                  example: 10
                currency:
                  type: string
                  format: iso-4217, case-insensitive
                  description: >
                    The currency code in [ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
                    example, USD.
                  example: USD
            txn_fee:
              type: object
              description: |
                The transaction fee charged for the settlement in cents.
              properties:
                amount:
                  type: number
                  minimum: 0
                  description: >
                    The amount of the transaction fee in cents. For example,
                    1000 cents is $10.00.
                  example: 10
                currency:
                  type: string
                  format: iso-4217, case-insensitive
                  description: >
                    The currency code in [ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
                    example, USD.
                  example: USD
        utr:
          type: string
          description: |
            The Unique Transaction Reference (UTR) for the settlement.
          example: 1568176960vxp0rj
        created_at:
          type: string
          readOnly: true
          format: date-time
          description: |
            The creation timestamp of the settlement.
          example: '2024-12-06T11:38:37.130Z'
        updated_at:
          type: string
          readOnly: true
          format: date-time
          description: |
            The last update timestamp of the settlement.
          example: '2024-12-06T11:38:37.130Z'
    Transaction:
      type: object
      x-tags:
        - Transaction
      properties:
        id:
          type: string
          readOnly: true
          description: |
            The unique identifier for the transaction.
          example: txn_687f1f8ePcIYg
        source_id:
          type: string
          description: |
            The unique identifier of the source for the transaction.
          example: payt_687f1f833Hdgx
        source_type:
          type: string
          description: |
            The type of the source for the transaction.
          example: payment
        credit:
          type: object
          description: |
            The credit details for the transaction.
          properties:
            amount:
              type: number
              minimum: 0
              description: |
                The amount credited in cents. For example, 1000 cents is $10.00.
              example: 1000
            currency:
              type: string
              format: iso-4217, case-insensitive
              description: >
                The currency code in [ISO
                4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
                example, USD.
              example: USD
        debit:
          type: object
          description: |
            The debit details for the transaction.
          properties:
            amount:
              type: number
              minimum: 0
              description: |
                The amount debited in cents. For example, 1000 cents is $10.00.
              example: 0
            currency:
              type: string
              format: iso-4217, case-insensitive
              description: >
                The currency code in [ISO
                4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
                example, USD.
              example: USD
        fees:
          type: object
          description: |
            The fees associated with the transaction.
          properties:
            fx_fee:
              type: object
              description: |
                The foreign-exchange fee charged for the transaction in cents.
              properties:
                amount:
                  type: number
                  minimum: 0
                  description: >
                    The amount of the foreign exchange fee in cents. For
                    example, 1000 cents is $10.00.
                  example: 10
                currency:
                  type: string
                  format: iso-4217, case-insensitive
                  description: >
                    The currency code in [ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
                    example, USD.
                  example: USD
            txn_fee:
              type: object
              description: |
                The transaction fee charged for the transaction in cents.
              properties:
                amount:
                  type: number
                  minimum: 0
                  description: >
                    The amount of the transaction fee in cents. For example,
                    1000 cents is $10.00.
                  example: 10
                currency:
                  type: string
                  format: iso-4217, case-insensitive
                  description: >
                    The currency code in [ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
                    example, USD.
                  example: USD
        settled_amount:
          type: object
          description: |
            The details of the amount settled in this transaction.
          properties:
            amount:
              type: number
              minimum: 1
              description: |
                The amount settled in cents. For example, 1000 cents is $10.00.
              example: 980
            currency:
              type: string
              format: iso-4217, case-insensitive
              description: >
                The currency code in [ISO
                4217](https://en.wikipedia.org/wiki/ISO_4217) format. For
                example, USD.
              example: USD
        processed_at:
          type: string
          readOnly: true
          format: date-time
          description: |
            The timestamp when the transaction was processed.
          example: '2024-12-06T11:38:37.130Z'
        created_at:
          type: string
          readOnly: true
          format: date-time
          description: |
            The creation timestamp of the transaction.
          example: '2024-12-06T11:38:37.130Z'
        updated_at:
          type: string
          readOnly: true
          format: date-time
          description: |
            The last update timestamp of the transaction.
          example: '2024-12-06T11:38:37.130Z'
  parameters:
    BeforeParam:
      in: query
      name: before
      schema:
        type: string
        format: timestamp
      description: >
        [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp in UTC to
        filter resources created before this time. Use this to avoid `Page
        drift` issue. See [Pagination
        parameters](\./pagination#pagination-parameters) for more details.
      example: '2025-02-18T12:03:44Z'
    AfterParam:
      in: query
      name: after
      schema:
        type: string
        format: timestamp
      description: >
        [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp in UTC to
        filter resources created after this time. Use this to avoid `Page drift`
        issue. See [Pagination parameters](\./pagination#pagination-parameters)
        for more details.
      example: '2025-01-18T12:03:44Z'
    PerPageParam:
      in: query
      name: per_page
      schema:
        type: integer
        default: 20
      description: Number of resources per page. Should be between 1 and 100.
    PageParam:
      in: query
      name: page
      schema:
        type: integer
        default: 1
      description: >-
        Page number for pagination. Starts from 1. Get the next page number from
        the `next` field in the response.
