> ## Documentation Index > Fetch the complete documentation index at: https://docs.craveup.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or recover the authoritative cart payment session ## OpenAPI ````yaml /generated/storefront.openapi.json post /locations/{locationId}/carts/{cartId}/payment-session openapi: 3.0.3 info: title: Crave Storefront API version: 2.0.0 description: >- Direct public Storefront API. Anonymous catalog reads require no API key. Protected resources use purpose-limited cart, checkout, receipt, or customer credentials. contact: name: Crave Support email: hello@craveup.com servers: - url: https://api.craveup.com/api/v1/storefront description: Production Storefront API - url: https://dev-api-43233223.craveup.com/api/v1/storefront description: Sandbox Storefront API security: [] tags: - name: Merchants - name: Locations - name: Ordering Sessions - name: Menus - name: Products - name: Analytics - name: Carts - name: Checkout - name: Cart Items - name: Discounts - name: Loyalty - name: Customer Authentication - name: Customers - name: Orders paths: /locations/{locationId}/carts/{cartId}/payment-session: post: tags: - Checkout summary: Create or recover the authoritative cart payment session operationId: storefrontCreatePaymentSession parameters: - name: locationId in: path required: true schema: type: string minLength: 1 maxLength: 128 - name: cartId in: path required: true schema: type: string minLength: 1 maxLength: 128 - name: Idempotency-Key in: header required: true description: Caller-stable key reused only for retries of this exact request. schema: type: string minLength: 16 maxLength: 128 pattern: ^[A-Za-z0-9._:-]{16,128}$ - name: If-Match in: header required: true description: Current cart ETag returned by the API. schema: type: string pattern: ^(?:W/)?"cart-(?:0|[1-9][0-9]*)"$ requestBody: required: false content: application/json: schema: type: object properties: {} additionalProperties: false responses: '200': description: Authoritative checkout payment session. content: application/json: schema: $ref: '#/components/schemas/CheckoutPaymentSession' headers: ETag: description: >- Current resource revision tag. Send it in If-Match before mutation. schema: type: string Cache-Control: schema: type: string example: private, no-store '400': description: The request is invalid. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '401': description: Authentication or capability authorization is required. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '403': description: The authenticated principal does not own this resource. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '404': description: The requested resource was not found. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '409': description: The idempotency key or resource revision conflicts. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '428': description: A current If-Match resource revision is required. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '429': description: The request was rate limited. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '500': description: An unexpected error occurred. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '503': description: A required dependency is temporarily unavailable. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' security: - StorefrontCartCapability: [] - StorefrontCustomerAuth: [] components: schemas: CheckoutPaymentSession: oneOf: - type: object properties: provider: type: string enum: - STRIPE clientSecret: type: string minLength: 1 quote: type: object properties: revision: type: string minLength: 1 maxLength: 128 total: type: object properties: amount: type: integer minimum: 0 maximum: 9007199254740991 currency: type: string enum: - USD - GBP - AED - AUD required: - amount - currency additionalProperties: false tip: type: object properties: amount: type: integer minimum: 0 maximum: 9007199254740991 currency: type: string enum: - USD - GBP - AED - AUD required: - amount - currency additionalProperties: false required: - revision - total - tip additionalProperties: false required: - provider - clientSecret - quote additionalProperties: false - type: object properties: provider: type: string enum: - SQUARE applicationId: type: string minLength: 1 locationId: type: string minLength: 1 environment: type: string enum: - sandbox - production countryCode: type: string minLength: 2 maxLength: 2 quote: type: object properties: revision: type: string minLength: 1 maxLength: 128 total: type: object properties: amount: type: integer minimum: 0 maximum: 9007199254740991 currency: type: string enum: - USD - GBP - AED - AUD required: - amount - currency additionalProperties: false tip: type: object properties: amount: type: integer minimum: 0 maximum: 9007199254740991 currency: type: string enum: - USD - GBP - AED - AUD required: - amount - currency additionalProperties: false required: - revision - total - tip additionalProperties: false remaining: type: object properties: amount: type: integer minimum: 0 maximum: 9007199254740991 currency: type: string enum: - USD - GBP - AED - AUD required: - amount - currency additionalProperties: false approvedTenders: type: array items: type: object properties: paymentId: type: string minLength: 1 tenderType: type: string enum: - CARD - GIFT_CARD - STORED_CARD - WALLET approvedAmount: type: object properties: amount: type: integer minimum: 0 maximum: 9007199254740991 currency: type: string enum: - USD - GBP - AED - AUD required: - amount - currency additionalProperties: false required: - paymentId - tenderType - approvedAmount additionalProperties: false required: - provider - applicationId - locationId - environment - countryCode - quote - remaining - approvedTenders additionalProperties: false - type: object properties: provider: type: string enum: - CLOVER apiAccessKey: type: string minLength: 1 merchantId: type: string minLength: 1 environment: type: string enum: - sandbox - production quote: type: object properties: revision: type: string minLength: 1 maxLength: 128 total: type: object properties: amount: type: integer minimum: 0 maximum: 9007199254740991 currency: type: string enum: - USD - GBP - AED - AUD required: - amount - currency additionalProperties: false tip: type: object properties: amount: type: integer minimum: 0 maximum: 9007199254740991 currency: type: string enum: - USD - GBP - AED - AUD required: - amount - currency additionalProperties: false required: - revision - total - tip additionalProperties: false required: - provider - apiAccessKey - merchantId - environment - quote additionalProperties: false CommerceErrorEnvelope: type: object properties: code: anyOf: - type: string enum: - VALIDATION_ERROR - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - RATE_LIMITED - CART_CONFLICT - REQUOTE_REQUIRED - RESOURCE_CONFLICT - CART_IMMUTABLE - IDEMPOTENCY_KEY_REQUIRED - IDEMPOTENCY_KEY_REUSED - IDEMPOTENCY_IN_PROGRESS - DEPENDENCY_UNAVAILABLE - INTERNAL_ERROR - type: string minLength: 1 message: type: string minLength: 1 requestId: type: string minLength: 8 details: type: object additionalProperties: {} required: - code - message - requestId additionalProperties: false securitySchemes: StorefrontCartCapability: type: apiKey in: header name: X-Cart-Token description: Purpose-limited capability returned for a guest cart. StorefrontCustomerAuth: type: http scheme: bearer bearerFormat: JWT description: Merchant-bound customer session JWT returned by OTP verification. ````