---
openapi: 3.1.0
info:
  title: Gigs Payments API
  description: Manage orders, payments, and payment methods within Gigs.
  contact:
    name: Gigs Support
    email: support@gigs.com
  version: '2024-12-20'
servers:
- url: https://api.gigs.com
  description: production
paths:
  "/projects/{project}/paymentLinks/{paymentLink}/cancel":
    parameters:
    - "$ref": https://api.gigs.com/openapi/core.yaml#/components/parameters/project
    - name: paymentLink
      in: path
      description: The unique identifier for the payment link.
      required: true
      schema:
        type: string
        examples:
        - pml_0SNlurA049MEWV1x2CfC8u8im5xU
    post:
      tags:
      - Payment Links
      operationId: PaymentLinksCancel
      summary: Cancel a payment link
      description: |
        Cancels an active payment link. Once canceled, the link can no longer be used for payments.

        <!-- theme: info -->
        > #### Preview
        >
        > This endpoint is currently in preview and might change in the future.
        >
        > We’re excited to hear your feedback and ideas. Please send an email
        > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.
      responses:
        '200':
          description: Returns the canceled payment link.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/paymentLink"
              examples:
                Example:
                  summary: Example
                  value:
                    object: paymentLink
                    id: pml_0SNlurA049MEWV1x2CfC8u8im5xU
                    canceledAt: '2024-08-14T19:40:34Z'
                    completedAt: '2024-08-14T19:40:34Z'
                    createdAt: '2024-08-14T19:38:34Z'
                    ebanx:
                      redirectUrl: https://example.com
                    invoice: inv_0SNlurA049MEWV1QTRqvd18YuG25
                    paymentUrl: https://api.ebanx.com/ws/redirect/execute?hash=64f2
                    status: active
                    type: ebanx
        '404':
          "$ref": https://api.gigs.com/openapi/core.yaml#/components/responses/notFound
  "/projects/{project}/paymentLinks/{paymentLink}":
    parameters:
    - "$ref": https://api.gigs.com/openapi/core.yaml#/components/parameters/project
    - name: paymentLink
      in: path
      description: The unique identifier for the payment link.
      required: true
      schema:
        type: string
        examples:
        - pml_0SNlurA049MEWV1x2CfC8u8im5xU
    get:
      tags:
      - Payment Links
      operationId: PaymentLinksRetrieve
      summary: Retrieve a payment link
      description: |
        Retrieves the details of an existing payment link.

        <!-- theme: info -->
        > #### Preview
        >
        > This endpoint is currently in preview and might change in the future.
        >
        > We’re excited to hear your feedback and ideas. Please send an email
        > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.
      responses:
        '200':
          description: Returns the payment link if it exists.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/paymentLink"
              examples:
                Example:
                  summary: Example
                  value:
                    object: paymentLink
                    id: pml_0SNlurA049MEWV1x2CfC8u8im5xU
                    canceledAt: '2024-08-14T19:40:34Z'
                    completedAt: '2024-08-14T19:40:34Z'
                    createdAt: '2024-08-14T19:38:34Z'
                    ebanx:
                      redirectUrl: https://example.com
                    invoice: inv_0SNlurA049MEWV1QTRqvd18YuG25
                    paymentUrl: https://api.ebanx.com/ws/redirect/execute?hash=64f2
                    status: active
                    type: ebanx
        '404':
          "$ref": https://api.gigs.com/openapi/core.yaml#/components/responses/notFound
  "/projects/{project}/paymentLinks":
    parameters:
    - "$ref": https://api.gigs.com/openapi/core.yaml#/components/parameters/project
    get:
      tags:
      - Payment Links
      operationId: PaymentLinksList
      summary: List all payment links
      description: |
        Returns a list of payment links.

        <!-- theme: info -->
        > #### Preview
        >
        > This endpoint is currently in preview and might change in the future.
        >
        > We’re excited to hear your feedback and ideas. Please send an email
        > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.
      parameters:
      - "$ref": https://api.gigs.com/openapi/core.yaml#/components/parameters/listAfter
      - "$ref": https://api.gigs.com/openapi/core.yaml#/components/parameters/listBefore
      - "$ref": https://api.gigs.com/openapi/core.yaml#/components/parameters/listLimit
      - name: invoice
        in: query
        description: The unique identifier for the invoice to be filtered by.
        schema:
          type: string
          examples:
          - inv_0SNlurA049MEWV1QTRqvd18YuG25
      - name: status
        in: query
        description: A comma-separated list of statuses to be filtered by.
        schema:
          type: array
          items:
            type: string
            enum:
            - active
            - canceled
            - completed
        style: form
        explode: false
      responses:
        '200':
          description: Returns a dictionary with an items property that contains an
            array of payment links.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: list
                    description: Type of object is always `list`.
                  items:
                    type: array
                    description: List of objects of type `paymentLink`.
                    items:
                      "$ref": "#/components/schemas/paymentLink"
                  moreItemsAfter:
                    type:
                    - string
                    - 'null'
                    description: A unique identifier to be used as `after` pagination
                      parameter if more items are available sorted after the current
                      batch of items.
                  moreItemsBefore:
                    type:
                    - string
                    - 'null'
                    description: A unique identifier to be used as `before` pagination
                      parameter if more items are available sorted before the current
                      batch of items.
                required:
                - object
                - items
                - moreItemsAfter
                - moreItemsBefore
              examples:
                Example:
                  summary: Example
                  value:
                    object: list
                    items:
                    - object: paymentLink
                      id: pml_0SNlurA049MEWV1x2CfC8u8im5xU
                      canceledAt: '2024-08-14T19:40:34Z'
                      completedAt: '2024-08-14T19:40:34Z'
                      createdAt: '2024-08-14T19:38:34Z'
                      ebanx:
                        redirectUrl: https://example.com
                      invoice: inv_0SNlurA049MEWV1QTRqvd18YuG25
                      paymentUrl: https://api.ebanx.com/ws/redirect/execute?hash=64f2
                      status: active
                      type: ebanx
                    moreItemsAfter:
                    moreItemsBefore:
        '404':
          "$ref": https://api.gigs.com/openapi/core.yaml#/components/responses/notFound
    post:
      tags:
      - Payment Links
      operationId: PaymentLinksCreate
      summary: Create a payment link
      description: |
        Creates a new payment link for an invoice.

        <!-- theme: info -->
        > #### Preview
        >
        > This endpoint is currently in preview and might change in the future.
        >
        > We’re excited to hear your feedback and ideas. Please send an email
        > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.
      requestBody:
        description: Properties of the new payment link.
        content:
          application/json:
            schema:
              type: object
              properties:
                ebanx:
                  type:
                  - object
                  - 'null'
                  description: The details needed to create a payment link with EBANX.
                    Required for type EBANX.
                  properties:
                    user:
                      type: object
                      description: The user information needed for the payment link.
                      properties:
                        fullName:
                          type: string
                          description: The full name of the user.
                          examples:
                          - Elaine Benes
                        email:
                          type: string
                          description: The email of the user.
                          examples:
                          - elaine@example.com
                        taxNumber:
                          type: string
                          description: The tax number of the user.
                          examples:
                          - 290.063.072-03
                      required:
                      - email
                      - fullName
                      - taxNumber
                    redirectUrl:
                      type: string
                      description: The URL to redirect the user to after the payment
                        has been attempted.
                      examples:
                      - https://example.com
                  required:
                  - user
                invoice:
                  type: string
                  description: The unique identifier of the Invoice the payment link
                    is for.
                  examples:
                  - inv_0SNlurA049MEWV1QTRqvd18YuG25
                type:
                  type: string
                  const: ebanx
                  description: Type describes the provider of the payment link.
                  examples:
                  - ebanx
              required:
              - invoice
              - type
            examples:
              Example - Full:
                summary: Example - Full
                value:
                  ebanx:
                    user:
                      fullName: Elaine Benes
                      email: elaine@example.com
                      taxNumber: 290.063.072-03
                    redirectUrl: https://example.com
                  invoice: inv_0SNlurA049MEWV1QTRqvd18YuG25
                  type: ebanx
              Example - Required:
                summary: Example - Required
                value:
                  invoice: inv_0SNlurA049MEWV1QTRqvd18YuG25
                  type: ebanx
        required: true
      responses:
        '201':
          description: Returns the created payment link.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/paymentLink"
              examples:
                Example:
                  summary: Example
                  value:
                    object: paymentLink
                    id: pml_0SNlurA049MEWV1x2CfC8u8im5xU
                    canceledAt: '2024-08-14T19:40:34Z'
                    completedAt: '2024-08-14T19:40:34Z'
                    createdAt: '2024-08-14T19:38:34Z'
                    ebanx:
                      redirectUrl: https://example.com
                    invoice: inv_0SNlurA049MEWV1QTRqvd18YuG25
                    paymentUrl: https://api.ebanx.com/ws/redirect/execute?hash=64f2
                    status: active
                    type: ebanx
        '403':
          "$ref": https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied
        '422':
          "$ref": https://api.gigs.com/openapi/core.yaml#/components/responses/unprocessableEntity
