> ## Documentation Index > Fetch the complete documentation index at: https://docs.synctera.com/llms.txt > Use this file to discover all available pages before exploring further. # In-Store Cash Deposits > Enable customers to deposit physical cash at retail locations using barcodes through InComm's VanillaDirect solution. # Overview Synctera offers in-store cash deposits through InComm's VanillaDirect solution. With this solution, customers generate a barcode on demand, and present it to a cashier at an InComm-supported retailer (e.g., 7-Eleven, Walgreens, CVS), which allows them to deposit physical cash directly into their account. This method provides an accessible alternative when ATMs or traditional banking options are not available. ## Barcode UX build As you own the user experience, you are responsible for building the barcode UX in your app, which includes: * Generating a barcode * Displaying the barcode and payment slip with the required information * Presenting the transaction details/receipt * Providing access to the retailer map The UX flow follows specific requirements, which are described below along with implementation details. ## Prerequisites Prerequisites for creating barcodes: * A [Customer](/v2/docs/create-a-personal-customer) has been created * An [Account](/v2/docs/create-accounts-guide) for the customer has been created # Managing Barcodes ## Create Barcode Barcodes should be generated through the customer's app shortly before they intend to make a deposit using the [POST /v2/cash/barcodes](/v2/reference/createbarcode) endpoint. Each barcode is single-use, is valid for **15 minutes** and must be used at a participating retail location within a **15-mile radius** of the location where it was generated. ### Example Request ```sh Shell theme={"system"} curl \ -X POST \ $baseurl/v2/cash/barcodes \ -H "Authorization: Bearer $apiKey" \ --json '{ "type": "CASH_DEPOSIT", "account_id": "019833f2-794b-7b6f-9bf1-ddbf935a74dd", "customer_id": "019833f2-972c-7b0e-ab52-1414133ed001", "customer_latitude": 37.7749, "customer_longitude": -122.4194, "tenant": "gxpwkp_eyzdoy", "metadata": { "test": "test_value", "test2": "test_value2" } }' ``` ### Example Response ```json JSON theme={"system"} { "account_id": "019833f2-794b-7b6f-9bf1-ddbf935a74dd", "barcode_number": "799366476346399810001917770198", "creation_time": "2025-06-17T23:12:28.572154Z", "currency": "USD", "customer_id": "019833f2-972c-7b0e-ab52-1414133ed001", "customer_latitude": 37.7749, "customer_longitude": -122.4194, "id": "019833f4-a7b3-7107-be10-a89c1dcdf510", "last_updated_time": "2025-06-17T23:12:28.572154Z", "max_amount": 900, "metadata": { "test": "test_value", "test2": "test_value2" }, "min_amount": 10, "status": "AVAILABLE", "tenant": "gxpwkp_eyzdoy", "timestamp_valid_to": "2025-06-17T23:22:28.044478Z", "type": "CASH_DEPOSIT" } ``` ## Block Barcode If a barcode has been generated but needs to be **blocked** to prevent further use, you can update its status to `BLOCKED` using the [PATCH /v2/cash/barcodes/\{barcode\_id}](/v2/reference/updatebarcode) endpoint. Once a barcode is blocked, it cannot be reactivated. A new barcode must be generated to enable subsequent deposits. ### Example Request ```sh Shell theme={"system"} curl \ -X PATCH \ $baseurl/v2/cash/barcodes/019833f4-a7b3-7107-be10-a89c1dcdf510 \ -H "Authorization: Bearer $apiKey" \ --json '{ "status": "BLOCKED" }' ``` ### Example Response ```json JSON theme={"system"} { "account_id": "019833f2-794b-7b6f-9bf1-ddbf935a74dd", "barcode_number": "799366476346399810001917770198", "creation_time": "2025-06-17T23:12:28.572154Z", "currency": "USD", "customer_id": "019833f2-972c-7b0e-ab52-1414133ed001", "customer_latitude": 37.7749, "customer_longitude": -122.4194, "id": "019833f4-a7b3-7107-be10-a89c1dcdf510", "last_updated_time": "2025-06-17T23:12:28.572154Z", "max_amount": 900, "metadata": { "test": "test_value", "test2": "test_value2" }, "min_amount": 10, "status": "BLOCKED", "tenant": "gxpwkp_eyzdoy", "timestamp_valid_to": "2025-06-17T23:22:28.044478Z", "type": "CASH_DEPOSIT" } ``` ## Displaying Barcodes Barcodes should be generated using the **Code 128C** format to ensure compatibility with retailer point-of-sale (POS) systems. Adhering to the specifications below will help ensure reliable scanning and processing. ### Printable Barcode Requirements * **Barcode format**: Must use **Code 128C** * **Color**: Black * **Minimum width**: 2.25 inches * **Minimum height**: 5/8 inch * **Quiet zone**: At least 1/8 inch of white space above and below the barcode * **Module size**: Minimum of 13 mils (for 300 DPI resolution); the module is the smallest unit width of a bar * **Human-readable text**: The barcode value must be printed below the barcode * **File format**: It is strongly recommended that barcodes be generated in **vector format** (e.g., SVG or PDF) to maintain scan quality across different devices and resolutions ### Displaying on Smartphone Customers may present digital barcodes on their smartphones at the point of sale. For optimal scan performance, users should rotate their device to **landscape orientation**, increasing the barcode’s width and improving scanner readability. The requirements for digital barcodes are the same as for printed versions. Specifically: * The barcode must follow the **Code 128C** format and all associated size and spacing requirements * A **human-readable number** must be displayed below the barcode to allow manual entry by the cashier if scanning fails ## Payment Stack Screen The option to Add/Deposit Cash must be made available to the customer in the app. The recommended best practice is to add the Cash Payment option at the top of the payment stack/options. ## Payment Slips Payment slips should be generated and provided to your customers, containing both the **barcode image** and the **human-readable barcode number**. While the layout of the slip can follow your brand’s design and formatting standards, it must include the following required elements: 1. **Payment Range** Display the minimum and maximum deposit amounts allowed for the barcode. 2. **Barcode Expiration Notice** Clearly state the time at which the barcode expires. 3. **VanillaDirect Ice Cream Cone** Include the official InComm VanillaDirect branding icon. 4. **Barcode** Display a scannable **Code 128C** barcode, along with the **human-readable number** printed below. 5. **Cash Deposit Fee** If applicable, display any fees configured for the cash deposit. 6. **Terms & Conditions** Include a reference to the **VDBS Terms of Service**. 7. **Consumer Step-by-Step** Provide clear, numbered instructions that explain how to complete the cash deposit at a participating retailer. 8. **Store Locator** Include a link or embedded map to help customers find eligible retail locations near them where the barcode can be used. The recommendation is to enable both map view and list view. As this feature requires the phone's **location services** to be turned on, screens for notifying the customer about location services being disabled and for prompting the user to allow location services are also required. 9. **Receipt** Provide the ability for your customer to display transaction details after completing a deposit. The transaction's [user\_data](/v2/docs/transactions-guide#user_data) field contains barcode-specific payment details, including barcode information and merchant location data, which you can use to build a comprehensive receipt: ```json JSON theme={"system"} { "barcode": { "barcode_number": "839650172948537162049873516238", "biller_id": "X8v2QmPzYdR5aLtKBwN1oCgHUEsJfT63", "pos_timestamp": "2014-03-17T11:13:36Z", "customer_longitude": -73.935242, "customer_latitude": 40.73061, "external_device_id": "738920164537", "metadata": { "product_id": "123456", "order_id": "NB-3406542", "comment": "any text" } }, "merchant": { "name": "7 Eleven", "retailer_reference_number": "98765", "address1": "address1", "address2": "", "city": "City", "county": "County", "state": "GA", "zip_code": "11223-3445", "country": "USA", "phone_numbers": [ "123456789" ], "terminal_id": "25476001", "lat": 33.7380073, "lng": -84.3936426, "store_id": "123345", "store_external_id": "25476" } } ``` Additionally, customers can retrieve their E-receipt directly from InComm by providing the barcode number at [pay.vanilladirect.com/ereceipt](https://pay.vanilladirect.com/ereceipt). Please reach out to your Synctera Implementation Representative for detailed UX/UI specifications, and for sample UX flows. 10. **Optional screens** * Barcode expiration screen: To enable customer to generate a new barcode * Monthly/daily deposit limit screens: To notify customer about limit being reched and when it will be reset # In-Store Cash Deposit Fees Cash deposit fees can be automatically deducted from the customer’s account at the time the deposit is processed. To enable this, you must configure a **cash deposit fee** with a specified amount in your system. If a transaction is reversed, the associated fee will also be automatically reversed. Our system supports only **one active cash deposit fee** at a time. It is strongly recommended that you configure **a single fee** to apply to all barcode-based cash deposit transactions. If multiple fees are configured, the **most recently created** fee will be prioritized and applied. For setup instructions, refer to the [**Fees**](/v2/docs/fees-and-rewards) section in the developer guide. # Point of Sale Interaction When a customer presents a barcode to the cashier, a **test transaction** is initiated that results in an **authorization** on the customer’s account. If the authorization succeeds, the payment is applied and posted to the customer’s account. Once the **payment application is successfully processed**, the cashier will accept the cash from the customer. At this point, the transaction is considered final and cannot be refunded or reversed. In the event of a **network timeout** or other communication failure during the transaction, the cashier will **not accept the cash**, and a **void payment** will be processed automatically. This ensures that no funds are posted to the customer's account and that the authorization is correctly canceled. Multiple test payments can be performed and are valid for authorization. However, only the **apply payment** finalizes the deposit, prompting the cashier to accept the cash and post the funds to the customer's account. ## Available Retail Locations To help your customers find nearby participating retailers where they can make cash deposits, you can either: * **Embed** a retailer map directly within your app using an ` ``` ### Retrieving the Retailer Map URL To get the URL for the retailer map, use the [GET /v2/cash/barcodes/retailer\_map\_url](/v2/reference/getretailermapurl) endpoint. You can customize the map's center using optional query parameters: * `lat`: Latitude of the map center * `lng`: Longitude of the map center # Sandbox Testing To test barcode-based cash deposits in the sandbox environment, you can use the **transaction simulation endpoints** provided. Please reach out to your Synctera Implementation Representative to get you set up in Sandbox. ## Retrieve Test Stores To get a list of stores available for testing, use the [GET /v2/cash/transaction\_simulations/barcodes/stores](/v2/reference/simulatebarcodesstores) endpoint. You can customize the response using query parameters to filter stores by location and radius. For example, retrieving stores outside the barcode's valid radius can help simulate invalid merchant locations. Supported query parameters: * `lat` *(required)*: Latitude coordinate to center the search * `lng` *(required)*: Longitude coordinate to center the search * `radius` *(optional)*: Search radius in miles * `limit` *(optional)*: Maximum number of stores to return ### Example Request ```sh Shell theme={"system"} curl \ -X GET \ $baseurl/v2/cash/transaction_simulations/barcodes/stores?lat=40.7128&lng=-74.0060&radius=15&limit=1 \ -H "Authorization: Bearer $apiKey" ``` ### Example Response ```json JSON theme={"system"} { "stores": [ { "address": { "address1": "1192 MYRTLE AVE", "city": "BROOKLYN", "country": "USA", "county": "KINGS", "state": "NY", "zip_code": "11221-2613" }, "business_name": "Dollar General", "coordinates": { "latitude": 40.697266, "longitude": -73.93116 }, "distance": 4.07, "id": "5897e7c84f3680b7934697656a12aa05" } ] } ``` ## Simulating Payments You can simulate test, apply, and void payments using the [POST /v2/cash/transaction\_simulations/barcodes/deposits](/v2/reference/simulatebarcodesdeposits) endpoint. Simulations must follow the same logical flow as real-world [point-of-sale interactions](/v2/docs/in-store-cash-deposits#point-of-sale-interaction). ### Parameters * **type** *(required)*: The payment action to simulate. Valid values are: * `TEST` — Authorizes the payment without applying it * `APPLY` — Applies the payment and posts funds to the account * **status** *(required)*: The status of the payment simulation. Valid values depend on the `type`: * For `TEST` type: * `PAID` — Authorize Payment * For `APPLY` type: * `PAID` — Apply Payment * `VOID` — Void Payment ### Example: Simulate a Test Payment ```sh Shell theme={"system"} curl \ -X POST \ $baseurl/v2/cash/transaction_simulations/barcodes/deposits \ -H "Authorization: Bearer $apiKey" \ --json '{ "amount": 100.00, "barcode_id": "01983364-ebd5-717b-9aaf-7cf91ced9ed8", "type": "TEST", "status": "PAID", "store_id": "5897e7c84f3680b7934697656a12aa05" }' ``` ### Reviewing Results After simulating a payment, review the customer account associated with the barcode to: * Verify the transaction outcome * Confirm correct fee application