> ## Documentation Index > Fetch the complete documentation index at: https://docs.xpaycheckout.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Intent > 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. ## OpenAPI ````yaml POST /payments/create-intent 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: /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' 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' components: parameters: 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 schemas: 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: type: string description: >- Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported) example: USD receiptId: type: string description: Your identifier of the order 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) 💡 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. Constraints: - Maximum of 50 key-value pairs allowed. - Each key must be no longer than 40 characters. - 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. To 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 productPage: $ref: '#/components/schemas/ProductPage' description: Product Page - showcases more about the product on the checkout page allowedCardInstallmentTenures: $ref: '#/components/schemas/AllowedCardInstallmentTenures' 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: description: Your identifier for the order type: string 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: description: Unique identifier of the intent type: string 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 Error: required: - errorCode - errorDescription type: object properties: errorCode: type: string example: bad_request errorDescription: type: string example: Failed to read request 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 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 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' securitySchemes: basicAuth: type: http scheme: basic ````