components:
  schemas:
    paymentLink:
      type: object
      title: PaymentLink
      description: |
        A payment link provides a URL that renders a page for the users to pay for an invoice.

        <!-- theme: info -->
        > #### Preview
        >
        > This schema is currently in preview and might change in the future.
        >
        > We’re excited to hear your feedback and ideas. Please send an email
        > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.
      properties:
        object:
          type: string
          const: paymentLink
          description: Type of object is always `paymentLink`.
        id:
          type: string
          description: Unique identifier for the payment link.
          examples:
          - pml_0SNlurA049MEWV1x2CfC8u8im5xU
        canceledAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Time when the payment link was canceled and became invalid.
          examples:
          - '2024-08-14T19:40:34Z'
        completedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Time when the payment link was used for a payment and thus
            completed.
          examples:
          - '2024-08-14T19:40:34Z'
        createdAt:
          type: string
          format: date-time
          description: Time when the payment link was created.
          examples:
          - '2024-08-14T19:38:34Z'
        ebanx:
          type:
          - object
          - 'null'
          description: The details for an EBANX payment link. Present when type is
            EBANX.
          properties:
            redirectUrl:
              type:
              - string
              - 'null'
              description: The URL the user is redirected to after the payment has
                been attempted.
              examples:
              - https://example.com
          required:
          - redirectUrl
        invoice:
          type: string
          description: The unique identifier of the Invoice the payment link is for.
          examples:
          - inv_0SNlurA049MEWV1QTRqvd18YuG25
        paymentUrl:
          type: string
          description: URL that renders a payment page for the user.
          examples:
          - https://api.ebanx.com/ws/redirect/execute?hash=64f2
        status:
          type: string
          enum:
          - active
          - canceled
          - completed
          description: Status of the payment link.
          examples:
          - active
        type:
          type: string
          const: ebanx
          description: Type describes the provider of the payment link. Currently
            only `EBANX` is supported.
          examples:
          - ebanx
      required:
      - object
      - id
      - ebanx
      - invoice
      - paymentUrl
      - status
      - type
      - canceledAt
      - completedAt
      - createdAt
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
security:
- bearerAuth: []
tags:
- name: Orders
  description: Operations to manage orders.
- name: Payments
  description: Operations to manage payments.
- name: Payment Links
  description: Operations to manage payment links.
- name: Payment Methods
  description: Operations to manage payment methods.
