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
Presenting the transaction details/receipt
Providing access to the retailer map

The requirements and implementation details are described below.

Prerequisites

Prerequisites for creating barcodes:

A Customer has been created
An Account 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 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

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

{
  "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} endpoint.

Once a barcode is blocked, it cannot be reactivated. A new barcode must be generated to enable subsequent deposits.

Example Request

curl \
  -X PATCH \
  $baseurl/v2/cash/barcodes/019833f4-a7b3-7107-be10-a89c1dcdf510 \
  -H "Authorization: Bearer $apiKey" \
  --json '{
    "status": "BLOCKED"
  }'

Example Response

{
  "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 inches (recommended: 2.7 inches)
Minimum height: 3/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 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:

Payment Range Display the minimum and maximum deposit amounts allowed for the barcode.
Barcode Expiration Notice Clearly state the time at which the barcode expires.
VanillaDirect Ice Cream Cone Include the official InComm VanillaDirect branding icon.
Barcode Display a scannable Code 128C barcode, along with the human-readable number printed below.
Cash Deposit Fee If applicable, display any fees configured for the cash deposit.
Terms & Conditions Include a reference to the VDBS Terms of Service.
Consumer Step-by-Step Provide clear, numbered instructions that explain how to complete the cash deposit at a participating retailer.
Store Locator Include a link or embedded map to help customers find eligible retail locations near them where the barcode can be used.
Receipt Provide the ability for your customer to display transaction details after completing a deposit. The transaction’s user_data field contains barcode-specific payment details, including barcode information and merchant location data, which you can use to build a comprehensive receipt:

{
  "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.

Please reach out to your Synctera Implementation Representative for sample UX flows.

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 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 <iframe>, or
Redirect customers to the retailer map URL in an external browser.

Embedding the Retailer Map

You can display the map using an <iframe> with the provided URL. The iframe supports geolocation to center the map based on the user’s location.

<iframe src="$retailerMapUrl" allow="geolocation">
  <p>Your browser does not support iframes.</p>
</iframe>

Retrieving the Retailer Map URL

To get the URL for the retailer map, use the GET /v2/cash/barcodes/retailer_map_url 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 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

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

{
  "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 endpoint. Simulations must follow the same logical flow as real-world point-of-sale interactions.

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

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

Overview

Products

Onboard a Personal Customer

Onboard a Business Customer

Create Accounts

Link External Accounts

Link External Cards

Issue Cards

Move Money

Get Transactions

Dispute Transactions

Platform Tools

Validate a Value Proposition

​Overview

​Barcode UX build

​Prerequisites

​Managing Barcodes

​Create Barcode

​Example Request

​Example Response

​Block Barcode

​Example Request

​Example Response

​Displaying Barcodes

​Printable Barcode Requirements

​Displaying on Smartphone

​Payment Slips

​In-Store Cash Deposit Fees

​Point of Sale Interaction

​Available Retail Locations

​Embedding the Retailer Map

​Retrieving the Retailer Map URL

​Sandbox Testing

​Retrieve Test Stores

​Example Request

​Example Response

​Simulating Payments

​Parameters

​Example: Simulate a Test Payment

​Reviewing Results

Overview

Barcode UX build

Prerequisites

Managing Barcodes

Create Barcode

Example Request

Example Response

Block Barcode

Example Request

Example Response

Displaying Barcodes

Printable Barcode Requirements

Displaying on Smartphone

Payment Slips

In-Store Cash Deposit Fees

Point of Sale Interaction

Available Retail Locations

Embedding the Retailer Map

Retrieving the Retailer Map URL

Sandbox Testing

Retrieve Test Stores

Example Request

Example Response

Simulating Payments

Parameters

Example: Simulate a Test Payment

Reviewing Results