{
    "openapi": "3.0.0",
    "paths": {
        "/checkout/stripe": {
            "post": {
                "description": "Initiates a Stripe Checkout session. Supports both Guest and Authenticated customers. Note: Authentication is required for recurring items (subscriptions). If the user is authenticated, he must have verified his email.",
                "operationId": "CheckoutStripe",
                "parameters": [
                    {
                        "name": "store-id",
                        "in": "header",
                        "description": "Store identifier",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CheckoutStripeInputDTO"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Stripe session created successfully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "url": {
                                            "type": "string",
                                            "description": "The unique Stripe Checkout URL where the user should be redirected.",
                                            "example": "https://checkout.stripe.com/c/pay/cs_test_..."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request - Validation or Business Logic errors.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "statusCode": {
                                            "type": "number",
                                            "example": 400
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Bad Request"
                                        }
                                    }
                                },
                                "examples": {
                                    "unverifiedEmail": {
                                        "summary": "Unverified email",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "Please, verify your email address before completing the purchase",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "missingShipping": {
                                        "summary": "Missing shipping method",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "Please select a shipping method.",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "inconsistentCart": {
                                        "summary": "Inconsistent currency/cadence",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "All articles must have the same currency/cadence",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "limitExceeded": {
                                        "summary": "Items limit exceeded",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "Exceeded the total items in the cart for this type of order",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "authRequiredRecurring": {
                                        "summary": "Auth required (Recurring)",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "You must be authenticated in order to buy an item with a recurring billing.",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "stripeConfigError": {
                                        "summary": "Stripe config error",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "SKU is not configured correctly.",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "taxCompatibility": {
                                        "summary": "Tax compatibility error",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "The product is not compatible with other items in your cart.",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "unknownCountry": {
                                        "summary": "Unknown shipping country",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "Shipping country is unknown for product [NAME]",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "noShippingMethods": {
                                        "summary": "No shipping available",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "No shipping method available for the selected country.",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "exclusivePromo": {
                                        "summary": "Exclusive promo conflict",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "Promotion \"CODE\" cannot be combined with other codes",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "promoExpired": {
                                        "summary": "Promotion expired",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "Promotion expired",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "authRequiredPromo": {
                                        "summary": "Auth required (Promo)",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "Authentication required. Please login.",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "promoLimitReached": {
                                        "summary": "Promo limit reached",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "This promotion has reached its global usage limit",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "minAmount": {
                                        "summary": "Min amount not reached",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "Minimum order amount is 50 EUR to apply the promotion CODE",
                                            "error": "Bad Request"
                                        }
                                    },
                                    "promoNotApplicable": {
                                        "summary": "Promo not applicable",
                                        "value": {
                                            "statusCode": 400,
                                            "message": "Promotion \"CODE\" is not available for variant \"NAME\"",
                                            "error": "Bad Request"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden - Stripe integration issues.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "statusCode": {
                                            "type": "number",
                                            "example": 403
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Forbidden"
                                        }
                                    }
                                },
                                "examples": {
                                    "missingStore": {
                                        "summary": "Missing Store ID",
                                        "value": {
                                            "statusCode": 403,
                                            "message": "Missing storeId",
                                            "error": "Forbidden"
                                        }
                                    },
                                    "notIntegrated": {
                                        "summary": "Stripe not properly integrated",
                                        "value": {
                                            "statusCode": 403,
                                            "message": "The store has not integrated Stripe properly",
                                            "error": "Forbidden"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Promotion code not found or inactive.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "statusCode": {
                                            "type": "number",
                                            "example": 404
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Invalid or inactive promotion code(s)"
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Not Found"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error during Stripe session creation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "statusCode": {
                                            "type": "number",
                                            "example": 500
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "There was an error when creating the session. Please contact us if the error persists"
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Internal Server Error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearer": []
                    }
                ],
                "summary": "Start Stripe Checkout",
                "tags": [
                    "Checkout"
                ]
            }
        }
    },
    "info": {
        "title": "Webround Commerce Checkout APIs",
        "description": "The Webround Commerce Checkout APIs documentation for Webround software",
        "version": "1.0",
        "contact": {}
    },
    "tags": [],
    "servers": [
        {
            "url": "https://checkout-api.webround.com",
            "description": "Production Server"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearer": {
                "scheme": "bearer",
                "bearerFormat": "JWT",
                "type": "http"
            }
        },
        "schemas": {
            "CheckoutCartItemDTO": {
                "type": "object",
                "properties": {
                    "variantId": {
                        "type": "string",
                        "format": "uuid",
                        "example": "b089f57c-4d86-4d9f-bb01-84c6b13b4f88"
                    },
                    "quantity": {
                        "type": "number",
                        "example": 1,
                        "minimum": 1,
                        "maximum": 10000
                    },
                    "priceId": {
                        "type": "string",
                        "format": "uuid",
                        "example": "7f58d339-f138-4d8d-94a2-2fa842f262c5"
                    }
                },
                "required": [
                    "variantId",
                    "quantity",
                    "priceId"
                ]
            },
            "CustomerAddressDTO": {
                "type": "object",
                "properties": {
                    "fullName": {
                        "type": "string",
                        "example": "Mario Rossi"
                    },
                    "company": {
                        "type": "string",
                        "example": "ACME S.r.l."
                    },
                    "vatCode": {
                        "type": "string",
                        "example": "01234567891",
                        "maxLength": 32
                    },
                    "phone": {
                        "type": "string",
                        "example": "+393331234567"
                    },
                    "addressLine1": {
                        "type": "string",
                        "example": "Via Roma 123"
                    },
                    "addressLine2": {
                        "type": "string",
                        "example": "Scala B, interno 7"
                    },
                    "city": {
                        "type": "string",
                        "example": "Milano"
                    },
                    "province": {
                        "type": "string",
                        "example": "MI"
                    },
                    "postalCode": {
                        "type": "string",
                        "example": "20100"
                    },
                    "countryCode": {
                        "type": "string",
                        "example": "IT",
                        "description": "ISO 3166-1 alpha-2 country code"
                    },
                    "additionalInfo": {
                        "type": "string",
                        "example": "Palazzo giallo"
                    }
                },
                "required": [
                    "fullName",
                    "addressLine1",
                    "city",
                    "postalCode",
                    "countryCode"
                ]
            },
            "CheckoutStripeInputDTO": {
                "type": "object",
                "properties": {
                    "langCode": {
                        "type": "string",
                        "enum": [
                            "af",
                            "am",
                            "sq",
                            "ar",
                            "hy",
                            "az",
                            "eu",
                            "be",
                            "bn",
                            "bs",
                            "bg",
                            "ca",
                            "ceb",
                            "ny",
                            "zh",
                            "co",
                            "hr",
                            "cs",
                            "da",
                            "nl",
                            "sjn",
                            "en",
                            "eo",
                            "et",
                            "tl",
                            "fo",
                            "fj",
                            "fi",
                            "fr",
                            "fy",
                            "gl",
                            "ka",
                            "de",
                            "el",
                            "gu",
                            "haw",
                            "ht",
                            "ha",
                            "he",
                            "hi",
                            "hmn",
                            "hu",
                            "is",
                            "ig",
                            "id",
                            "iu",
                            "iku",
                            "ga",
                            "it",
                            "ja",
                            "jw",
                            "kk",
                            "kn",
                            "km",
                            "ko",
                            "kok",
                            "ky",
                            "ku",
                            "ckb",
                            "sdh",
                            "lo",
                            "lv",
                            "lt",
                            "lb",
                            "mk",
                            "mg",
                            "ms",
                            "ml",
                            "mt",
                            "mr",
                            "mn",
                            "mi",
                            "my",
                            "ne",
                            "no",
                            "pap",
                            "fa",
                            "pl",
                            "pt",
                            "pa",
                            "ps",
                            "otq",
                            "ro",
                            "ru",
                            "sm",
                            "gd",
                            "sr",
                            "sr-LA",
                            "sd",
                            "si",
                            "sk",
                            "sl",
                            "sn",
                            "st",
                            "so",
                            "es",
                            "su",
                            "sw",
                            "sv",
                            "ty",
                            "ta",
                            "tg",
                            "te",
                            "th",
                            "bo",
                            "to",
                            "tr",
                            "uk",
                            "ur",
                            "uz",
                            "vi",
                            "cy",
                            "xh",
                            "yi",
                            "yo",
                            "yua",
                            "yue",
                            "zu",
                            "default"
                        ],
                        "default": "default",
                        "example": "it"
                    },
                    "cartItems": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/CheckoutCartItemDTO"
                        }
                    },
                    "email": {
                        "type": "string",
                        "example": "user@email.com"
                    },
                    "cartTrackingId": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "promotionCodes": {
                        "maxItems": 10,
                        "example": [
                            "PROMO20"
                        ],
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "shippingMethodId": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "deliveryMethods": {
                        "type": "string",
                        "enum": [
                            "pickup",
                            "shipping",
                            "digital",
                            "none"
                        ],
                        "example": {
                            "b089f57c-4d86-4d9f-bb01-84c6b13b4f88": "shipping"
                        }
                    },
                    "shippingAddress": {
                        "$ref": "#/components/schemas/CustomerAddressDTO"
                    },
                    "billingAddress": {
                        "$ref": "#/components/schemas/CustomerAddressDTO"
                    },
                    "requestsInvoice": {
                        "type": "boolean"
                    },
                    "successUrl": {
                        "type": "string",
                        "example": "https://example.com/success",
                        "description": "The redirection URL after the Stripe Checkout Page. The hostname defaults to store domain. If the URL is submitted, hostname must be in the store's domains whitelist."
                    },
                    "cancelUrl": {
                        "type": "string",
                        "example": "https://example.com/cancel",
                        "description": "The redirection URL after the Stripe Checkout Page. The hostname defaults to store domain. If the URL is submitted, hostname must be in the store's domains whitelist."
                    },
                    "additionalData": {
                        "type": "object",
                        "example": {
                            "custom_data": "1234"
                        }
                    }
                },
                "required": [
                    "langCode",
                    "cartItems",
                    "email",
                    "deliveryMethods"
                ]
            }
        }
    }
}