> ## Documentation Index > Fetch the complete documentation index at: https://docs.boomfi.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Create checkout session > Open a checkout session and return the client secret the merchant's page passes to @boomfi-sdk/connect-web. The secret is returned once, by this call only; repeating merchant_request_id with the same parameters returns the existing session with client_secret absent. ## OpenAPI ````yaml /openapi.yaml post /checkout/sessions openapi: 3.1.0 info: contact: email: support@boomfi.xyz name: API Support description: >- The BoomFi Merchants API provides a set of endpoints for merchants to manage their accounts, transactions, and more. Hosts differ per brand/environment; use the brand-specific base URL from the docs. title: BoomFi Merchants API version: '1.0' servers: - url: https://mapi.boomfi.xyz/v1 description: Production - url: https://mapi-test.boomfi.xyz/v1 description: Test security: [] tags: - description: Payment links name: Paylinks - description: Billing plans name: Plans - description: Subscriptions name: Subscriptions - description: Customer records name: Customers - description: Invoices name: Invoices - description: Payments name: Payments - description: Organisation events name: Events - description: Organisation profile and display settings name: Organisation - description: Webhook and request-signing secrets name: Secrets - description: Settlement accounts name: Accounts - name: External Accounts - description: Managed virtual accounts, balances, pay-in, and payout name: Virtual Accounts - description: Partner-managed accounts, virtual accounts, pay-in, and payout name: Partners - description: Partner maintain-balance automations name: Partner Balance Monitoring - name: Checkout Sessions paths: /checkout/sessions: post: tags: - Checkout Sessions summary: Create checkout session description: >- Open a checkout session and return the client secret the merchant's page passes to @boomfi-sdk/connect-web. The secret is returned once, by this call only; repeating merchant_request_id with the same parameters returns the existing session with client_secret absent. requestBody: content: application/json: schema: $ref: '#/components/schemas/checkoutsession.CreateSessionRequest' description: Checkout session parameters required: true responses: '200': description: Idempotency key replayed; client_secret is absent content: application/json: schema: $ref: >- #/components/schemas/internal.Response-checkoutsession_CreateSessionResponse '201': description: Created content: application/json: schema: $ref: >- #/components/schemas/internal.Response-checkoutsession_CreateSessionResponse '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' security: - ApiKeyAuth: [] components: schemas: checkoutsession.CreateSessionRequest: properties: allowed_origin: description: >- The registered origin permitted to frame this session. Embedded only — a hosted or lite checkout is not framed. May be omitted when the organisation has registered exactly one. example: https://shop.example type: string amount: description: Amount to charge. Must currently match the payment link's own price. example: '248.00' type: string cancel_url: description: >- Where a hosted or lite checkout sends a payer who abandons it. Same rules as success_url, but optional. example: https://shop.example/cart maxLength: 2048 type: string config: description: >- Passed through to the checkout. No credentials and nothing about the payer — it is served to whoever holds the public embed handle. type: object currency: description: Currency to charge in. Must currently match the payment link's own. example: EUR type: string customer_reference: description: Your own identifier for the payer. Not shown to them. example: user_4815 maxLength: 255 type: string expires_in: description: >- Seconds until the session stops accepting new bindings. Defaults to 86400, bounded 1800-86400, as Stripe's. example: 86400 maximum: 86400 minimum: 1800 type: integer locale: description: Preferred display locale. example: en-GB maxLength: 35 type: string merchant_request_id: description: >- Your idempotency key. Repeating one with the same parameters returns the session it already created; repeating it with different parameters is a conflict. example: dep_92817 maxLength: 255 type: string mode: description: What the session collects. Only Payment is supported so far. enum: - Payment - Subscription - Rfq example: Payment type: string payment_link_id: description: >- Payment link the session opens. Omit for a session with no paylink behind it. example: 2ZxK1qLm9vQnR7sT4uY6wB8cD0e type: string redirect_on_completion: description: >- Whether an embedded checkout redirects to return_url on completion. Embedded only; never is refused if a redirect-based payment method (e.g. Binance Pay) is available. enum: - always - if_required - never example: if_required type: string return_url: description: >- Where an embedded checkout returns the payer. Embedded only; must be on allowed_origin. Required unless redirect_on_completion is never. example: https://shop.example/deposit/result maxLength: 2048 type: string success_url: description: >- Where a hosted or lite checkout sends the payer once it completes. Required for those modes, rejected for Embedded, and must be on one of your registered origins. example: https://shop.example/deposit/done maxLength: 2048 type: string ui_mode: description: How the checkout is presented. enum: - Hosted - Embedded - Lite example: Embedded type: string type: object internal.Response-checkoutsession_CreateSessionResponse: properties: data: allOf: - $ref: '#/components/schemas/checkoutsession.CreateSessionResponse' description: Response payload when the request succeeded. error: description: True when the request failed. type: boolean message: description: Human-readable status or error message. type: string type: object internal.ErrorResponse: properties: error: allOf: - $ref: '#/components/schemas/internal.ErrorStruct' description: Error details including HTTP-style code and message. type: object checkoutsession.CreateSessionResponse: properties: activated_at: type: string allowed_origin: type: string amount: type: string cancel_url: type: string client_secret: description: >- Returned exactly once, by the call that created the session. Stored only as a digest, so a repeated create returns the existing session with this field absent rather than a secret that cannot be reconstructed. type: string completed_at: type: string config: type: object created_at: type: string currency: type: string customer_reference: type: string expired_at: type: string expires_at: description: When the session stops accepting new bindings. type: string id: description: Unique session identifier (cs_...). type: string locale: type: string merchant_request_id: type: string mode: enum: - Payment - Subscription - Rfq type: string payment_id: type: string payment_link_id: type: string payment_status: description: Money state, mirroring the payment this session produced. type: string return_url: type: string revoked_reason: description: >- Why the session was expired early, when it was not the clock that did it. type: string status: enum: - Open - Complete - Expired type: string success_url: type: string ui_mode: enum: - Hosted - Embedded - Lite type: string type: object internal.ErrorStruct: properties: code: description: |- Error code Example: 400 example: 400 type: integer errors: description: List of errors items: $ref: '#/components/schemas/internal.SingleError' type: array message: description: |- Error message Example: Insufficient quantity example: Insufficient quantity type: string type: object internal.SingleError: properties: domain: description: |- Domain Example: orders example: orders type: string reason: description: |- Error Reason Example: InsufficientQuantity example: InsufficientQuantity type: string type: object securitySchemes: ApiKeyAuth: in: header name: X-API-KEY type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.