---
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: '2025-05-22'
servers:
- url: https://api.gigs.com
  description: production
paths:
  "/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
  "/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/{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
components:
  schemas:
    payment:
      type: object
      title: Payment
      description: Payments describe the amount charged for an order or subscription
        using a given payment method.
      properties:
        object:
          type: string
          const: payment
          description: Type of object is always `payment`.
        id:
          type: string
          description: Unique identifier for the payment.
          examples:
          - pay_0SNlurA049MEWV2HRA0slWFuS8DV
        amount:
          type: object
          description: The total amount charged for this payment.
          properties:
            amount:
              type: integer
              description: The price amount in the currency's minor unit, e.g. "cents"
                for many currencies.
              minimum: 0
              examples:
              - 999
            currency:
              type: string
              format: ISO 4217
              description: Three-letter ISO 4217 currency code. Must be a supported
                currency.
              examples:
              - USD
          required:
          - amount
          - currency
          examples:
          - amount: 990
            currency: USD
        attemptedAt:
          type: string
          format: date-time
          description: Time when the payment was last attempted.
          examples:
          - '2021-02-14T19:38:34Z'
        createdAt:
          type: string
          format: date-time
          description: Time when the payment was created.
          examples:
          - '2021-02-14T19:38:34Z'
        disputeClosedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Time when the payment dispute was closed. Only present if the
            payment is disputed.
          examples:
          - '2021-02-14T19:38:34Z'
        disputeOutcome:
          type:
          - string
          - 'null'
          enum:
          -
          - lost
          - won
          description: The outcome of a payment dispute. Only present if the payment
            is disputed.
        failedAttempts:
          type: integer
          description: The number of failed payment attempts so far.
          minimum: 0
          examples:
          - 3
        failureCode:
          type:
          - string
          - 'null'
          description: An error code indicating the reason for the payment failure.
            Only present if the payment failed.
          examples:
          - paymentCardDeclined
        failureMessage:
          type:
          - string
          - 'null'
          description: A human-readable message indicating the reason for the payment
            failure. Only present if the payment failed.
          examples:
          - The card has been declined.
        method:
          type:
          - object
          - 'null'
          description: Payment methods are used to process payments for subscriptions
            and orders.
          properties:
            object:
              type: string
              const: paymentMethod
              description: Type of object is always `paymentMethod`.
            id:
              type: string
              description: Unique identifier for the payment method.
              examples:
              - pm_1IHCiiI2m82Dc6YnhqGWH6JX
            brand:
              type:
              - string
              - 'null'
              enum:
              - amex
              - diners
              - discover
              - jcb
              - mastercard
              - unionpay
              - visa
              - unknown
              description: Card brand. Only available for type `card`.
              examples:
              - visa
            createdAt:
              type: string
              format: date-time
              description: Time when the payment method was created.
              examples:
              - '2021-02-14T19:38:34Z'
            last4:
              type:
              - string
              - 'null'
              description: The last four digits of the card. Only available for type
                `card`.
              examples:
              - '4242'
            provider:
              type: string
              const: stripe
              description: The provider of the payment method. Currently only `stripe`
                is supported.
            status:
              type: string
              enum:
              - available
              - requiresConfirmation
              description: "The status of the payment method. It can have one of the
                following values:\n\n        - `available`: The payment method is
                available for processing payments.\n        - `requiresConfirmation`:
                The payment method requires user confirmation before being able to
                process payments.\n      "
              examples:
              - available
            type:
              type: string
              enum:
              - card
              - applePay
              - googlePay
              description: Type of the payment method.
              examples:
              - card
            user:
              type: string
              description: Unique identifier for the user of the payment method.
              examples:
              - usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
          required:
          - object
          - id
          - brand
          - last4
          - provider
          - status
          - type
          - user
          - createdAt
        reason:
          type: string
          enum:
          - subscriptionCreation
          - subscriptionRenewal
          - other
          description: "The reason for this payment. It can have one of the following
            values:\n\n        - `subscriptionCreation`: The payment is due to a new
            subscription.\n        - `subscriptionRenewal`: The payment is due to
            a recurring subscription renewal.\n        - `other`: The invoice is not
            related to a subscription but due an e.g. one-time addon.\n      "
        references:
          type: array
          description: List of payment references. Supported reference types are `order`
            and `subscription`.
          items:
            type: object
            properties:
              object:
                type: string
                enum:
                - order
                - subscription
                - subscriptionAddon
                description: The type of the referenced object.
              id:
                type: string
                description: Unique identifier of the referenced object.
                examples:
                - ord_0SNlurA049MEWV0SiRFOw0dmChqN
            required:
            - object
            - id
        refunded:
          type: object
          description: The total amount refunded from this payment.
          properties:
            amount:
              type: integer
              description: The price amount in the currency's minor unit, e.g. "cents"
                for many currencies.
              minimum: 0
              examples:
              - 999
            currency:
              type: string
              format: ISO 4217
              description: Three-letter ISO 4217 currency code. Must be a supported
                currency.
              examples:
              - USD
          required:
          - amount
          - currency
          examples:
          - amount: 0
            currency: USD
        refundedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Time when the payment was fully refunded. Only present if the
            payment was refunded.
          examples:
          - '2021-02-14T19:38:34Z'
        status:
          type: string
          enum:
          - succeeded
          - requiresConfirmation
          - failed
          - refunded
          - disputed
          - requiresPaymentMethod
          description: "The status of the payment. It can have one of the following
            values:\n\n        - `succeeded`: The payment was completed successfully.\n
            \       - `failed`: The payment failed. Payments are retried automatically
            for up to 3 weeks.\n        - `refunded`: The payment was fully refunded.
            Partially refunded payments do not have this status.\n        - `disputed`:
            The payment is under dispute.\n        - `requiresConfirmation`: The payment
            requires user confirmation before being processed.\n        - `requiresPaymentMethod`:
            The payment is awaiting for a payment method to be attached.\n      "
        user:
          "$ref": https://api.gigs.com/openapi/core.yaml#/components/schemas/user
      required:
      - object
      - id
      - amount
      - disputeOutcome
      - failedAttempts
      - failureCode
      - failureMessage
      - method
      - reason
      - references
      - refunded
      - status
      - user
      - attemptedAt
      - createdAt
      - disputeClosedAt
      - refundedAt
    paymentLink:
      type: object
      title: PaymentLink
      description: |
        Payment links provide a URL to a hosted checkout page where users can pay for invoices. Currently only EBANX is supported as the payment provider.

        <!-- 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
    paymentMethod:
      type: object
      title: PaymentMethod
      description: Payment methods are used to process payments for subscriptions
        and orders.
      properties:
        object:
          type: string
          const: paymentMethod
          description: Type of object is always `paymentMethod`.
        id:
          type: string
          description: Unique identifier for the payment method.
          examples:
          - pm_1IHCiiI2m82Dc6YnhqGWH6JX
        brand:
          type:
          - string
          - 'null'
          enum:
          - amex
          - diners
          - discover
          - jcb
          - mastercard
          - unionpay
          - visa
          - unknown
          description: Card brand. Only available for type `card`.
          examples:
          - visa
        createdAt:
          type: string
          format: date-time
          description: Time when the payment method was created.
          examples:
          - '2021-02-14T19:38:34Z'
        last4:
          type:
          - string
          - 'null'
          description: The last four digits of the card. Only available for type `card`.
          examples:
          - '4242'
        provider:
          type: string
          const: stripe
          description: The provider of the payment method. Currently only `stripe`
            is supported.
        status:
          type: string
          enum:
          - available
          - requiresConfirmation
          description: "The status of the payment method. It can have one of the following
            values:\n\n        - `available`: The payment method is available for
            processing payments.\n        - `requiresConfirmation`: The payment method
            requires user confirmation before being able to process payments.\n      "
          examples:
          - available
        type:
          type: string
          enum:
          - card
          - applePay
          - googlePay
          description: Type of the payment method.
          examples:
          - card
        user:
          type: string
          description: Unique identifier for the user of the payment method.
          examples:
          - usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
      required:
      - object
      - id
      - brand
      - last4
      - provider
      - status
      - type
      - user
      - 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.
