Withdraw

{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-walkthrough","badge","download-button","admonition","step"]},"redocly_category":"Documentation","type":"markdown"},"seo":{"title":"Integrate a withdrawal form","description":"Learn how to integrate an embedded withdrawal form.","siteUrl":"https://www.rebilly.com","image":"/assets/rebillysocial.94fb32fc280c9e84b963c440ec462771d25f4e6fdaaa6c59de41e8135113b46b.db81178d.png","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeWalkthrough","attributes":{"__idx":1,"preview":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is an interactive example of a withdrawal form that uses the Cashier JavaScript library."]},{"$$mdtype":"Tag","name":"iframe","attributes":{"src":"/examples/cashier/withdraw/withdraw.html","style":{"margin":"8px auto","width":"80%","height":"874px","border":"0","borderRadius":"12px"},"scrolling":"yes","loading":"lazy"},"children":[]}],"filters":{},"filesets":[{"files":[{"path":"docs/dev-docs/_code-samples/integrate-a-withdraw-form/server.js","content":[{"start":0,"condition":{"steps":["install-and-initialize-dependencies"]},"children":["import express from \"express\";","import RebillyAPI from \"rebilly-js-sdk\";","","const app = express();"]},"",{"start":7,"condition":{"steps":["provide-credentials"]},"children":["const API_SECRET_KEY = \"SECRET_KEY\";","const ORGANIZATION_ID = \"ORGANIZATION_ID\";","const WEBSITE_ID = \"WEBSITE_ID\";"]},"",{"start":13,"condition":{"steps":["initialize-rebilly-js-sdk"]},"children":["const rebilly = RebillyAPI({"," organizationId: ORGANIZATION_ID,"," sandbox: true,"," apiKey: API_SECRET_KEY,"," timeout: 5000,","});"]},"","app.use(express.static(\"public\"));","",{"start":24,"condition":{"steps":["define-route-for-post-requests"]},"children":["app.post(\"/create-cashier\", async (req, res) => {"," try {"," const response = await rebilly.cashiers.create({"," data: {"," websiteId: WEBSITE_ID,",{"start":30,"condition":{"steps":["provide-customer-id"]},"children":[" customerId: \"{{ CUSTOMER_ID }}\","]},{"start":33,"condition":{"steps":["provide-currency"]},"children":[" currency: \"{{ CURRENCY }}\","]}," },"," });",""," const cashierToken = response.fields.cashierToken;",""," res.send({ cashierToken });"," } catch (error) {"," if (error?.response?.data) {"," console.error(error.response.data);"," } else {"," console.error(error);"," }"," res.status(500).json({ error: \"Failed to create cashier token\" });"," }","});"]},"","app.listen(8080, () => console.log(\"Running on port 8080\"));",""],"metadata":{"steps":["install-and-initialize-dependencies","provide-credentials","initialize-rebilly-js-sdk","define-route-for-post-requests","provide-customer-id","provide-currency"]},"basename":"server.js","language":"javascript"}],"downloadAssociatedFiles":[]},{"files":[{"path":"docs/dev-docs/_code-samples/integrate-a-withdraw-form/public/index.html","content":["",""," "," Withdraw",{"start":4,"condition":{"steps":["install-the-library"]},"children":[" "]}," ",{"start":8,"condition":{"steps":["add-custom-styling"]},"children":[" "]}," "," ",{"start":20,"condition":{"steps":["add-a-container-element"]},"children":["

"]}," ","",""],"metadata":{"steps":["install-the-library","add-custom-styling","add-a-container-element"]},"basename":"index.html","language":"html"}],"downloadAssociatedFiles":[]},{"files":[{"path":"docs/dev-docs/_code-samples/integrate-a-withdraw-form/public/withdraw.js","content":[{"start":0,"condition":{"steps":["render-the-withdraw-form"]},"children":["async function setup() {"," const response = await fetch(\"http://localhost:8080/create-cashier\", {"," method: \"POST\","," headers: {"," Accept: \"application/json\","," \"Content-Type\": \"application/json\","," },"," });"," const data = await response.json();",""," const mountElement = document.querySelector(\"#withdraw\");"," const cashierToken = data.cashierToken;",""," if (window.RebillyCashier) {"," window.RebillyCashier.renderWithdraw({"," mountElement,"," cashierToken,",{"start":18,"condition":{"steps":["handle-complete-action"]},"children":[" completeAction: (type) => {"," console.log(\"Complete action triggered with type:\", type);"," },"]}," });"," } else {"," console.error(\"RebillyCashier library not loaded\");"," }","}","","setup();"]},"",{"start":32,"condition":{"steps":["handle-withdrawal-completed"]},"children":["window.RebillyCashier.on(\"withdrawal-completed\", (payoutRequest) => {"," console.log(\"Withdrawal completed:\", payoutRequest);","});"]},""],"metadata":{"steps":["render-the-withdraw-form","handle-complete-action","handle-withdrawal-completed"]},"basename":"withdraw.js","language":"javascript"}],"downloadAssociatedFiles":[]},{"downloadAssociatedFiles":[{"path":"docs/dev-docs/_code-samples/integrate-a-withdraw-form/package.json","content":["{"," \"name\": \"rebilly-cashier-withdraw-example\","," \"version\": \"1.0.0\","," \"main\": \"server.js\","," \"scripts\": {"," \"dev\": \"node server.js\""," },"," \"author\": \"Rebilly\","," \"license\": \"MIT\","," \"dependencies\": {"," \"express\": \"^4.21.2\","," \"rebilly-js-sdk\": \"^60.10.0\""," },"," \"type\": \"module\"","}",""],"metadata":{"steps":[]},"basename":"package.json","language":"text"}],"files":[]},{"downloadAssociatedFiles":[{"path":"docs/dev-docs/_code-samples/integrate-a-withdraw-form/README.md","content":["# Integrate a withdrawal form","","This example describes how to integrate and embed a customizable, white-label withdrawal form into your website using the Cashier JavaScript library, the [Rebilly JS SDK](https://www.npmjs.com/package/rebilly-js-sdk), and [Express JS](https://expressjs.com/en/starter/installing.html).","","To view the integration guide, see [Integrate a withdrawal form](https://www.rebilly.com/docs/dev-docs/integrate-a-withdraw-form/).","","## Setup","","1. Install dependencies: `npm install`","","2. Configure credentials:","","> In production, we recommend using a secrets manager to store your secret key instead of including it alongside code.","","In `server.js`:","","- Assign values for `API_SECRET_KEY`, `ORGANIZATION_ID`, `WEBSITE_ID`.","- Replace `{{ CUSTOMER_ID }}` and `{{ CURRENCY }}` with a customer ID and a currency code in ISO 4217 format.","","## Run the sample application","","1. Start the server: `node server.js`","2. Open the application: [http://localhost:8080](http://localhost:8080).","","## Error handling","","Errors from the server are logged to your console.","Check the developer tools in your web browser for client-side errors.",""],"metadata":{"steps":[]},"basename":"README.md","language":"markdoc"}],"files":[]}],"steps":[{"id":"install-and-initialize-dependencies","heading":"Install and initialize dependencies"},{"id":"provide-credentials","heading":"Provide credentials"},{"id":"initialize-rebilly-js-sdk","heading":"Initialize Rebilly JS SDK"},{"id":"define-route-for-post-requests","heading":"Define route for POST requests"},{"id":"provide-customer-id","heading":"Provide a customer ID"},{"id":"provide-currency","heading":"Provide currency"},{"id":"install-the-library","heading":"Install the library"},{"id":"add-custom-styling","heading":"Add custom styling (optional)"},{"id":"add-a-container-element","heading":"Add a container element"},{"id":"render-the-withdraw-form","heading":"Render the withdrawal form"},{"id":"handle-withdrawal-completed","heading":"Handle withdrawal form completion (optional)"},{"id":"handle-complete-action","heading":"Handle withdrawal result action (optional)"},{"id":"run-the-example","heading":"Run the example"}],"inputs":{},"toggles":{}},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"integrate-a-withdrawal-form","__idx":0},"children":["Integrate a withdrawal form ",{"$$mdtype":"Tag","name":"Badge","attributes":{"type":"experimental"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide describes how to integrate and embed a customizable, white-label withdrawal form into your website using the Cashier JavaScript library, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.npmjs.com/package/rebilly-js-sdk"},"children":["Rebilly JS SDK"]},", and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://expressjs.com/en/starter/installing.html"},"children":["Express JS"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this guide, you configure the withdrawal form to retrieve a cashier token from a backend endpoint and use that token to mount the Cashier JavaScript library in the frontend."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the withdrawal form to allow customers to request withdrawals from their account balance."," ","When a customer submits a withdrawal, a payout request is created."," ","A ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/payout-requests"},"children":["payout request"]}," is a customer request to withdraw funds."," ","In the withdrawal form, customers select a withdrawal amount, choose or add a payment instrument, and confirm the withdrawal."," ","Payouts must be approved and allocated before the approved amount is transferred to the payment instrument."," ","For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/payout-requests"},"children":["Payout requests"]},"."]},{"$$mdtype":"Tag","name":"DownloadButton","attributes":{"text":"Download full app"},"children":[]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To complete this guide, you must have a website ID, an organization ID, a secret API key, and a customer ID."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You must also have a payment gateway configured in your Rebilly account to process payout requests."," ","For sandbox testing, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TestProcessor"]}," gateway is pre-configured."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your website uses a Content Security Policy (CSP), configure it before you embed the withdrawal form."," ","For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/set-up-environment#configure-content-security-policy"},"children":["Configure content security policy"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you already have your IDs and API keys, continue to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#step-1-set-up-the-server"},"children":["Step 1: Set up the server"]},"."," ","If you do not, create a customer and get your IDs and API key in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/set-up-environment"},"children":["Set up your environment"]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To process payout requests, configure at least one gateway for payouts and configure payout methods to display in the form."," ","For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/settings/set-up-a-gateway#optionally,-configure-how-the-gateway-manages-payout-requests"},"children":["Configure a gateway to manage payout requests"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/settings/payout-method-configuration#configure-methods-to-display-in-a-payout-form"},"children":["Configure payout methods displayed in payout forms"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-set-up-the-server","__idx":1},"children":["Step 1: Set up the server"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section describes how to set up your server-side code."," ","This guide uses an Express node app to authenticate the client."]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"install-and-initialize-dependencies","heading":"Install and initialize dependencies"},"children":[{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Install the required dependencies in your project directory:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npm install express rebilly-js-sdk --save\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Initialize Express and the Rebilly SDK."]}]}]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"provide-credentials","heading":"Provide credentials"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provide your secret key, website ID, and organization ID."," ","For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/integrate-a-withdraw-form#prerequisites"},"children":["Prerequisites"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store your secret key in a secrets manager, not in your code."]}]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"initialize-rebilly-js-sdk","heading":"Initialize Rebilly JS SDK"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set up the Rebilly JS SDK and provide your secret API key."," ","Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sandbox"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," to test in the sandbox environment."]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"define-route-for-post-requests","heading":"Define route for POST requests"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define a route for handling HTTP POST requests to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/create-cashier"]}," endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/catalog/all/cashiers/postcashier"},"children":["Create a cashier API operation"]}," and this ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://expressjs.com/en/starter/hello-world.html"},"children":["Express example"]},"."]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"provide-customer-id","heading":"Provide a customer ID"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provide the ID of a customer."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/integrate-a-withdraw-form#prerequisites"},"children":["Prerequisites"]},"."]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"provide-currency","heading":"Provide currency"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provide the currency of the transaction."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-set-up-the-form","__idx":2},"children":["Step 2: Set up the form"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section describes the basic setup for mounting the withdrawal form."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For this guide, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.html"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["withdraw.js"]}," must be placed in a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["public"]}," directory in the root of your project."]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"install-the-library","heading":"Install the library"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Include the Cashier JavaScript library using a CDN:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"HTML","header":{"controls":{"copy":{}}},"source":"https://cdn.rebilly.com/cashier/@latest/main.js\n","lang":"HTML"},"children":[]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"add-custom-styling","heading":"Add custom styling (optional)"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Optionally, use Cashier library CSS variables or classes to customize the appearance of the withdrawal form."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/customize-rebilly-cashier/"},"children":["Customize"]},"."]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"add-a-container-element","heading":"Add a container element"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define an empty container element to hold the withdrawal form."," ","This element is provided to the Cashier library ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["renderWithdraw"]}," method to mount the withdrawal form."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Any HTML element may be used to contain the withdrawal form."]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"render-the-withdraw-form","heading":"Render the withdrawal form"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a request to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/create-cashier"]}," server endpoint you created in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#step-1-set-up-the-server"},"children":["Step 1: Set up a server"]},", and use the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cashierToken"]}," to mount the withdrawal form on the page."]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"handle-withdrawal-completed","heading":"Handle withdrawal form completion (optional)"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To handle withdrawal form completion, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RebillyCashier.on()"]}," to listen for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["withdrawal-completed"]}," event."]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"handle-complete-action","heading":"Handle withdrawal result action (optional)"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To run custom logic when the customer presses ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue"]}," on the result screen of the withdrawal or reverse withdrawal form, instead of redirecting to a URL, pass a completeAction callback to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RebillyCashier.renderWithdraw()"]},"."," ","The callback receives a type value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["withdrawal"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reverse-withdrawal"]},"."," ","The withdrawal form displays the reverse withdrawal option when the customer has pending payout requests."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-view-the-withdrawal-form","__idx":3},"children":["Step 3: View the withdrawal form"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section describes how to view the withdrawal form in a web browser."]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"run-the-example","heading":"Run the example"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["server.js"]},". When the server is running, open a browser and visit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http://localhost:8080"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/integrate-a-withdraw-form#prerequisites"},"children":["Prerequisites"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"node server.js\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-topics","__idx":4},"children":["Related topics"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/integrate-a-reverse-withdraw-form/"},"children":["Integrate a reverse withdrawal form"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/integrate-a-deposit-form/"},"children":["Integrate a deposit form"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/customize-rebilly-cashier/"},"children":["Customize"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/reference-rebilly-cashier/"},"children":["Reference"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/payout-requests"},"children":["Payout requests"]}]}]}]}]},"headings":[{"value":"Integrate a withdrawal form","id":"integrate-a-withdrawal-form","depth":1},{"value":"Step 1: Set up the server","id":"step-1-set-up-the-server","depth":2},{"value":"Step 2: Set up the form","id":"step-2-set-up-the-form","depth":2},{"value":"Step 3: View the withdrawal form","id":"step-3-view-the-withdrawal-form","depth":2},{"value":"Related topics","id":"related-topics","depth":2}],"frontmatter":{"seo":{"title":"Integrate a withdrawal form","description":"Learn how to integrate an embedded withdrawal form."},"markdown":{"toc":{"hide":true}},"footer":{"hide":true}},"lastModified":"2026-07-09T14:42:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/dev-docs/integrate-a-withdraw-form","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}