---
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: '2026-01-29'
servers:
- url: https://api.gigs.com
  description: production
paths: {}
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:
          "$ref": https://api.gigs.com/openapi/core.yaml#/components/schemas/price
          description: The total amount charged for this payment.
          examples:
          - amount: 990
            currency: USD
        attemptedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Time when the payment was last attempted. `null` if the payment
            has never been 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:
          anyOf:
          - "$ref": "#/components/schemas/paymentMethod"
          - type: 'null'
        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:
          "$ref": https://api.gigs.com/openapi/core.yaml#/components/schemas/price
          description: The total amount refunded from this payment.
          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:
          - pending
          - succeeded
          - requiresConfirmation
          - failed
          - refunded
          - disputed
          - requiresPaymentMethod
          description: "The status of the payment. It can have one of the following
            values:\n\n        - `pending`: The payment has been created but not yet
            processed by the payment provider.\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
    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
          - deleted
          - replaced
          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        -
            `deleted`: The payment method has been deleted. This value appears in
            `paymentMethod.deleted` events and in the response to `DELETE /paymentMethods/{id}`;
            deleted payment methods cannot be fetched via GET.\n        - `replaced`:
            The payment method has been replaced by another payment method with the
            same card details. This value appears in payment method events; replaced
            payment methods cannot be fetched via GET.\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 Methods
  description: Operations to manage payment methods.
