Overview

Synctera offers in-store cash deposits through InComm’s VanillaDirect solution. With this solution, customers generate 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 barcode
Displaying barcode and payment slip
Presenting transaction details/receipt
Providing access to retailer map

The requirements an implementation details are described below.

Pre-Requisites

Pre-requisites 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. 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.

Endpoint

POST /v1/cash/barcodes

Example Request

curl \
-X POST \ 
$baseurl/v1/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": "14_23",
    "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.

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

Endpoint

PATCH /v1/cash/barcodes/{$barcode_id}

Example Request

curl \
-X PATCH \ 
$baseurl/v1/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 the transaction details.

Barcode specific payment data can be found in the transactions user data and can be used to display the required details on the receipt.

User Data:

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

Also, your customer can always get their E-receipt by providing the appropriate barcode number at vanilladirect.com/pay/ereceipt.

📘
Sample UX Flows
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.

🚧
In-Store Cash Deposit Fees
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.

👍
Successful POS Interaction
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
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

Obtain the URL for the retailer map.

Endpoint

GET /v1/cash/barcodes/retailer_map_url

You can customize the map’s center using optional query parameters:

GET /v1/cash/barcodes/retailer_map_url?lat=37.773972&lng=-122.43129

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.

📘
Sandbox Env
Please reach out to your Synctera Implementation Representative to get you set up in Sandbox

Retrieve Test Stores

Get a list of stores available for testing.

Endpoint

GET /v1/cash/transaction_simulations/barcodes/stores

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/v1/cash/transaction_simulations/barcodes/stores?lat=40.7128&lng=-74.0060&radius=15&limit=1 \ 
-H "Authorization: Bearer $apiKey" \

Example Response

[
  {
    "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 transaction simulation 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

Endpoint

POST /v1/cash/transaction_simulations/barcodes/deposit

Example: Simulate a Test Payment

curl \
-X POST \ 
$baseurl/v1/cash/transaction_simulations/barcodes/deposit \ 
-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

In-Store Cash Deposits (Alpha)

Overview

Barcode UX build

Pre-Requisites

Managing Barcodes

Create Barcode

Endpoint

Example Request

Example Response

Block Barcode

🚧
Blocked Barcode

Endpoint

Example Request

Example Response

Displaying Barcodes

Printable Barcode Requirements

Displaying on Smartphone

Payment Slips

📘
Sample UX Flows

In-Store Cash Deposit Fees

🚧
In-Store Cash Deposit Fees

Point of Sale Interaction

👍
Successful POS Interaction

📘
Multiple Test Payments

Available Retail Locations

Embedding the Retailer Map

Retrieving the Retailer Map URL

Endpoint

Sandbox Testing

📘
Sandbox Env

Retrieve Test Stores

Endpoint

Example Request

Example Response

Simulating Payments

Parameters

Endpoint

Example: Simulate a Test Payment

Reviewing Results

Overview

Barcode UX build

Pre-Requisites

Managing Barcodes

Create Barcode

Endpoint

Example Request

Example Response

Block Barcode

🚧Blocked Barcode

Endpoint

Example Request

Example Response

Displaying Barcodes

Printable Barcode Requirements

Displaying on Smartphone

Payment Slips

📘Sample UX Flows

In-Store Cash Deposit Fees

🚧In-Store Cash Deposit Fees

Point of Sale Interaction

👍Successful POS Interaction

📘Multiple Test Payments

Available Retail Locations

Embedding the Retailer Map

Retrieving the Retailer Map URL

Endpoint

Sandbox Testing

📘Sandbox Env

Retrieve Test Stores

Endpoint

Example Request

Example Response

Simulating Payments

Parameters

Endpoint

Example: Simulate a Test Payment

Reviewing Results

🚧
Blocked Barcode

📘
Sample UX Flows

🚧
In-Store Cash Deposit Fees

👍
Successful POS Interaction

📘
Multiple Test Payments

📘
Sandbox Env