{
  "openapi": "3.0.1",
  "info": {
    "title": "xPay API Store",
    "description": "",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.xpaycheckout.com"
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "paths": {
    "/balance/payouts": {
      "get": {
        "description": "Retrieve a list of payouts created within a specific time range, with support for filtering and pagination. This endpoint allows you to track and analyse all payout transactions to your account. It's useful for building dashboards, reconciling payouts, or reviewing recent payout transactions programmatically.",
        "parameters": [
          { "$ref": "#/components/parameters/StartTime" },
          { "$ref": "#/components/parameters/EndTime" },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100 },
            "description": "Max items per page (default 10, max 100)",
            "example": 50
          },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": {
            "description": "Successful response with payouts and pagination cursor.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/get-payouts-response" }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    },
    "/balance/payouts/{payoutId}": {
      "get": {
        "description": "Get details of a single payout by payoutId",
        "parameters": [
          {
            "name": "payoutId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Unique identifier of the payout",
            "example": "po_g8jKF4kdSdxlYcX2"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with payout details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/get-payout-response" }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    },
    "/payments/intents": {
      "get": {
        "description": "Retrieve a list of payment intents created within a specific time range, with support for filtering and pagination. This endpoint allows you to track and analyse all payment attempts for your account. It's useful for building dashboards, reconciling payments, or reviewing recent transactions programmatically.",
        "parameters": [
          { "$ref": "#/components/parameters/StartTime" },
          { "$ref": "#/components/parameters/EndTime" },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": {
            "description": "Successful response with payment intents and pagination cursor.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/get-intents-response" }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    },
    "/payments/create-intent": {
      "post": {
        "description": "This API is the first API to be called when the payment flow begins. Through this API, you inform xPay of the intent of the user to pay with all the requisite info about the user.",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" },
          { "$ref": "#/components/parameters/ConnectMerchantId" }
        ],
        "requestBody": {
          "description": "Create Intent",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/create-intent"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Create Intent response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntentDetailsResponse"
                }
              }
            }
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payments/capture-payment": {
      "post": {
        "description": "Captures a payment that was previously authorized by creating an intent with `manualCapture` set to `true`.",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Capture Payment",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/capture-payment-request"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Capture Payment response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/capture-payment-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payments/s2s/charge-raw-card": {
      "post": {
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/charge-raw-card-request"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Charge raw card response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/charge-raw-card-response"
                },
                "examples": {
                  "": {
                    "summary": "",
                    "value": {
                      "nextActionRedirectionURL": "https://pay.xpaycheckout.com/?id=in_gKAqC775RFeXjkGM&secret=7Cduomd3LDV6zimJC7vXwh",
                      "intentId": "in_gKAqB3B2aVbFEtbI"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payments/v2/get-intent/{xIntentId}": {
      "get": {
        "description": "You can use this API to get the status of the transaction that corresponds to a particular intent. This API also returns the masked card info of the payer (if it's a card transaction) and the transaction lifecycle, which includes multiple attempts, failures, and other checkpoints during a transaction.",
        "parameters": [
          {
            "name": "xIntentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "in_fooBOwYsaK50AEfK"
            },
            "description": "Unique identifier of the intent"
          },
          {
            "name": "expand",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": ["charge_attempts", "succeeded_charge"]
              }
            },
            "description": "List of fields to expand in the response. Available options: \n - `charge_attempts` : includes all charge attempts \n - `succeeded_charge` : includes the successful charge details",
            "example": ["charge_attempts", "succeeded_charge"]
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with transaction status and related details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/get-intent-details-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, xIntentId not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payments/merchant/refund": {
      "post": {
        "description": "The Refund APIs allow merchants to process refunds for previously captured payments",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Refund API",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/refund"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Refund API response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/refund-response"
                }
              }
            }
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payments/refunds/{intentId}": {
      "get": {
        "description": "Retrieve a list of refunds for a specific payment intent",
        "parameters": [
          {
            "name": "intentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique identifier of the payment intent",
            "example": "in_fooBOwYsaK50AEfK"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with list of refunds",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/get-refunds-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payments/refund/{refundId}": {
      "get": {
        "description": "Get details of a single refund by refundId",
        "parameters": [
          {
            "name": "refundId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique identifier of the refund",
            "example": "rf_fooBOwYsaK50AEaJ"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with refund details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/refund-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/link/merchant/generate-link": {
      "post": {
        "description": "This API can be used to generate payment links programmatically. Payments links are basically standalone webpages where your customer can make a one time payment.",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Generate Payment Link",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/generate-link"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Generate Payment Link",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/generate-link-response"
                }
              }
            }
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/subscription/create": {
      "post": {
        "description": "",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Create Subscription",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/create-subscription"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Create Subscription response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/create-subscription-response"
                }
              }
            }
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/subscription/get-subscription/{subscriptionId}": {
      "get": {
        "description": "",
        "parameters": [
          {
            "name": "subscriptionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "sub_fooBOwYsaK50AEfK"
            },
            "description": "Unique identifier of the subscription"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with subscription details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/get-subscription-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, xSubscriptionId not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/subscription/merchant/cancel": {
      "post": {
        "description": "",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Cancel Subscription",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/cancel-subscription"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Cancel Subscription response"
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/subscription/merchant/pause": {
      "post": {
        "description": "",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Pause Subscription",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/pause-subscription"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Pause Subscription response"
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/subscription/merchant/unpause": {
      "post": {
        "description": "",
        "requestBody": {
          "description": "Unpause Subscription",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/unpause-subscription"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Unpause Subscription response"
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/subscription/merchant/one-time-charge": {
      "post": {
        "description": "Charge a one-time amount against an existing subscription using its saved payment method.",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Subscription One Time Charge",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/subs-one-time-charge"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Subscription One Time Charge response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/subs-one-time-charge-response"
                },
                "examples": {
                  "success": {
                    "summary": "200 - Success",
                    "value": {
                      "intentId": "in_gKAqR0DjLeOihdTE",
                      "status": "SUCCESS",
                      "errorCode": null,
                      "errorMessage": null
                    }
                  },
                  "failed": {
                    "summary": "200 - Fail",
                    "value": {
                      "intentId": "in_gKAqR0DjLeOihdTE",
                      "status": "FAILED",
                      "errorCode": "card_declined",
                      "errorMessage": "The payment has been declined by the customer's bank."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/subscription/manual-retry": {
      "post": {
        "description": "Manually retry a failed payment for an existing subscription. This operation is only allowed when the subscription is in the `UNPAID` status and is subject to a 4-hour cooldown.",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Manual Retry Subscription",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/subs-manual-retry"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Manual retry response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/subs-manual-retry-response"
                },
                "examples": {
                  "success": {
                    "summary": "200 - Success",
                    "value": {
                      "success": true,
                      "minManualRetryDate": "2026-09-16T12:30:00.000+00:00",
                      "status": "ACTIVE",
                      "errorCode": null,
                      "errorMessage": null
                    }
                  },
                  "failed": {
                    "summary": "200 - Failed retry",
                    "value": {
                      "success": false,
                      "minManualRetryDate": "2026-09-16T12:30:00.000+00:00",
                      "status": "UNPAID",
                      "errorCode": "card_declined",
                      "errorMessage": "The payment has been declined by the customer's bank."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "errorCode": "bad_request",
                  "errorDescription": "Please wait until Wed Sep 16 11:40:29 UTC 2026 before retrying"
                }
              }
            }
          }
        }
      }
    },
    "/subscription/link/merchant/generate-link": {
      "post": {
        "description": "This API can be used to generate subscription links programmatically. Subscription links are basically standalone webpages where your customer can make a subscription payment.",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Generate Subscription Link",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/subscription-link"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Generate Subscription Link",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/subscription-link-response"
                }
              }
            }
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payments/cancel/{xIntentId}": {
      "post": {
        "description": "",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Cancel Payment",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/cancel-payment"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Cancel Payment response"
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/setup-method/create": {
      "post": {
        "description": "Create a new setup method for storing payment methods",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Create Setup Method",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/create-setup-method"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Setup Method created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/create-setup-method-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/setup-method/s2s/create": {
      "post": {
        "description": "Create a new setup method for storing payment methods server to server",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Create S2S Setup Method",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/create-s2s-setup-method"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Setup Method created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/create-setup-method-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/setup-method/{setupMethodId}": {
      "get": {
        "description": "Get details of a setup method",
        "parameters": [
          {
            "name": "setupMethodId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique identifier of the setup method"
          }
        ],
        "responses": {
          "200": {
            "description": "Setup Method details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/get-setup-method-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payments/charge-tokenised-pm": {
      "post": {
        "description": "Charge a payment using a tokenized payment method",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Charge Tokenized Payment Method",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/charge-tokenised-pm"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Payment charged successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/charge-tokenised-pm-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payment-method-token/{paymentMethodTokenId}": {
      "get": {
        "description": "Get details of a payment method token",
        "parameters": [
          {
            "name": "paymentMethodTokenId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique identifier of the payment method token"
          }
        ],
        "responses": {
          "200": {
            "description": "Payment method token details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/get-payment-method-token-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/customer/{customerId}/payment-method-tokens": {
      "get": {
        "description": "Retrieve a list of payment method tokens for a customer created within a specific time range, with support for filtering and pagination. This endpoint allows you to track and analyse all payment method tokens for a customer. It's useful for building dashboards, reconciling payment methods, or reviewing saved payment methods programmatically.",
        "parameters": [
          { "$ref": "#/components/parameters/CustomerId" },
          { "$ref": "#/components/parameters/StartTime" },
          { "$ref": "#/components/parameters/EndTime" },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Offset" },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": { 
              "type": "string"
            },
            "description": "Filter by payment method token status. Valid values: `LIVE`, `DELETED`. Refer payment method token [status](/products/setup-method/overview#payment-method-token-lifecycle) for more details.",
            "example": "LIVE"
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/get-payment-method-tokens-for-customer-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/customer/create": {
      "post": {
        "description": "Create a new customer in the xPay system",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "description": "Create Customer",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/create-customer"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Customer created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/create-customer-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/customer/{customerId}": {
      "get": {
        "description": "Get customer details by customer ID",
        "parameters": [
          { "$ref": "#/components/parameters/CustomerId" }
        ],
        "responses": {
          "200": {
            "description": "Customer details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/get-customer-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payment-method-token/delete": {
    "post": {
        "description": "Delete a payment method token",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
            "description": "Delete Token Request",
            "content": {
                "application/json": {
                    "schema": {
                        "$ref": "#/components/schemas/DeleteTokenisedPMRequest"
                    }
                }
            },
            "required": true
        },
        "responses": {
            "200": {
                "description": "Payment method token deleted successfully"
            },
            "400": {
                "description": "Invalid request",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        }
    }
},
    "/argus/block-fingerprint-by-intent": {
      "post": {
        "description": "Block the card fingerprint associated with a payment intent.",
        "requestBody": {
          "description": "The payment intent whose card fingerprint should be blocked.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/block-fingerprint-by-intent-request"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "No content is returned."
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "intent-status": {
                    "summary": "Intent status does not allow block fingerprint",
                    "value": {
                      "errorCode": "bad_request",
                      "errorDescription": "Intent status does not allow block fingerprint"
                    }
                  },
                  "payment-method": {
                    "summary": "Payment method does not allow block fingerprint",
                    "value": {
                      "errorCode": "bad_request",
                      "errorDescription": "Payment method does not allow block fingerprint"
                    }
                  },
                  "already-blocked": {
                    "summary": "Fingerprint already blocked",
                    "value": {
                      "errorCode": "bad_request",
                      "errorDescription": "Fingerprint already blocked"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/subscription/edit": {
      "post": {
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/edit-subs-request"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Subscription edited successfully"
          },
          "400": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhook": {
      "post": {
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "description": "Create a webhook configuration to receive realtime events for payments, intents, subscriptions, payouts, or setup methods.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/create-webhook-request"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Webhook configuration created successfully. Returns the identifier of the newly created webhook.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/create-webhook-response"
                }
              }
            }
          },
          "204": {
            "description": "Webhook configuration created successfully. No content is returned."
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "description": "Retrieve the list of webhook configurations that are currently active for your account.",
        "responses": {
          "200": {
            "description": "List of webhook configurations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/get-webhooks-response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhook/{webhookConfigId}": {
      "get": {
        "description": "Retrieve a specific webhook configuration by its identifier.",
        "parameters": [
          {
            "name": "webhookConfigId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Identifier of the webhook configuration to retrieve",
            "example": "whc_gKAi2oZN1AeU7BfV"
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook configuration details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/webhook-config"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "description": "Update an existing webhook configuration. Use this to rotate the event signer, change the destination endpoint, or adjust the subscribed event types.",
        "parameters": [
          {
            "name": "webhookConfigId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Identifier of the webhook configuration to update",
            "example": "whc_gKAi2oZN1AeU7BfV"
          },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/create-webhook-request"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Webhook configuration updated successfully. No content is returned."
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "description": "Delete an existing webhook configuration and stop delivery of future events to that endpoint.",
        "parameters": [
          {
            "name": "webhookConfigId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Identifier of the webhook configuration to delete",
            "example": "whc_gKAi2oZN1AeU7BfV"
          },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "responses": {
          "204": {
            "description": "Webhook configuration deleted successfully. No content is returned."
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "block-fingerprint-by-intent-request": {
        "type": "object",
        "required": ["intentId"],
        "properties": {
          "intentId": {
            "type": "string",
            "description": "Unique identifier of the payment intent.",
            "example": "in_gKAqR0DjLeOihdTE"
          }
        }
      },
      "PayoutAmount": {
        "type": "integer",
        "format": "int64",
        "description": "Amount in cents (USD)",
        "example": 30000
      },
      "PayoutStatus": {
        "type": "string",
        "description": "Current status of the payout",
        "enum": ["INITIATED", "SUCCESS", "FAILED"],
        "example": "SUCCESS"
      },
      "Amount": {
        "type": "integer",
        "format": "int64",
        "description": "The amount in lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (The minimum amount should be greater than 1 USD)",
        "example": 2000
      },
      "UpfrontAmount": {
        "type": "integer",
        "format": "int64",
        "description": "An optional amount that merchants can set to be charged to the customer at the time the subscription is activated. This amount replaces the first billing cycle charge — the regular subscription amount is not added on top of it. Regular billing resumes from the next cycle.\n\nThe amount is in the lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (minimum amount should be greater than 1 USD).\n\n**Validation Rules:**\n- Not compatible with `trialPeriodCount` and `trialPeriodInterval` — cannot be provided simultaneously",
        "minimum": 1,
        "example": 200
      },
      "CustomerId": {
        "type": "string",
        "description": "The unique identifier for the customer, generated via the [create-customer API](/developer-resources/endpoints/customer/create-customer). This can be used to associate the payment with a specific customer in your system.",
        "example": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
      },
      "CustomerAddress": {
        "type": "object",
        "properties": {
          "addressLine1": {
            "type": "string",
            "description": "Line 1 of the customer's address",
            "example": "123 Main St"
          },
          "addressLine2": {
            "type": "string",
            "description": "Line 2 of the customer's address",
            "example": "Apt 1"
          },
          "city": {
            "type": "string",
            "description": "City of the customer's address",
            "example": "New York"
          },
          "state": {
            "type": "string",
            "description": "State of the customer's address",
            "example": "NY"
          },
          "country": {
            "type": "string",
            "description": "Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).",
            "example": "US"
          },
          "postalCode": {
            "type": "string",
            "description": "Postal code",
            "example": "2424"
          }
        }
      },
      "CardDetails": {
        "description": "Payment card information collected by you",
        "type": "object",
        "properties": {
          "cardHolderName": {
            "type": "string",
            "description": "Name of the cardholder",
            "example": "John Doe"
          },
          "cardNumber": {
            "type": "string",
            "description": "Full Primary Account Number (PAN)",
            "example": "4000002500000003"
          },
          "expiryMonth": {
            "type": "integer",
            "minimum": 1,
            "maximum": 12,
            "description": "Card expiry month in MM format",
            "example": 1
          },
          "expiryYear": {
            "type": "integer",
            "description": "Card expiry year in YY format",
            "example": 28
          },
          "cvv": {
            "type": "string",
            "description": "Card security code (CVV/CSC).",
            "example": "123"
          },
          "country": {
            "type": "string",
            "description": "Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)) of the country where the card is registered.",
            "example": "US"
          },
          "postalCode": {
            "type": "string",
            "description": "Postal code of the location where the card is registered.",
            "example": "2424"
          }
        },
        "required": ["cardNumber", "expiryMonth", "expiryYear", "cvv"]
      },
      "BillingDetails": {
        "type": "object",
        "description": "Billing details for the customer.",
        "required": ["name", "email", "contactNumber"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Customer's name",
            "example": "John Doe"
          },
          "email": {
            "type": "string",
            "description": "Customer's email address",
            "example": "john.doe@example.com"
          },
          "contactNumber": {
            "type": "string",
            "description": "Customer's contact number ([E.164 format](https://en.wikipedia.org/wiki/E.164)), including the country code (e.g., +1 for US, +44 for UK, +91 for India).",
            "example": "+919123456789"
          },
          "customerAddress": {
            "$ref": "#/components/schemas/CustomerAddress"
          }
        }
      },
      "CustomerReferenceId": {
        "type": "string",
        "description": "Your unique identifier for the customer. This can be used to associate the payment with a specific customer in your system.",
        "example": "eTfd3Jq1tZxPjYVhRQW2r3"
      },
      "ReceiptId": {
        "type": "string",
        "description": "Your identifier of the order",
        "example": "order123"
      },
      "PaginationOffset": {
        "type": "string",
        "description": "Pagination cursor for fetching the next page of results. Use this exact string as the `offset` parameter in your next API request. When this field is missing or null, you've reached the end of the results.\n\nFor detailed pagination implementation guide, see [Pagination Guide](/developer-resources/pagination)."
      },
      "SucceededAt": {
        "type": "integer",
        "description": "Epoch timestamp in milliseconds of when the payment was successfully completed",
        "example": 1727340330123
      },
      "CreatedAt": {
        "type": "integer",
        "description": "Epoch timestamp in milliseconds of when the intent was created",
        "example": 1727340330123
      },
      "PaymentMethodTokenCreatedAt": {
        "type": "integer",
        "description": "Epoch timestamp in milliseconds of when the payment method token was created",
        "example": 1727340330123
      },
      "PayoutCreatedAt": {
        "type": "integer",
        "description": "Epoch timestamp in milliseconds of when the payout was created",
        "example": 1727340330123
      },
      "Currency": {
        "type": "string",
        "description": "Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported)",
        "example": "USD"
      },
      "RefundedAt": {
        "type": "integer",
        "format": "int64",
        "description": "Epoch timestamp in milliseconds of when the refund was processed",
        "example": 1727340330123
      },
      "get-payouts-response": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Payout" }
          },
          "metadata": {
            "type": "object",
            "properties": {
              "offset": { "$ref": "#/components/schemas/PaginationOffset" }
            }
          }
        },
        "required": ["data", "metadata"]
      },
      "Payout": {
        "type": "object",
        "properties": {
          "payoutId": { "type": "string", "description": "Unique identifier of the payout" },
          "amount": { "$ref": "#/components/schemas/PayoutAmount" },
          "status": { "$ref": "#/components/schemas/PayoutStatus" },
          "createdAt": { "$ref": "#/components/schemas/PayoutCreatedAt" }
        },
        "required": ["payoutId", "amount", "status", "createdAt"]
      },
      "get-payout-response": {
        "type": "object",
        "properties": {
          "payoutId": { "type": "string", "description": "Unique identifier of the payout", "example": "po_g8jKF4kdSdxlYcX2" },
          "payoutStatementUrl": {
            "type": "string",
            "description": "A special link you can use to download the payout statement file as a CSV. This link is valid for 10 minutes."
          },
          "amount": { "$ref": "#/components/schemas/PayoutAmount" },
          "status": { "$ref": "#/components/schemas/PayoutStatus" },
          "createdAt": { "$ref": "#/components/schemas/PayoutCreatedAt" }
        },
        "required": ["payoutId", "payoutStatementUrl", "amount", "status", "createdAt"]
      },
      "get-intents-response": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/IntentSummary" }
          },
          "metadata": {
            "type": "object",
            "properties": {
              "offset": { "$ref": "#/components/schemas/PaginationOffset" }
            }
          }
        },
        "required": ["data", "metadata"]
      },
      "IntentSummary": {
        "type": "object",
        "properties": {
          "amount": { "$ref": "#/components/schemas/Amount", "example": 2000 },
          "currency": { "type": "string", "description": "Three-letter currency code", "example": "USD" },
          "createdAt": { "$ref": "#/components/schemas/CreatedAt" },
          "status": { "type": "string", "description": "Current status of the intent. Refer [payment statuses](/products/one-time-payments/payment-statuses)", "example": "SUCCESS" },
          "succeededAt": { "$ref": "#/components/schemas/SucceededAt" },
          "receiptId": { "type": "string", "description": "Your identifier for the order", "example": "1234567890" },
          "xIntentId": { "type": "string", "description": "Unique identifier of the intent", "example": "in_fnXr3r2P1bEiiE1n" }
        },
        "required": ["amount", "currency", "createdAt", "status", "xIntentId"]
      },
      "create-intent": {
        "required": ["amount", "currency", "callbackUrl", "customerDetails"],
        "type": "object",
        "properties": {
          "amount": {
            "description": "The amount in lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (The minimum amount should be greater than 1 USD)",
            "type": "integer",
            "format": "int64",
            "example": 100
          },
          "currency": {
            "description": "Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported)",
            "type": "string",
            "example": "USD"
          },
          "receiptId": {
            "description": "Your identifier of the order",
            "type": "string",
            "example": "order123"
          },
          "customerDetails": {
            "$ref": "#/components/schemas/BillingDetails"
          },
          "customerReferenceId": {
            "$ref": "#/components/schemas/CustomerReferenceId"
          },
          "description": {
            "description": "The description of the order, if any",
            "type": "string",
            "example": "Order for 2 items"
          },
          "callbackUrl": {
            "description": "The URL we will callback to with the xIntentId once it finishes.",
            "type": "string",
            "example": "https://example.com/callback"
          },
          "cancelUrl": {
            "description": "The URL to redirect the customer to when they cancel the payment. If not provided, the callbackUrl will be used as fallback.",
            "type": "string",
            "example": "https://example.com/cancel"
          },
          "paymentMethods": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of payment methods to be enabled for the link. [supported payment methods](/get-started/payment-methods-supported#payment-method-enums)\n\n💡 If a selected payment method is unavailable, the system will automatically fallback to card payments to ensure a smooth checkout experience.",
            "example": ["CARD", "GOOGLE_PAY", "APPLE_PAY"]
          },
          "metadata": {
            "type": "object",
            "description": "A collection of key-value pairs that can be attached to an object for storing additional structured information. This is useful for capturing custom data or context-specific attributes.\n\nConstraints:\n- Maximum of 50 key-value pairs allowed.\n- Each key must be no longer than 40 characters.\n- Each value must be a string and cannot exceed 500 characters.",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "orderId": "12345",
              "customerNote": "Deliver after 5 PM"
            }
          },
          "phoneNumberRequired": {
            "type": "boolean",
            "description": "Flag to indicate whether phone number is required from the customer during checkout. By default, this is false.",
            "example": false
          },
          "customerId": {
            "type": "string",
            "description": "The unique identifier for the customer, generated via the [create-customer API](/api-reference/customers/create-customer). This can be used to associate the payment with a specific customer in your system.",
            "example": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
          },
          "storeFrontId": {
            "type": "string",
            "description": "🔵 **Beta Feature** - The unique identifier for your storefront. This ID is used to associate the payment with a specific storefront in your account. When provided, it will replace the default DBA and logo with the corresponding storefront's branding. This feature is currently in beta testing and may be subject to changes.\n\nTo enable this feature, please contact [hello@xpaycheckout.com](mailto:hello@xpaycheckout.com)",
            "example": "sf_sK8d3Jq1tZxPjYVhRQW2rf"
          },
          "tokenise": {
            "type": "boolean",
            "description": "This boolean tokenises and stores the card to showcase the same card in future. If sending this value, corresponding `customerId` is also required. You will receive [`payment_method_token.created`](/developer-resources/webhooks/events/setupMethodEvents/payment_method_token_created) webhook every time a new payment method token is created.",
            "example": false
          },
          "manualCapture": {
            "type": "boolean",
            "description": "When set to true, the payment is authorized but not captured immediately, allowing you to complete the capture separately. By default, this is false.",
            "example": false
          },
          "productPage": {
            "$ref": "#/components/schemas/ProductPage",
            "description": "Product Page - showcases more about the product on the checkout page"
          },
          "allowedCardInstallmentTenures": {
            "$ref": "#/components/schemas/AllowedCardInstallmentTenures"
          },
          "platformFeeInBps": {
            "type": "integer",
            "description": "Optional additional fee in basis points (1 bps = 0.01%). Only available to Platform merchants when creating a payment intent on behalf of a Connect merchant (requires the `x-connect-merchant-id` header). See [Platform Connect](/products/platform-connect/overview).",
            "example": 100
          }
        }
      },
      "capture-payment-request": {
        "required": ["intentId"],
        "type": "object",
        "properties": {
          "intentId": {
            "type": "string",
            "description": "Unique identifier of the previously authorized payment intent",
            "example": "in_fooBOwYsaK50AEfK"
          }
        }
      },
      "capture-payment-response": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Current status of the payment intent. Refer to [payment statuses](/products/one-time-payments/payment-statuses).",
            "example": "SUCCESS"
          },
          "errorCode": {
            "type": "string",
            "nullable": true,
            "description": "Machine-readable error code when the capture is unsuccessful. Refer to [error codes](/products/one-time-payments/error-codes).",
            "example": null
          },
          "errorMessage": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable error message when the capture is unsuccessful.",
            "example": null
          }
        }
      },
      "charge-raw-card-request": {
        "allOf": [
          {
            "type": "object",
            "required": ["amount", "currency", "cardDetails", "callbackUrl"],
            "properties": {
              "amount": {
                "$ref": "#/components/schemas/Amount"
              },
              "currency": {
                "description": "Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported)",
                "type": "string",
                "example": "USD"
              },
              "receiptId": {
                "description": "Your identifier for the order",
                "type": "string",
                "example": "order123"
              },
              "cardDetails": {
                "$ref": "#/components/schemas/CardDetails"
              },
              "callbackUrl": {
                "description": "URL that the customer will be redirected to once the payment is processed in case 3ds authentication is required.",
                "type": "string",
                "example": "https://example.com/callback"
              },
              "metadata": {
                "type": "object",
                "description": "A collection of key-value pairs that can be attached to an object for storing additional structured information. This is useful for capturing custom data or context-specific attributes.\n\nConstraints:\n- Maximum of 50 key-value pairs allowed.\n- Each key must be no longer than 40 characters.\n- Each value must be a string and cannot exceed 500 characters.",
                "additionalProperties": {
                  "type": "string"
                },
                "example": {
                  "orderId": "12345",
                  "customerNote": "Deliver after 5 PM"
                }
              },
              "customerId": {
                "$ref": "#/components/schemas/CustomerId"
              },
              "customerReferenceId": {
                "$ref": "#/components/schemas/CustomerReferenceId"
              },
              "customerDetails": {
                "allOf": [{ "$ref": "#/components/schemas/BillingDetails" }],
                "description": "Details of the customer. Required if `customerId` is not provided."
              }
            }
          }
        ]
      },
      "charge-raw-card-response": {
        "type": "object",
        "properties": {
          "intentId": {
            "type": "string",
            "description": "Identifier of the payment intent created for this charge.",
            "example": "in_gKAqR0DjLeOihdTE"
          },
          "nextActionRedirectionURL": {
            "type": "string",
            "description": "URL to redirect your customer to xpay's secure link to complete any pending 3DS or next action steps. Present only when additional authentication is required.",
            "example": "https://pay.xpaycheckout.com/?id=67f53a6e2097773e4f0112c8"
          },
          "errorCode": {
            "type": "string",
            "description": "Machine readable failure reason when status is `FAILED`. [See all possible values here.](/products/one-time-payments/error-codes)",
            "example": "insufficient_funds"
          }
        },
        "required": ["intentId", "nextActionRedirectionURL"]
      },
      "generate-link": {
        "required": ["amount", "currency", "customerDetails", "expiryDate"],
        "type": "object",
        "properties": {
          "amount": {
            "description": "The amount in lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (The minimum amount should be greater than 1 USD)",
            "type": "integer",
            "format": "int64",
            "example": 100
          },
          "currency": {
            "description": "Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported)",
            "type": "string",
            "example": "USD"
          },
          "receiptId": {
            "description": "Your identifier of the order",
            "type": "string",
            "example": "order123"
          },
          "customerDetails": {
            "$ref": "#/components/schemas/BillingDetails"
          },
          "description": {
            "description": "The description of the order, if any",
            "type": "string",
            "example": "Order for 2 items"
          },
          "expiryDate": {
            "description": "Timestamp in epoch milliseconds, indicating the expiration time of the link",
            "type": "integer",
            "format": "int64",
            "example": 32526868154000
          },
          "callbackUrl": {
            "description": "The URL we will callback to with the xIntentId once it finishes.",
            "type": "string",
            "example": "https://example.com/callback"
          },
          "cancelUrl": {
            "description": "The URL to redirect the customer to when they cancel the payment. If not provided, the callbackUrl will be used as fallback.",
            "type": "string",
            "example": "https://example.com/cancel"
          },
          "paymentMethods": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of payment methods to be enabled for the link. [supported payment methods](/get-started/payment-methods-supported#payment-method-enums)\n\n💡 If a selected payment method is unavailable, the system will automatically fallback to card payments to ensure a smooth checkout experience.",
            "example": ["CARD", "GOOGLE_PAY", "APPLE_PAY"]
          },
          "storeFrontId": {
            "type": "string",
            "description": "🔵 **Beta Feature** - The unique identifier for your storefront. This ID is used to associate the payment link with a specific storefront in your account. When provided, it will replace the default DBA and logo with the corresponding storefront's branding. This feature is currently in beta testing and may be subject to changes.\n\nTo enable this feature, please contact [hello@xpaycheckout.com](mailto:hello@xpaycheckout.com)",
            "example": "sf_sK8d3Jq1tZxPjYVhRQW2rf"
          },
          "multiUseLimit": {
            "type": "integer",
            "format": "int64",
            "description": "The maximum number of times this payment link can be used. If null, the link can be used only once. Must be greater than 0 if provided.",
            "minimum": 1,
            "example": 5
          },
          "productPage": {
            "$ref": "#/components/schemas/ProductPage",
            "description": "Product Page - showcases more about the product in the payment links"
          },
          "phoneNumberRequired": {
            "type": "boolean",
            "description": "Flag to indicate whether phone number is required from the customer during checkout. By default, this is false.",
            "example": false
          },
          "allowedCardInstallmentTenures": {
            "$ref": "#/components/schemas/AllowedCardInstallmentTenures"
          }
        }
      },
      "refund": {
        "required": ["xIntentId"],
        "type": "object",
        "properties": {
          "xIntentId": {
            "description": "Unique identifier of the intent",
            "type": "string",
            "example": "in_fooBOwYsaK50AEfK"
          },
          "amount": {
            "description": "The amount you want to refund, specified in the smallest unit of the currency (for example, cents for USD, paise for INR). \n\n- If you want to issue a partial refund, provide the amount you wish to refund here. For example, if the original payment was $100 (i.e., 10000 cents), and you want to refund $20, you would enter 2000.\n- If you leave this field blank, the full payment amount will be refunded automatically.",
            "type": "string",
            "example": "200"
          },
          "refundReferenceId": {
            "description": "Your identifier for the refund",
            "type": "string",
            "example": "re123"
          }
        }
      },
      "refund-response": {
        "type": "object",
        "properties": {
          "refundId": {
            "type": "string",
            "description": "Unique identifier of the refund",
            "example": "rf_fooBOwYsaK50AEaJ"
          },
          "intentId": {
            "type": "string",
            "description": "Unique identifier of the payment intent",
            "example": "in_fooBOwYsaK50AEfK"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "refundedAt": {
            "$ref": "#/components/schemas/RefundedAt"
          },
          "refundReferenceId": {
            "type": "string",
            "description": "Your identifier for the refund",
            "example": "re123"
          }
        },
        "required": ["refundId", "intentId", "amount", "currency", "refundedAt"]
      },
      "get-refunds-response": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/refund-response"
        }
      },
      "IntentDetailsResponse": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "integer",
            "description": "The amount in lowest count unit (e.g., cents for USD)",
            "example": 100
          },
          "currency": {
            "type": "string",
            "description": "Three-letter currency code",
            "example": "USD"
          },
          "presentmentCurrency": {
            "type": "string",
            "description": "The currency that the customer paid in",
            "example": "USD"
          },
          "receiptId": {
            "type": "string",
            "description": "Your identifier for the order",
            "example": "order123"
          },
          "customerDetails": {
            "$ref": "#/components/schemas/BillingDetails"
          },
          "description": {
            "type": "string",
            "description": "Description of the order, if any",
            "example": "Order for 2 items"
          },
          "callbackUrl": {
            "type": "string",
            "description": "Callback URL to notify order status",
            "example": "https://example.com/callback"
          },
          "cancelUrl": {
            "type": "string",
            "description": "The URL to redirect the customer to when they cancel the payment.",
            "example": "https://example.com/cancel"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of when the intent was created",
            "example": "2024-09-26T10:41:50.472+00:00"
          },
          "status": {
            "type": "string",
            "description": "Current status of the intent. Refer [payment statuses](/products/one-time-payments/payment-statuses)",
            "example": "CREATED"
          },
          "xIntentId": {
            "type": "string",
            "description": "Unique identifier of the intent",
            "example": "in_fooBOwYsaK50AEfK"
          },
          "fwdUrl": {
            "type": "string",
            "description": "The URL to redirect the customer to the xPay payment gateway for payment.",
            "example": "https://pay.xpaycheckout.com/?xpay_intent_id=67f53a6e2097773e4f0112c8"
          },
          "metadata": {
            "type": "object",
            "description": "A collection of key-value pairs that were provided when the object was created. These metadata values are echoed back in the response, allowing you to store and retrieve custom information such as context-specific attributes, references, or tags. This can be useful for correlating records in your system or attaching meaningful context to transactions.",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "orderId": "12345",
              "customerNote": "Deliver after 5 PM"
            }
          }
        }
      },
      "get-intent-details-response": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "integer",
            "description": "The amount in lowest count unit (e.g., cents for USD)",
            "example": 100
          },
          "currency": {
            "type": "string",
            "description": "Three-letter currency code",
            "example": "USD"
          },
          "presentmentCurrency": {
            "type": "string",
            "description": "The currency that the customer paid in",
            "example": "USD"
          },
          "receiptId": {
            "type": "string",
            "description": "Your identifier for the order",
            "example": "order123"
          },
          "customerDetails": {
            "$ref": "#/components/schemas/BillingDetails"
          },
          "customerReferenceId": {
            "type": "string",
            "description": "Your unique identifier for the customer. This can be used to associate the payment with a specific customer in your system.",
            "example": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
          },
          "description": {
            "type": "string",
            "description": "Description of the order, if any",
            "example": "Order for 2 items"
          },
          "callbackUrl": {
            "type": "string",
            "description": "Callback URL to notify order status",
            "example": "https://example.com/callback"
          },
          "cancelUrl": {
            "type": "string",
            "description": "The URL to redirect the customer to when they cancel the payment.",
            "example": "https://example.com/cancel"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of when the intent was created",
            "example": "2024-09-26T10:41:50.472+00:00"
          },
          "status": {
            "type": "string",
            "description": "Current status of the intent. Refer [payment statuses](/products/one-time-payments/payment-statuses)",
            "example": "CREATED"
          },
          "xIntentId": {
            "type": "string",
            "description": "Unique identifier of the intent",
            "example": "in_fooBOwYsaK50AEfK"
          },
          "succeededAt": {
            "$ref": "#/components/schemas/SucceededAt"
          },
          "metadata": {
            "type": "object",
            "description": "A collection of key-value pairs that were provided when the object was created. These metadata values are echoed back in the response, allowing you to store and retrieve custom information such as context-specific attributes, references, or tags. This can be useful for correlating records in your system or attaching meaningful context to transactions.",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "orderId": "12345",
              "customerNote": "Deliver after 5 PM"
            }
          },
          "chargeAttempts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChargeDTO"
            },
            "description": "List of all charge attempts for this intent. Only included when `charge_attempts` is specified in the expand parameter.",
            "example": [
              {
                "status": "FAILED",
                "paymentMetadata": {
                  "paymentMethod": "CARD",
                  "cardMetadata": {
                    "brand": "visa",
                    "country": "US",
                    "lastFourDigit": "4242",
                    "expiryMonth": 12,
                    "expiryYear": 2025,
                    "cardType": "CREDIT"
                  }
                },
                "chargeTime": 1727340330123,
                "errorCode": "card_declined"
              },
              {
                "status": "SUCCESS",
                "paymentMetadata": {
                  "paymentMethod": "CARD",
                  "cardMetadata": {
                    "brand": "visa",
                    "country": "US",
                    "lastFourDigit": "4242",
                    "expiryMonth": 12,
                    "expiryYear": 2025,
                    "cardType": "CREDIT"
                  }
                },
                "chargeTime": 1727340331123,
                "errorCode": null
              }
            ]
          },
          "succeededCharge": {
            "$ref": "#/components/schemas/ChargeDTO",
            "description": "Details of the successful charge attempt. Only included when `succeeded_charge` is specified in the expand parameter and the payment was successful.",
            "example": {
              "status": "SUCCESS",
              "paymentMetadata": {
                "paymentMethod": "CARD",
                "cardMetadata": {
                  "brand": "visa",
                  "country": "US",
                  "lastFourDigit": "4242",
                  "expiryMonth": 12,
                  "expiryYear": 2025,
                  "cardType": "CREDIT"
                }
              },
              "chargeTime": 1727340331123,
              "errorCode": null
            }
          },
          "paymentMethod": {
            "type": "string",
            "enum": [
              "CARD",
              "GOOGLE_PAY",
              "APPLE_PAY",
              "PAYPAL",
              "AMAZON_PAY",
              "CASH_APP",
              "KLARNA",
              "AFTERPAY",
              "AFFIRM",
              "VENMO",
              "CARD_INSTALLMENT"
            ],
            "description": "The payment method associated with a successful intent. See [Payment Methods](/get-started/payment-methods-supported) for the full list of supported payment methods and their availability.",
            "example": "CARD"
          }
        }
      },
      "generate-link-response": {
        "type": "object",
        "properties": {
          "shortUrl": {
            "type": "string",
            "description": "The shortened URL generated by the xPay API. This link can be shared with customers for completing payments.",
            "example": "https://api.xpaycheckout.com/link/pcTrro7D"
          },
          "disclaimer": {
            "type": "string",
            "description": "A message highlighting unsupported currency and payment method pairs. You may use this information to communicate these limitations to your users and set expectations.",
            "example": "GBP is not supported on Klarna. The payment will default to USD."
          }
        }
      },
      "Error": {
        "required": ["errorCode", "errorDescription"],
        "type": "object",
        "properties": {
          "errorCode": {
            "type": "string",
            "example": "bad_request"
          },
          "errorDescription": {
            "type": "string",
            "example": "Failed to read request"
          }
        }
      },
      "create-subscription": {
        "required": [
          "amount",
          "currency",
          "customerDetails",
          "callbackUrl",
          "interval",
          "intervalCount",
          "cycleCount"
        ],
        "type": "object",
        "properties": {
          "amount": {
            "description": "The amount in lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (The minimum amount should be greater than 1 USD)",
            "type": "integer",
            "format": "int64",
            "example": 100
          },
          "currency": {
            "description": "Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported)",
            "type": "string",
            "example": "USD"
          },
          "receiptId": {
            "description": "Your identifier of the order",
            "type": "string",
            "example": "order123"
          },
          "customerDetails": {
            "$ref": "#/components/schemas/BillingDetails"
          },
          "callbackUrl": {
            "description": "The URL we will callback to with the order status once it finishes.",
            "type": "string",
            "example": "https://example.com/callback"
          },
          "cancelUrl": {
            "description": "The URL to redirect the customer to when they cancel the subscription. If not provided, the callbackUrl will be used as fallback.",
            "type": "string",
            "example": "https://example.com/cancel"
          },
          "interval": {
            "type": "string",
            "description": "The interval group between subscriptions.",
            "enum": ["DAY", "WEEK", "MONTH", "YEAR"],
            "example": "MONTH"
          },
          "intervalCount": {
            "type": "integer",
            "description": "The number of intervals between subscription billings. For example, `interval = MONTH` and `intervalCount = 3` bills every 3 months.",
            "format": "int64",
            "example": 2
          },
          "cycleCount": {
            "type": "integer",
            "description": "The number of billing cycles for which the subscription will renew before ending. The first cycle is included in this count.",
            "format": "int64",
            "example": 2
          },
          "upfrontAmount": {
            "$ref": "#/components/schemas/UpfrontAmount"
          },
          "trialPeriodCount": {
            "type": "integer",
            "format": "int64",
            "description": "The number of trial periods before the first billing cycle. Must be greater than or equal to 0 if provided.\n\n**Validation Rules:**\n- If `trialPeriodCount` is provided, `trialPeriodInterval` must also be provided\n- `trialPeriodCount` is not compatible with `upfrontAmount` - both cannot be provided simultaneously",
            "minimum": 0,
            "example": 7
          },
          "trialPeriodInterval": {
            "type": "string",
            "description": "The interval for the trial period.\n\n**Validation Rules:**\n- Required when `trialPeriodCount` is provided",
            "enum": ["DAY", "WEEK", "MONTH", "YEAR"],
            "example": "DAY"
          },
          "metadata": {
            "type": "object",
            "description": "A collection of key-value pairs that can be attached to an object for storing additional structured information. This is useful for capturing custom data or context-specific attributes.\n\nConstraints:\n- Maximum of 50 key-value pairs allowed.\n- Each key must be no longer than 40 characters.\n- Each value must be a string and cannot exceed 500 characters.",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "orderId": "12345",
              "customerNote": "Deliver after 5 PM"
            }
          },
          "phoneNumberRequired": {
            "type": "boolean",
            "description": "Flag to indicate whether phone number is required from the customer during checkout. By default, this is false.",
            "example": false
          },
          "customerId": {
            "$ref": "#/components/schemas/CustomerId"
          },
          "productPage": {
            "$ref": "#/components/schemas/ProductPage",
            "description": "Product Page - showcases more about the product on the checkout page"
          }
        }
      },
      "create-subscription-response": {
        "type": "object",
        "properties": {
          "subscriptionId": {
            "type": "string",
            "description": "Unique identifier of the subscription",
            "example": "sub_fooBOwYsaK50AEfK"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of when the subscription was created",
            "example": "2024-09-26T10:41:50.472+00:00"
          },
          "fwdUrl": {
            "type": "string",
            "description": "The URL to redirect the customer to the xPay payment gateway for payment.",
            "example": "https://pay.xpaycheckout.com/?subscription_id=67f53a6e2097773e4f0112c8"
          }
        }
      },
      "get-subscription-response": {
        "type": "object",
        "properties": {
          "subscriptionId": {
            "type": "string",
            "description": "Unique identifier of the subscription",
            "example": "sub_fooBOwYsaK50AEfK"
          },
          "interval": {
            "type": "string",
            "description": "The interval group between subscriptions.",
            "enum": ["DAY", "WEEK", "MONTH", "YEAR"],
            "example": "MONTH"
          },
          "intervalCount": {
            "type": "integer",
            "description": "The number of intervals between subscription billings. For example, `interval = MONTH` and `intervalCount = 3` bills every 3 months.",
            "format": "int64",
            "example": 2
          },
          "cycleCount": {
            "type": "integer",
            "description": "The number of billing cycles for which the subscription will renew before ending. The first cycle is included in this count.",
            "format": "int64",
            "example": 2
          },
          "remainingCycleCount": {
            "type": "integer",
            "description": "The number of billing cycles remaining for the subscription.",
            "format": "int64",
            "example": 2
          },
          "currency": {
            "type": "string",
            "description": "Three-letter currency code",
            "example": "USD"
          },
          "amount": {
            "type": "integer",
            "description": "The amount in lowest count unit (e.g., cents for USD)",
            "format": "int64",
            "example": 100
          },
          "presentmentCurrency": {
            "type": "string",
            "description": "The currency that the customer paid in",
            "example": "USD"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of when the subscription was created",
            "example": "2024-09-26T10:41:50.472+00:00"
          },
          "status": {
            "type": "string",
            "description": "The status of the subscription. Refer [subscription statuses](/products/subscription/subscription-statuses)",
            "example": "CREATED"
          },
          "upfrontAmount": {
            "type": "integer",
            "format": "int64",
            "description": "The amount charged to the customer at the time the subscription was activated. This replaces the first billing cycle charge; regular billing resumes from the next cycle.",
            "example": 200
          },
          "trialPeriodCount": {
            "type": "integer",
            "format": "int64",
            "description": "The number of trial periods before the first billing cycle.",
            "example": 7
          },
          "trialPeriodInterval": {
            "type": "string",
            "description": "The interval for the trial period.",
            "enum": ["DAY", "WEEK", "MONTH", "YEAR"],
            "example": "DAY"
          },
          "metadata": {
            "type": "object",
            "description": "A collection of key-value pairs that can be attached to an object for storing additional structured information. This is useful for capturing custom data or context-specific attributes.\n\nConstraints:\n- Maximum of 50 key-value pairs allowed.\n- Each key must be no longer than 40 characters.\n- Each value must be a string and cannot exceed 500 characters.",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "orderId": "12345",
              "customerNote": "Deliver after 5 PM"
            }
          },
          "updatePaymentMethodLink": {
            "type": "string",
            "description": "The URL to redirect the customer to the xPay payment gateway for updating the payment method. Available only for subscriptions in `TRIALING`, `ACTIVE`, or `UNPAID`  status.",
            "example": "https://pay.xpaycheckout.com/subscription/update?subscription_id=sub_123"
          },
          "paymentMetadata": {
            "$ref": "#/components/schemas/PaymentMetadataDTO",
            "description": "Payment metadata for the subscription, including the payment method and card details if applicable"
          }
        }
      },
      "cancel-subscription": {
        "required": ["subscriptionId"],
        "type": "object",
        "properties": {
          "subscriptionId": {
            "description": "Unique identifier of the subscription",
            "type": "string",
            "example": "sub_fooBOwYsaK50AEfK"
          }
        }
      },
      "pause-subscription": {
        "required": ["subscriptionId"],
        "type": "object",
        "properties": {
          "subscriptionId": {
            "description": "Unique identifier of the subscription",
            "type": "string",
            "example": "sub_fooBOwYsaK50AEfK"
          }
        }
      },
      "unpause-subscription": {
        "required": ["subscriptionId", "newNextPaymentDate"],
        "type": "object",
        "properties": {
          "subscriptionId": {
            "description": "Unique identifier of the subscription",
            "type": "string",
            "example": "sub_fooBOwYsaK50AEfK"
          },
          "newNextPaymentDate": {
            "description": "The date on which the subscription becomes active again and the next charge will be attempted, as a Unix timestamp in milliseconds.",
            "type": "integer",
            "format": "int64",
            "example": 1729608043615
          }
        }
      },
      "subs-one-time-charge": {
        "required": ["subscriptionId", "amount", "currency"],
        "type": "object",
        "properties": {
          "subscriptionId": {
            "description": "Unique identifier of the subscription to charge against. The subscription's saved payment method will be used for this charge.",
            "type": "string",
            "example": "sub_fooBOwYsaK50AEfK"
          },
          "amount": {
            "description": "The amount in lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents. Must be within the currency's supported minimum and maximum bounds.",
            "type": "integer",
            "format": "int64",
            "example": 500
          },
          "currency": {
            "description": "Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported)",
            "type": "string",
            "example": "USD"
          },
          "comments": {
            "description": "Optional free-form note describing the reason for this one-time charge.",
            "type": "string",
            "example": "One-time setup fee for premium add-on"
          }
        }
      },
      "subs-one-time-charge-response": {
        "type": "object",
        "properties": {
          "intentId": {
            "type": "string",
            "description": "Unique identifier of the payment intent created for this one-time charge.",
            "example": "in_gKAqR0DjLeOihdTE"
          },
          "status": {
            "type": "string",
            "description": "The status of the payment intent. Refer [payment intent status](/products/one-time-payments/payment-statuses)",
            "example": "SUCCESS"
          },
          "errorCode": {
            "type": "string",
            "nullable": true,
            "description": "Machine readable failure reason when status is `FAILED`. `null` on a successful charge. [See all possible values here.](/products/one-time-payments/error-codes)",
            "example": "card_declined"
          },
          "errorMessage": {
            "type": "string",
            "nullable": true,
            "description": "Human readable description of the failure reason when the charge was not successful. `null` on a successful charge.",
            "example": "The payment has been declined by the customer's bank."
          }
        }
      },
      "subs-manual-retry": {
        "required": ["subscriptionId"],
        "type": "object",
        "properties": {
          "subscriptionId": {
            "description": "Unique identifier of the subscription whose failed payment should be retried.",
            "type": "string",
            "example": "sub_fooBOwYsaK50AEfK"
          }
        }
      },
      "subs-manual-retry-response": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indicates whether the manual retry payment was successful.",
            "example": true
          },
          "minManualRetryDate": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Earliest time at which another manual retry can be attempted based on the 4-hour cooldown.",
            "example": "2026-09-08T14:30:00.000+00:00"
          },
          "status": {
            "type": "string",
            "description": "Current subscription status after the retry attempt. Refer [subscription statuses](/products/subscription/subscription-statuses).",
            "enum": ["ACTIVE", "UNPAID", "ENDED"],
            "example": "ACTIVE"
          },
          "errorCode": {
            "type": "string",
            "nullable": true,
            "description": "Machine-readable failure reason when the manual retry is unsuccessful. `null` on success. [See all possible values here.](/products/one-time-payments/error-codes)",
            "example": "card_declined"
          },
          "errorMessage": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable failure reason when the manual retry is unsuccessful. `null` on success.",
            "example": null
          }
        }
      },
      "cancel-payment": {
        "required": ["xIntentId"],
        "type": "object",
        "properties": {
          "xIntentId": {
            "description": "Unique identifier of the payment",
            "type": "string",
            "example": "in_fooBOwYsaK50AEfK"
          }
        }
      },
      "subscription-link": {
        "required": [
          "amount",
          "currency",
          "customerDetails",
          "expiryDate",
          "interval",
          "intervalCount",
          "cycleCount"
        ],
        "type": "object",
        "properties": {
          "amount": {
            "description": "The amount in lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (The minimum amount should be greater than 1 USD)",
            "type": "integer",
            "format": "int64",
            "example": 100
          },
          "currency": {
            "description": "Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported)",
            "type": "string",
            "example": "USD"
          },
          "receiptId": {
            "description": "Your identifier of the order",
            "type": "string",
            "example": "order123"
          },
          "customerDetails": {
            "$ref": "#/components/schemas/BillingDetails"
          },
          "description": {
            "description": "The description of the order, if any",
            "type": "string",
            "example": "Order for 2 items"
          },
          "expiryDate": {
            "description": "Timestamp in epoch milliseconds, indicating the expiration time of the link",
            "type": "integer",
            "format": "int64",
            "example": 32526868154000
          },
          "callbackUrl": {
            "description": "The URL we will callback to with the subscriptionId once it finishes.",
            "type": "string",
            "example": "https://example.com/callback"
          },
          "cancelUrl": {
            "description": "The URL to redirect the customer to when they cancel the subscription. If not provided, the callbackUrl will be used as fallback.",
            "type": "string",
            "example": "https://example.com/cancel"
          },
          "interval": {
            "type": "string",
            "description": "The interval group between subscriptions.",
            "enum": ["DAY", "WEEK", "MONTH", "YEAR"],
            "example": "MONTH"
          },
          "intervalCount": {
            "type": "integer",
            "description": "The number of intervals between subscription billings. For example, `interval = MONTH` and `intervalCount = 3` bills every 3 months.",
            "format": "int64",
            "example": 2
          },
          "cycleCount": {
            "type": "integer",
            "description": "The number of billing cycles for which the subscription will renew before ending. The first cycle is included in this count.",
            "format": "int64",
            "example": 2
          },
          "upfrontAmount": {
            "$ref": "#/components/schemas/UpfrontAmount"
          },
          "trialPeriodCount": {
            "type": "integer",
            "format": "int64",
            "description": "The number of trial periods before the first billing cycle. Must be greater than or equal to 0 if provided.\n\n**Validation Rules:**\n- If `trialPeriodCount` is provided, `trialPeriodInterval` must also be provided\n- `trialPeriodCount` is not compatible with `upfrontAmount` - both cannot be provided simultaneously",
            "minimum": 0,
            "example": 7
          },
          "trialPeriodInterval": {
            "type": "string",
            "description": "The interval for the trial period.\n\n**Validation Rules:**\n- Required when `trialPeriodCount` is provided",
            "enum": ["DAY", "WEEK", "MONTH", "YEAR"],
            "example": "DAY"
          },
          "multiUseLimit": {
            "type": "integer",
            "format": "int64",
            "description": "The maximum number of times this subscription link can be used. If null, the link can be used only once. Must be greater than 0 if provided.",
            "minimum": 1,
            "example": 5
          },
          "productPage": {
            "$ref": "#/components/schemas/ProductPage",
            "description": "Product Page - showcases more about the product in the payment links"
          },
          "phoneNumberRequired": {
            "type": "boolean",
            "description": "Flag to indicate whether phone number is required from the customer during checkout. By default, this is false.",
            "example": false
          }
        }
      },
      "subscription-link-response": {
        "type": "object",
        "properties": {
          "shortUrl": {
            "type": "string",
            "description": "The shortened URL generated by the xPay API. This link can be shared with customers for completing payments.",
            "example": "https://api.xpaycheckout.com/subscription/link/pcTrro7D"
          },
          "disclaimer": {
            "type": "string",
            "description": "A message highlighting unsupported currency and payment method pairs. You may use this information to communicate these limitations to your users and set expectations.",
            "example": "GBP is not supported on Klarna. The payment will default to USD."
          }
        }
      },
      "create-setup-method": {
        "required": ["currency", "callbackUrl", "billingDetails"],
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "description": "Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported)",
            "example": "USD"
          },
          "paymentMethods": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of payment methods to be enabled for setup. [supported payment methods](/get-started/payment-methods-supported#payment-method-enums)\n\n💡 If a selected payment method is unavailable, the system will automatically fallback to card payments to ensure a smooth checkout experience.",
            "example": ["CARD", "GOOGLE_PAY", "APPLE_PAY"]
          },
          "customerId": {
            "allOf": [{ "$ref": "#/components/schemas/CustomerId" }],
            "description": "The unique identifier for the customer, generated via the [create-customer API](/developer-resources/endpoints/customer/create-customer)."
          },
          "billingDetails": {
            "allOf": [{ "$ref": "#/components/schemas/BillingDetails" }],
            "description": "Billing details for the customer."
          },
          "storeFrontId": {
            "type": "string",
            "description": "The unique identifier for your storefront",
            "example": "sf_sK8d3Jq1tZxPjYVhRQW2rf"
          },
          "callbackUrl": {
            "type": "string",
            "description": "The URL we will callback to once the setup is complete",
            "example": "https://example.com/callback"
          },
          "metadata": {
            "type": "object",
            "description": "A collection of key-value pairs that can be attached to an object for storing additional structured information",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "orderId": "12345",
              "customerNote": "Setup for recurring payments"
            }
          },
          "phoneNumberRequired": {
            "type": "boolean",
            "description": "Flag to indicate whether phone number is required from the customer during checkout. By default, this is false.",
            "example": false
          }
        }
      },
      "create-s2s-setup-method": {
        "required": ["currency", "cardDetails", "billingDetails", "callbackUrl"],
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "description": "Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported)",
            "example": "USD"
          },
          "customerId": {
            "allOf": [{ "$ref": "#/components/schemas/CustomerId" }],
            "description": "The unique identifier for the customer, generated via the [create-customer API](/developer-resources/endpoints/customer/create-customer).\n\n⚠️ Please note: Provide either `customerReferenceId` or this field, not both, as they are mutually exclusive."
          },
          "customerReferenceId": {
            "allOf": [{ "$ref": "#/components/schemas/CustomerReferenceId" }],
            "description": "Your unique identifier for the customer.\n\n⚠️ Please note: Provide either `customerId` or this field, not both, as they are mutually exclusive."
          },
          "billingDetails": {
            "allOf": [{ "$ref": "#/components/schemas/BillingDetails" }],
            "description": "Billing details for the customer."
          },
          "storeFrontId": {
            "type": "string",
            "description": "The unique identifier for your storefront",
            "example": "sf_sK8d3Jq1tZxPjYVhRQW2rf"
          },
          "callbackUrl": {
            "type": "string",
            "description": "The URL we will callback to once the setup is complete",
            "example": "https://example.com/callback"
          },
          "phoneNumberRequired": {
            "type": "boolean",
            "description": "Flag to indicate whether phone number is required from the customer during checkout. By default, this is false.",
            "example": false
          },
          "cardDetails": {
            "$ref": "#/components/schemas/CardDetails"
          },
          "amount": {
            "type": "integer",
            "format": "int64",
            "description": "The amount to charge immediately while setting up the payment method token. The amount in lowest count unit e.g.: For USD 1, amount is 100 representing 100 cents. Should be greater than 0.",
            "example": 100
          },
          "receiptId": {
            "type": "string",
            "description": "Your identifier of the order. This will be persisted in the intent created while setting up the payment method token.",
            "example": "order123"
          },
          "metadata": {
            "type": "object",
            "description": "A collection of key-value pairs that can be attached to an object for storing additional structured information.\n\nConstraints:\n- Maximum of 50 key-value pairs allowed.\n- Each key must be no longer than 40 characters.\n- Each value must be a string and cannot exceed 500 characters.",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "orderId": "12345",
              "customerNote": "Setup for recurring payments"
            }
          }
        }
      },
      "create-setup-method-response": {
        "type": "object",
        "properties": {
          "setupMethodId": {
            "type": "string",
            "description": "Unique identifier of the setup method",
            "example": "sm_sK8d3Jq1tZxPjYVhRQW2rf"
          },
          "fwdUrl": {
            "type": "string",
            "description": "The URL to redirect the customer to complete the setup",
            "example": "https://pay.xpaycheckout.com/setup-method?id=sm_sK8d3Jq1tZxPjYVhRQW2rf&secret=4b5PyxKSOuunnnFruohoiF"
          }
        }
      },
      "get-setup-method-response": {
        "type": "object",
        "properties": {
          "setupMethodId": {
            "type": "string",
            "description": "Unique identifier of the setup method",
            "example": "sm_sK8d3Jq1tZxPjYVhRQW2rf"
          },
          "customerId": {
            "type": "string",
            "description": "The unique identifier for the customer, generated via the [create-customer API](/api-reference/customers/create-customer)",
            "example": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
          },
          "currency": {
            "type": "string",
            "description": "Three letter abbreviation of the currency",
            "example": "USD"
          },
          "paymentMethods": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of payment methods enabled for setup.\n\n💡 If a selected payment method is unavailable, the system will automatically fallback to card payments to ensure a smooth checkout experience.",
            "example": ["CARD", "GOOGLE_PAY", "APPLE_PAY"]
          },
          "storeFrontId": {
            "type": "string",
            "description": "The unique identifier for your storefront",
            "example": "sf_sK8d3Jq1tZxPjYVhRQW2rf"
          },
          "callbackUrl": {
            "type": "string",
            "description": "The URL we will callback to once the setup is complete",
            "example": "https://example.com/callback"
          },
          "metadata": {
            "type": "object",
            "description": "A collection of key-value pairs that were provided when the object was created",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "orderId": "12345",
              "customerNote": "Setup for recurring payments"
            }
          },
          "status": {
            "type": "string",
            "description": "The status of the setup method",
            "enum": ["CREATED", "SUCCESS", "FAILED"],
            "example": "CREATED"
          },
          "pmId": {
            "type": "string",
            "description": "Unique identifier of the payment method if setup is completed",
            "example": "pmt_ftoeKIYGC3f43frT"
          },
          "intentId": {
            "type": "string",
            "description": "Unique identifier of the successful payment intent created while setting up the payment method token. Present only when `amount` is passed during setup creation.",
            "example": "in_ftoeKIYGC3f43frX"
          },
          "receiptId": {
            "type": "string",
            "description": "Your identifier for the order. Present only when provided during setup method creation.",
            "example": "recp_123311"
          }
        }
      },
      "charge-tokenised-pm": {
        "required": ["pmId", "customerId", "currency", "amount"],
        "type": "object",
        "properties": {
          "pmId": {
            "type": "string",
            "description": "Unique identifier of the payment method to charge",
            "example": "pmt_ftoeKIYGC3f43frT"
          },
          "customerId": {
            "type": "string",
            "description": "The unique identifier for the customer, generated via the [create-customer API](/api-reference/customers/create-customer)",
            "example": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
          },
          "currency": {
            "type": "string",
            "description": "Three letter abbreviation of the currency",
            "example": "USD"
          },
          "amount": {
            "type": "integer",
            "format": "int64",
            "description": "The amount in lowest count unit (e.g., cents for USD)",
            "example": 1000
          },
          "receiptId": { "$ref": "#/components/schemas/ReceiptId" },
          "storeFrontId": {
            "type": "string",
            "description": "Unique identifier of the storefront",
            "example": "sf_sadfsdfsdf213dsaf"
          },
          "metadata": {
            "type": "object",
            "description": "A collection of key-value pairs that can be attached to an object for storing additional structured information",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "orderId": "12345",
              "customerNote": "Charge for recurring payments"
            }
          }
        }
      },
      "charge-tokenised-pm-response": {
        "type": "object",
        "properties": {
          "intentId": {
            "type": "string",
            "description": "Unique identifier of the payment intent",
            "example": "in_dHd3Jq1tZxPjYVhRQW2r3"
          },
          "status": {
            "type": "string",
            "description": "The status of the payment intent. Refer [payment intent status](/products/one-time-payments/payment-statuses)",
            "example": "SUCCESS"
          },
          "errorCode": {
            "type": "string",
            "description": "Error code if the operation was not successful",
            "example": "card_declined"
          }
        }
      },
      "get-payment-method-token-response": {
        "type": "object",
        "properties": {
          "paymentMethodId": {
            "type": "string",
            "description": "Unique identifier of the payment method",
            "example": "pmt_ftoeKIYGC3f43frT"
          },
          "paymentMethod": {
            "type": "string",
            "description": "Type of payment method",
            "example": "CARD"
          },
          "customerId": {
            "type": "string",
            "description": "The unique identifier for the customer, generated via the [create-customer API](/api-reference/customers/create-customer)",
            "example": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
          },
          "status": {
            "type": "string",
            "description": "Status of the payment method token. Please refer to payment method token [status](/products/setup-method/overview#payment-method-token-lifecycle) for more details.",
            "enum": ["LIVE", "DELETED"],
            "example": "LIVE"
          },
          "createdAt": { "$ref": "#/components/schemas/PaymentMethodTokenCreatedAt" }
        },
        "required": ["paymentMethodId", "paymentMethod", "customerId", "status", "createdAt"]
      },
      "create-customer": {
        "required": ["customerDetails"],
        "type": "object",
        "properties": {
          "customerDetails": {
            "$ref": "#/components/schemas/BillingDetails"
          }
        }
      },
      "create-customer-response": {
        "type": "object",
        "properties": {
          "customerId": {
            "type": "string",
            "description": "Unique identifier for the created customer",
            "example": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
          }
        }
      },
      "get-customer-response": {
        "type": "object",
        "properties": {
          "customerId": {
            "type": "string",
            "description": "Unique identifier for the customer",
            "example": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
          },
          "customerDetails": {
            "$ref": "#/components/schemas/BillingDetails"
          }
        }
      },
      "DeleteTokenisedPMRequest": {
        "type": "object",
        "required": ["pmId"],
        "properties": {
            "pmId": {
                "type": "string",
                "description": "Payment method token ID to be deleted"
            }
        }
      },
      "edit-subs-request": {
        "type": "object",
        "required": ["subscriptionId"],
        "properties": {
          "subscriptionId": {
            "type": "string",
            "description": "Unique identifier of the subscription",
            "example": "sub_fooBOwYsaK50AEfK"
          },
          "newAmount": {
            "type": "integer",
            "format": "int64",
            "description": "New recurring amount for the subscription, if changed. The amount in lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (The minimum amount should be greater than 1 USD).",
            "example": 1000
          },
          "newCycleCount": {
            "type": "integer",
            "format": "int64",
            "description": "New number of billing cycles for the subscription, if changed.",
            "example": 6
          },
          "newNextPaymentDate": {
            "type": "integer",
            "format": "int64",
            "description": "New next payment date in epoch milliseconds, if changed. Future payments will be deducted at the frequency interval defined in the subscription, calculated from the new next payment date.",
            "example": 1753104947000
          },
          "interval": {
            "type": "string",
            "description": "The interval group between subscriptions.\n\n⚠️ Please note: When editing interval, `intervalCount` and `newNextPaymentDate` must also be provided.",
            "enum": ["DAY", "WEEK", "MONTH", "YEAR"],
            "example": "MONTH"
          },
          "intervalCount": {
            "type": "integer",
            "format": "int64",
            "description": "The number of intervals between subscription billings. For example, `interval = MONTH` and `intervalCount = 3` bills every 3 months.\n\n⚠️ Please note: When editing intervalCount, `interval` and `newNextPaymentDate` must also be provided.",
            "example": 2
          }
        }
      },
      "create-webhook-request": {
        "type": "object",
        "required": ["eventSigner", "endpoint", "subscribedEventTypes"],
        "properties": {
          "eventSigner": {
            "type": "string",
            "description": "Secret used to sign outbound webhook events. Provide a value that you will use to verify the signature.",
            "example": "secret_key"
          },
          "endpoint": {
            "type": "string",
            "description": "Public **HTTPS** URL where **xPay** should `POST` webhook events.",
            "example": "https://your-webhook-endpoint.com/webhook"
          },
          "subscribedEventTypes": {
            "type": "array",
            "description": "List of event types to subscribe to. Refer to [webhook events](/developer-resources/webhooks/events-list) for the full list of available events.",
            "items": {
              "type": "string"
            },
            "example": [
              "intent.created",
              "intent.success",
              "intent.failed",
              "intent.refunded",
              "intent.checkout_opened",
              "subscription.trialing",
              "subscription.cycle_charged"
            ]
          }
        }
      },
      "create-webhook-response": {
        "type": "object",
        "description": "Response payload returned after successfully creating a webhook configuration.",
        "properties": {
          "webhookConfigId": {
            "type": "string",
            "description": "Identifier of the newly created webhook configuration.",
            "example": "whc_gKAi2oZN1AeU7BfV"
          }
        },
        "required": ["webhookConfigId"]
      },
      "webhook-config": {
        "type": "object",
        "properties": {
          "webhookConfigId": {
            "type": "string",
            "description": "Unique identifier for the webhook configuration",
            "example": "whc_gKAi2oZN1AeU7BfV"
          },
          "webHookUrl": {
            "type": "string",
            "description": "Webhook endpoint URL that was registered",
            "example": "https://your-webhook-endpoint.com/webhook"
          },
          "eventSigner": {
            "type": "string",
            "description": "Secret used to sign outgoing events",
            "example": "secret_key"
          },
          "subscribedEventTypes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Events configured for this webhook",
            "example": [
              "intent.checkout_opened",
              "intent.created",
              "intent.failed",
              "intent.refunded",
              "intent.success",
              "subscription.trialing",
              "subscription.cycle_charged"
            ]
          },
          "isActive": {
            "type": "boolean",
            "description": "Indicates whether the webhook configuration is active",
            "example": true
          }
        },
        "required": ["webhookConfigId", "webHookUrl", "eventSigner", "subscribedEventTypes", "isActive"]
      },
      "get-webhooks-response": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/webhook-config"
            },
            "description": "List of webhook configurations"
          }
        },
        "required": ["data"]
      },
      "ProductPage": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Product name. Must be between 2 and 100 characters long.",
            "minLength": 2,
            "maxLength": 100,
            "example": "Premium Subscription"
          },
          "description": {
            "type": "string",
            "description": "Product description. Must be less than 500 characters long.",
            "maxLength": 500,
            "example": "Access to premium features and content"
          }
        }
      },
      "AllowedCardInstallmentTenures": {
        "type": "array",
        "description": "Optional. Restricts which Card Installment (EMI) tenures (in months) are offered at checkout. If omitted, all tenures enabled on your account are offered.",
        "items": {
          "type": "string",
          "enum": ["three", "six", "nine", "twelve"]
        },
        "example": ["three", "six"]
      },
      "CardMetadataDTO": {
        "type": "object",
        "description": "Card metadata containing additional information about the card used for payment",
        "properties": {
          "brand": {
            "type": "string",
            "description": "The brand of the card (e.g., `amex`, `diners`, `discover`, `jcb`, `mastercard`, `unionpay`, `visa`, `rupay`), among others",
            "example": "visa"
          },
          "country": {
            "type": "string",
            "description": "Country code of the card issuer",
            "example": "US"
          },
          "lastFourDigit": {
            "type": "string",
            "description": "Last 4 digits of the card number",
            "example": "4242"
          },
          "expiryMonth": {
            "type": "integer",
            "format": "int64",
            "description": "Card expiration month",
            "example": 12
          },
          "expiryYear": {
            "type": "integer",
            "format": "int64",
            "description": "Card expiration year",
            "example": 2028
          },
          "cardType": {
            "type": "string",
            "description": "Type of card funding, such as Credit or Debit",
            "enum": ["CREDIT", "DEBIT", "PREPAID", "UNKNOWN"],
            "example": "CREDIT"
          }
        }
      },
      "CardInstallmentMetadataDTO": {
        "type": "object",
        "description": "Card installment (EMI) metadata, present only for `CARD_INSTALLMENT` payments",
        "properties": {
          "cardInstallmentTenure": {
            "type": "string",
            "description": "The installment tenure (in months) selected for this payment",
            "enum": ["three", "six", "nine", "twelve"],
            "example": "three"
          }
        }
      },
      "PaymentMetadataDTO": {
        "type": "object",
        "description": "Payment metadata containing additional information about the payment attempt",
        "properties": {
          "paymentMethod": {
            "type": "string",
            "description": "The payment method used for this attempt. Refer to [supported payment methods](/get-started/payment-methods-supported#payment-method-enums) for a complete list of available payment methods.",
            "example": "CARD"
          },
          "cardMetadata": {
            "$ref": "#/components/schemas/CardMetadataDTO",
            "description": "Card-specific metadata (only present for card payments)"
          },
          "cardInstallmentMetadata": {
            "$ref": "#/components/schemas/CardInstallmentMetadataDTO",
            "description": "Card installment (EMI) metadata (only present for `CARD_INSTALLMENT` payments)"
          }
        }
      },
      "ChargeDTO": {
        "type": "object",
        "description": "Charge attempt details",
        "properties": {
          "status": {
            "type": "string",
            "description": "Status of the charge attempt",
            "example": "SUCCESS"
          },
          "paymentMetadata": {
            "$ref": "#/components/schemas/PaymentMetadataDTO",
            "description": "Payment metadata for this charge attempt"
          },
          "chargeTime": {
            "type": "integer",
            "format": "int64",
            "description": "Timestamp in epoch milliseconds when the charge was attempted",
            "example": 1727340330123
          },
          "errorCode": {
            "type": "string",
            "description": "Error code if the charge attempt failed. Refer to [error codes documentation](/products/one-time-payments/error-codes) for a complete list of possible error codes.",
            "example": "card_declined"
          }
        }
      },
      "get-payment-method-tokens-for-customer-response": {
        "type": "object",
        "description": "Response containing a list of payment method tokens for a customer",
        "properties": {
          "data": {
            "type": "array",
            "description": "List of payment method tokens, could be empty if no payment method tokens are found for the customer",
            "items": {
              "$ref": "#/components/schemas/get-payment-method-token-response"
            }
          },
          "metadata": {
            "type": "object",
            "properties": {
              "offset": { "$ref": "#/components/schemas/PaginationOffset" }
            }
          }
        },
        "required": ["data", "metadata"]
      }
    },
    "parameters": {
      "CustomerId": {
        "name": "customerId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Unique identifier of the customer"
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100 },
        "description": "Max items per page (default 50, max 100)",
        "example": 100
      },
      "Offset": {
        "name": "offset",
        "in": "query",
        "required": false,
        "schema": { "type": "string" },
        "description": "Cursor-based pagination token. Use the `offset` value from `metadata.offset` in the previous response to fetch the next page. Continue until `metadata.offset` is no longer present in the response.\n\n🚨 **Important**: Changing any query parameters invalidates existing offset values and requires restarting pagination from the beginning.\n\nFor detailed pagination implementation guide, see [Pagination Guide](/developer-resources/pagination)."
      },
      "StartTime": {
        "name": "startTime",
        "in": "query",
        "required": false,
        "schema": { "type": "integer", "format": "int64" },
        "description": "Start of range in epoch milliseconds. Fetches items created after this timestamp."
      },
      "EndTime": {
        "name": "endTime",
        "in": "query",
        "required": false,
        "schema": { "type": "integer", "format": "int64" },
        "description": "End of range in epoch milliseconds. Fetches items created before this timestamp."
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 255,
          "pattern": "^[a-zA-Z0-9\\-_:\\.]+$"
        },
        "description": "A unique key for making the request idempotent. Must match pattern: `^[a-zA-Z0-9\\-_:\\.]+$`. See [Idempotent Requests](/developer-resources/idempotency) for more details.",
        "example": "KG5LxwFBepaKHyUD"
      },
      "ConnectMerchantId": {
        "name": "x-connect-merchant-id",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "A Connect merchant ID owned by the authenticated Platform. Required when a Platform merchant creates a payment intent on behalf of a Connect merchant. See [Platform Connect](/products/platform-connect/overview).",
        "example": "me_abc123xyz"
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  }
}