{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["image-lightbox","admonition"]},"type":"markdown"},"seo":{"title":"Flute Checkout","siteUrl":"https://developer.flute.com","description":"Documentation and API reference for integrating Flute payment processing.","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"flute-checkout","__idx":0},"children":["Flute Checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Flute Checkout is a hosted payment page that handles the entire checkout experience on your behalf. You redirect your customer to it at payment time, and once the payment is complete, Flute sends them back to your application."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Flute Checkout gives you:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PCI-DSS compliance"]},". Card data is captured and processed through Flute's secure infrastructure, never touching your servers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No frontend work"]},". A single API call creates the payment session. Flute hosts and manages the entire payment UI."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Branded experience"]},". Customize the hosted page with your logo, colors, and font to match your application."]}]},{"$$mdtype":"Tag","name":"ImageLightbox","attributes":{"src":"/img/checkout.png","alt":"Flute Checkout screen","caption":"Example of Flute Checkout screen."},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-overview","__idx":1},"children":["Integration Overview"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n autonumber\n participant C as Customer\n participant FE as Merchant Frontend\n participant BE as Merchant Backend\n participant API as Flute API\n\n BE->>API: POST /pay-int-api/payment-sessions\n API-->>BE: { \"id\": \"SESSION_ID\", \"checkoutUrl\": \"...\" }\n BE-->>FE: checkoutUrl\n\n FE->>C: Redirect to Flute Checkout\n Note over C,API: Customer completes payment on Flute-hosted page\n\n C->>FE: Redirected to returnUrl\n FE->>BE: Fetch session result\n BE->>API: GET /pay-int-api/payment-sessions/{id}\n API-->>BE: Session object\n BE-->>FE: Session result\n FE-->>C: Show result\n","diagramHtml":"Flute APIMerchant BackendMerchant FrontendCustomerFlute APIMerchant BackendMerchant FrontendCustomerCustomer completes payment on Flute-hosted pagePOST /pay-int-api/payment-sessions1{ \"id\": \"SESSION_ID\", \"checkoutUrl\": \"...\" }2checkoutUrl3Redirect to Flute Checkout4Redirected to returnUrl5Fetch session result6GET /pay-int-api/payment-sessions/{id}7Session object8Session result9Show result10","diagramHtmlDark":"Flute APIMerchant BackendMerchant FrontendCustomerFlute APIMerchant BackendMerchant FrontendCustomerCustomer completes payment on Flute-hosted pagePOST /pay-int-api/payment-sessions1{ \"id\": \"SESSION_ID\", \"checkoutUrl\": \"...\" }2checkoutUrl3Redirect to Flute Checkout4Redirected to returnUrl5Fetch session result6GET /pay-int-api/payment-sessions/{id}7Session object8Session result9Show result10"},"children":["sequenceDiagram\n autonumber\n participant C as Customer\n participant FE as Merchant Frontend\n participant BE as Merchant Backend\n participant API as Flute API\n\n BE->>API: POST /pay-int-api/payment-sessions\n API-->>BE: { \"id\": \"SESSION_ID\", \"checkoutUrl\": \"...\" }\n BE-->>FE: checkoutUrl\n\n FE->>C: Redirect to Flute Checkout\n Note over C,API: Customer completes payment on Flute-hosted page\n\n C->>FE: Redirected to returnUrl\n FE->>BE: Fetch session result\n BE->>API: GET /pay-int-api/payment-sessions/{id}\n API-->>BE: Session object\n BE-->>FE: Session result\n FE-->>C: Show result\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"building-with-flute-checkout","__idx":2},"children":["Building with Flute Checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Flute Checkout supports both card and ACH transactions. The integration follows three steps:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 1: Creating a Payment Session"]}," from the backend to get the checkout URL."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 2: Redirecting the Customer"]}," to the Flute-hosted checkout page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 3: Verifying Payment"]}," once the customer returns to your application."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1-creating-a-payment-session","__idx":3},"children":["Step 1: Creating a Payment Session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sandbox Environment:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://sandbox.api.flute.com\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Production Environment:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://api.flute.com\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create a payment session, call ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/api-reference/payment-sessions/pay_int_api_payment_sessions","style":{"textDecoration":"underline","fontWeight":"normal"}},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /pay-int-api/payment-sessions"]}]}," from the backend."," ","The following is an example request body showing the fields relevant to Flute Checkout."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/api-reference/payment-sessions/pay_int_api_payment_sessions","style":{"textDecoration":"underline","fontWeight":"normal"}},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /pay-int-api/payment-sessions"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"amount\": 500.00,\n \"returnUrl\": \"https://pay.flute.com/payments/returnUrl/{{paymentSessionId}}\",\n \"paymentMethodTypes\": [ \"card\", \"ach\" ],\n \"metadata\":\n {\n \"orderId\": \"ORD/456\",\n \"invoiceNumber\": \"INV-2026-001\"\n },\n ...\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following is a payment session response body relevant to Flute Checkout."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["amount"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"float"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction amount. If provided, Flute Checkout displays it as the payment total. If omitted, the customer is prompted to enter an amount."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["returnUrl"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The URL your customer is redirected to after the checkout flow ends. Include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{{paymentSessionId}}"]}," as a placeholder in the URL. Flute substitutes the real payment session identifier before returning the URL in the response. See the example response body for details."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["metadata"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional key-value pairs for additional context, such as an internal order ID or invoice reference. Values are sanitized for security.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Maximum of 50 key-value pairs. Maximum 40 characters per key, 500 characters per value, 8 KB for the full set."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["paymentMethodTypes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string[]"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The allowed payment types. Accepted values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"card\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"ach\""]},". Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"card\"]"]}," if omitted."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["expiresAt"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string/date-time"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional expiry timestamp in an ISO 8601 UTC date-time format, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2026-03-12T19:00:00.000Z"]},". The hosted page renders an expired error after this time, preventing further interaction. If omitted, the payment session expires in 30 minutes."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The default payment session expiry is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["30 minutes"]},"."," ","If you are using Flute Checkout for emailed payment links or other flows where the customer may not act immediately, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresAt"]}," explicitly to a longer window."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example response body:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25\",\n \"amount\": 500.00,\n \"currency\": \"USD\",\n \"status\": \"Created\",\n \"checkoutUrl\": \"https://public.flute.com/checkout/dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25\",\n \"returnUrl\": \"https://pay.flute.com/payments/returnUrl/dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25\",\n \"paymentMethodTypes\": [ \"card\", \"ach\" ],\n \"metadata\": { \"orderId\": \"ORD/456\", \"invoiceNumber\": \"INV-2026-001\" },\n \"createdAt\": \"2026-03-12T19:00:00.000Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following is a payment session response body relevant to Flute Checkout."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["id"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The payment session identifier. Use this value when redirecting to Flute Checkout."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["checkoutUrl"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The fully-formed checkout URL. Redirect your customer to this URL to start the checkout flow."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["returnUrl"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The URL the customer is redirected to after the checkout flow ends, with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{{paymentSessionId}}"]}," substituted with the real payment session identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["metadata"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The key-value pairs provided in the request, echoed back in the response."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-redirecting-the-customer","__idx":4},"children":["Step 2: Redirecting the Customer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}," from the session creation response to send the customer to Flute Checkout. Use one of the following methods:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"server-side-or-direct-redirect","__idx":5},"children":["Server-side or direct redirect"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}," is a fully-formed URL unique to the customer's payment session."," ","Redirect to it directly from your server or pass it to any of the client-side methods below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"using-the-flutejs-library","__idx":6},"children":["Using the Flute.js library"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Load the Flute.js library and call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flute.checkoutPage()"]}," with the payment session identifier."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"\n \n\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const flute = new window.Flute();\nflute.checkoutPage('dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25')\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"client-side-browser-redirect","__idx":7},"children":["Client-side browser redirect"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"window.location.href = \"https://public.flute.com/checkout/dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25\";\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3-verifying-payment","__idx":8},"children":["Step 3: Verifying Payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the payment session is completed, cancelled, or expired, the customer is redirected to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]}," you provided at payment session creation."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{{paymentSessionId}}"]}," placeholder in the URL is substituted with the actual payment session identifier, which you can use to look up the result from the backend."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]}," was set, the customer remains on the Flute-hosted page and sees a generic confirmation message."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always verify the payment result from the backend."," ","Never rely on the frontend or the redirect URL alone."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call the following endpoint after receiving the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_session.completed"]}," webhook or after the customer is redirected to your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]},":"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/api-reference/payment-sessions/pay_int_api_payment_sessions_paymentsessionid","style":{"textDecoration":"underline","fontWeight":"normal"}},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /pay-int-api/payment-sessions/{paymentSessionId}"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Subscribe to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_session.completed"]}," webhook to be notified when a payment session reaches a terminal state."," ","This is the recommended approach. As a fallback, you can poll the endpoint above and check for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Completed"]}," status."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As the customer interacts with Flute Checkout, the payment session moves through these states:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Created"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment session was initialized but not yet processed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Completed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment session was completed. Check transaction details to verify if the payment was approved or not."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancelled"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment session was canceled before completion."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Expired"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment session expired before being completed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment was attempted but did not succeed. A new payment session must be created for a new payment attempt."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 3.1: Check the payment session status"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The payment session-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," field must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Completed"]},"."," ","This confirms the customer went through the checkout flow, but does not by itself confirm the payment was approved."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 3.2: Check the transaction status"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionDetails.status"]}," against the expected success statuses for your payment type:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Card payments"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"transactionDetails.status"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionDetails.status"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment authorized, pending capture."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Captured"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment captured."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PartiallyAuthorized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Partial amount authorized."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACH payments"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"transactionDetails.status"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionDetails.status"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Scheduled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment scheduled for processing."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["InProgress"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submission accepted and being processed."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additional statuses may appear on subsequent lookups as the payment progresses through its lifecycle."," ","For example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Settled"]}," for card payments and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Cleared"]}," for ACH payments."," ","These do not require any action on your end."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Any other status (including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Declined"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Failed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Voided"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Cancelled"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ChargedBack"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Held"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HeldByProcessor"]},") indicates the payment did not succeed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Other useful fields"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionDetails.transactionReceipt.amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Charged amount (in USD)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionDetails.transactionReceipt.transactionId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Metadata provided at payment session creation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer record associated with the payment, if a payment method was saved."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"faster-checkout-for-returning-customers","__idx":9},"children":["Faster Checkout for Returning Customers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a payment session is created with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerId"]}," that has saved payment methods on file, Flute Checkout automatically surfaces those methods on the payment page."," ","The customer can select a saved card or bank account and complete the payment without re-entering their details, providing a faster checkout experience for returning users."]},{"$$mdtype":"Tag","name":"ImageLightbox","attributes":{"src":"/img/faster-checkout.png","alt":"Flute Checkout with saved payment methods","caption":"Flute Checkout showing saved payment methods for a returning customer."},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerId"]}," when creating the payment session:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"amount\": 144.00,\n \"returnUrl\": \"https://pay.flute.com/payments/returnUrl/{{paymentSessionId}}\",\n \"customerId\": \"CUSTOMER_ID\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}," grants access to any saved payment methods linked to the payment session's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerId"]},"."," ","Keep it private."," ","Treat it like a one-time payment token."," ","Generate it at checkout time, send it directly to the authenticated customer, and never share or publicly expose it."," ","Anyone with access to the URL can use those saved methods to complete the payment."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":10},"children":["Error Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section describes possible errors, following the Flute error format."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Status"},"children":["HTTP Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error Type"},"children":["Error Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["validation_error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid input.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"This means the request was rejected before reaching the processor. No transaction was created and the session status remains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Created"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["authentication_error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid OAuth token.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Check for missing, expired, or invalid credentials."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["authorization_error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request is forbidden.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"The caller is authenticated but not authorized to perform the action. Check API key permission levels."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["not_found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment session not found."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["409"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["conflict"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment session not in valid state for operation.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"The request is valid and well formed. Fulfilling the request would conflict with an existing resource state. Common examples include registering the same webhook endpoint twice or attempting to void a transaction that has already settled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["422"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["payment_error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment declined or processing error.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"The submission was rejected after reaching the processor. The payment session is now ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Failed"]},". A new payment session must be created for another payment attempt."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["429"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["rate_limit_error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit exceeded on public endpoints.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Reduce the request rate or wait before retrying."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["internal_error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server error."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following is an example returned error."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"error\":\n {\n \"type\": \"validation_error\",\n \"message\": \"Invalid payment method type\",\n \"details\": [{ \"field\": \"paymentMethodTypes\", \"message\": \"Allowed values: 'card', 'ach'\" }]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"branding-flute-checkout","__idx":11},"children":["Branding Flute Checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The hosted checkout page can be customized so it feels like part of your own website."," ","Configurable components include the merchant logo, font, accent color, and page background color."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To configure these branding options:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Navigate to the partner's ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://dashboard.flute.com/dashboard","target":"_blank","rel":"noopener noreferrer"},"children":["Flute dashboard page"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant"]}," from the left menu panel."," ","This displays the list of merchants for the partner."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select the individual merchant."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Impersonate merchant"]},"."," ","This allows the partner to act on behalf of the merchant."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings"]}," from the left menu panel."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Profile"]}," in the right navigation panel. This displays the branding options page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select options under the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Branding and customization"]}," section."]}]}]},"headings":[{"value":"Flute Checkout","id":"flute-checkout","depth":1},{"value":"Integration Overview","id":"integration-overview","depth":2},{"value":"Building with Flute Checkout","id":"building-with-flute-checkout","depth":2},{"value":"Step 1: Creating a Payment Session","id":"step-1-creating-a-payment-session","depth":3},{"value":"Step 2: Redirecting the Customer","id":"step-2-redirecting-the-customer","depth":3},{"value":"Server-side or direct redirect","id":"server-side-or-direct-redirect","depth":4},{"value":"Using the Flute.js library","id":"using-the-flutejs-library","depth":4},{"value":"Client-side browser redirect","id":"client-side-browser-redirect","depth":4},{"value":"Step 3: Verifying Payment","id":"step-3-verifying-payment","depth":3},{"value":"Faster Checkout for Returning Customers","id":"faster-checkout-for-returning-customers","depth":2},{"value":"Error Handling","id":"error-handling","depth":2},{"value":"Branding Flute Checkout","id":"branding-flute-checkout","depth":2}],"frontmatter":{"title":"Flute Checkout","description":"Accept payments through a Flute-hosted checkout page with no frontend integration required.","seo":{"title":"Flute Checkout"}},"lastModified":"2026-09-15T06:57:09.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/online-payments/flute-checkout","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}