Cashier

{"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 cashier form","description":"Learn how to integrate an embedded cashier form that contains both withdrawal and deposit tabs.","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 cashier form that uses the Cashier library."," ","To complete the payment flow, enter any 3-digits for the CVC number. For more test cards, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/tutorials/test-payment-cards"},"children":["Test cards, IBANs, and ACH details"]}]},{"$$mdtype":"Tag","name":"iframe","attributes":{"src":"/examples/cashier/payout/payout.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-cashier-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);"," }"," }","});"]},"","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-cashier-form/public/index.html","content":["",""," "," Cashier",{"start":4,"condition":{"steps":["install-the-library"]},"children":[" "]}," "," "," ",{"start":10,"condition":{"steps":["add-a-container-element"]},"children":["

"]}," ","",""],"metadata":{"steps":["install-the-library","add-a-container-element"]},"basename":"index.html","language":"html"}],"downloadAssociatedFiles":[]},{"files":[{"path":"docs/dev-docs/_code-samples/integrate-a-cashier-form/public/cashier.js","content":[{"start":0,"condition":{"steps":["render-the-cashier-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(\"#cashier\");"," const cashierToken = data.cashierToken;",""," if (window.RebillyCashier) {"," window.RebillyCashier.render({"," mountElement,"," cashierToken,"," });"," } else {"," console.error(\"RebillyCashier library not loaded\");"," }","}","","setup();"]},""],"metadata":{"steps":["render-the-cashier-form"]},"basename":"cashier.js","language":"javascript"}],"downloadAssociatedFiles":[]},{"downloadAssociatedFiles":[{"path":"docs/dev-docs/_code-samples/integrate-a-cashier-form/package.json","content":["{"," \"name\": \"rebilly-cashier-form-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-cashier-form/README.md","content":["# Integrate a cashier form","","This example describes how to integrate and embed a customizable, white-label cashier form that contains both withdrawal and deposit tabs 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 cashier form](https://www.rebilly.com/docs/dev-docs/integrate-a-cashier-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-a-container-element","heading":"Add a container element"},{"id":"render-the-cashier-form","heading":"Render the cashier form"},{"id":"run-the-example","heading":"Run the example"}],"inputs":{},"toggles":{}},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"integrate-a-cashier-form","__idx":0},"children":["Integrate a cashier 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 cashier form that contains both withdrawal and deposit tabs 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 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 cashier form to allow customers to withdraw funds and to make deposits."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the form, customers must select or add a preferred payment instrument on which to receive the withdrawal or to make the deposit."," ","Payout requests must be approved and allocated before the approved amount is transferred to the customer's payment instrument."," ","Deposits are immediately credited to the customer's account."," ","For more information on deposit request statuses, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/dev-docs/deposit-requests"},"children":["Deposit 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."," ","For sandbox testing, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TestProcessor"]}," gateway is pre-configured."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To process payout requests in the withdrawal tab, 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-withdrawal-forms"},"children":["Configure methods to display in withdrawal forms"]},"."]},{"$$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 cashier 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 display deposit amounts in the deposit tab of the cashier form, create a deposit amount strategy."," ","If not specified, default amounts of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["10"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["20"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["30"]}," are displayed, with an option to enter a custom amount."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/catalog/all/deposits/postdepositstrategy"},"children":["Create a deposit amount strategy API operation"]},", or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/settings/deposit-strategies#create-a-deposit-amount-strategy"},"children":["Create a deposit amount strategy"]}," in the Rebilly UI."]}]},{"$$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-cashier-form#prerequisites"},"children":["Prerequisites"]},"."]}]},{"$$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-cashier-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 cashier 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":["cashier.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-a-container-element","heading":"Add a container element"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define an empty container element to hold the cashier form."," ","This element is provided to the Cashier library ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["render"]}," method to mount the cashier form."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Any HTML element may be used to contain the cashier form."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-configure-the-library","__idx":3},"children":["Step 3: Configure the library"]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"render-the-cashier-form","heading":"Render the cashier 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 cashier form on the page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["render"]}," method displays the full cashier interface, which includes both deposit and withdrawal tabs."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-view-the-cashier-form","__idx":4},"children":["Step 4: View the cashier form"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section describes how to view the cashier 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-cashier-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":5},"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-withdrawal-form/"},"children":["Integrate a withdrawal 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/data-tables/manage-payout-requests"},"children":["Payout requests"]}]}]}]}]},"headings":[{"value":"Integrate a cashier form","id":"integrate-a-cashier-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: Configure the library","id":"step-3-configure-the-library","depth":2},{"value":"Step 4: View the cashier form","id":"step-4-view-the-cashier-form","depth":2},{"value":"Related topics","id":"related-topics","depth":2}],"frontmatter":{"seo":{"title":"Integrate a cashier form","description":"Learn how to integrate an embedded cashier form that contains both withdrawal and deposit tabs."},"redirects":{"/docs/dev-docs/rebilly-instruments-payout-integration/":{},"/docs/dev-docs/integrate-a-payout-form/":{}},"markdown":{"toc":{"hide":true}},"footer":{"hide":true}},"lastModified":"2026-07-21T15:06:02.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/dev-docs/integrate-a-cashier-form","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}