{
  "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.319"
  },
  "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": [
              null,
              "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."
    }
  ]
}