Documentation
Start typing to search…

Cash On-Ramp Overview

Overview

The Order Template system powers Coinme's cash on-ramp functionality. When a user wants to purchase crypto with cash at a retail location (e.g., via Green Dot), an Order Template is created that generates a barcode. The user takes this barcode to a participating retail location, makes their cash payment, and the system initiates the crypto purchase.

Core Concepts

What is an Order Template?

An Order Template is a pre-configured instruction set that contains all the data needed to execute a cash-based crypto purchase. It includes user information, transaction details, and generates a scannable barcode for use at retail locations.


Order Template Lifecycle

Happy Path: CREATED → CONSUMED → COMPLETED

Alternative Paths:

  • CREATED → EXPIRED (barcode not used in time)
  • CREATED → DELETED (removed by system or user)
  • CONSUMED → REJECTED (rare failure during transaction initiation)

Order Template Statuses

Active States

These count toward the provider's active template limit.

CREATED Order template has been created and is active. Barcode is ready for use.

UPDATED Order template has been modified. Note: Not applicable for Green Dot—see "Sealed" below.

Transitional State

CONSUMED Barcode has been scanned and payment received. Transaction is being initiated. This is a very short-lived state lasting only milliseconds.

Final States

These no longer count toward limits and cannot be modified.

1. COMPLETED Transaction successfully initiated. This is the expected successful outcome.

2. REJECTED Transaction initiation failed after payment was received. Extremely rare edge case—e.g., system outage during initiation.

3. EXPIRED Order template was not used within the allowed time window.

4. DELETED Order template was removed, either manually or by the system due to active template limits.

The "Sealed" Parameter

Some payment providers (including Green Dot) do not allow modifications to an order template after creation.

{
  "orderTemplateId": "abc123",
  "sealed": true,
  ...
}
  • sealed: true — The order template cannot be updated after creation. You will never see an UPDATED status.
  • sealed: false — The order template can be modified via the update endpoint.

For Green Dot: All order templates are sealed (sealed: true).

Creating Order Templates

Method 1: Standard Creation

Create a new order template by providing all required user and transaction data:

POST /order-templates

Request body includes user details, amount, asset, and payment provider information.

Method 2: Refresh (Create from Existing)

Create a new order template by referencing an existing one. This copies all input data from the referenced template, saving you from re-entering the same information.

POST /order-templates/refresh
{
  "orderTemplateId": "existing-template-id"
}

Key points about refresh:

  • This is not a "resume" function—it creates a brand new order template.
  • The new template gets a new ID and a fresh barcode.
  • You can refresh from an order template in any status (including final states like COMPLETED or EXPIRED).
  • The system behaves exactly as if you created a new template with all the data manually entered.

Use case: A user's barcode expired, but they still want to make the same purchase. Instead of collecting all their information again, call the refresh endpoint with the expired template's ID.

Active Template Limits

Each payment provider has a maximum number of active order templates allowed per user at any given time.

Green Dot: Maximum 1 active template

What happens when the limit is reached?

When you create a new order template (via either method) and the user already has the maximum number of active templates:

  1. The system identifies the oldest active order template.
  2. That template is automatically deleted.
  3. The new template is created.

Example (Green Dot):

  • User has an active order template (status: CREATED).
  • User requests a new order template via refresh.
  • The old template is deleted → status changes to DELETED.
  • New template is created → status is CREATED.

Field Name Clarification

⚠️

API Note: Some endpoints may return transactionSystemRef instead of orderTemplateId. These refer to the same value. transactionSystemRef is an internal system name.

When refreshing, the response includes:

{
  "orderTemplateId": "new-template-id",
  "refreshedFromOrderTemplateId": "original-template-id"
}

The CONSUMED State (Deep Dive)

The CONSUMED state is a brief transitional phase that occurs after a barcode is scanned:

  1. User scans barcode at retail location.
  2. Green Dot calls Coinme's API to confirm the payment.
  3. Coinme validates the order template exists and is active.
  4. Status → CONSUMED — Payment confirmed, transaction initiation begins.
  5. Transaction initiates (all validations already passed at template creation).
  6. Status → COMPLETED — Normal successful outcome.

Why CONSUMED exists

At this point, all checks and validations have already been performed. The system simply needs to initiate the transaction flow, which should not fail. However, in extremely rare edge cases (e.g., partial system outage), initiation could fail:

  • Success: CONSUMED → COMPLETED
  • Failure (rare): CONSUMED → REJECTED

Can you refresh from CONSUMED?

Technically yes, but practically no. The CONSUMED state lasts only milliseconds. You would need to call the refresh endpoint at the exact moment between barcode scan and transaction completion—an essentially impossible timing window.

Quick Reference: Refresh Behavior by Status

From CREATED: Can refresh. Original is deleted (due to limit), new template created.

From UPDATED: Can refresh. Original is deleted (due to limit), new template created.

From CONSUMED: Technically possible, but requires impossibly precise timing (milliseconds window).

From COMPLETED: Can refresh. New template created, original remains unchanged.

From REJECTED: Can refresh. New template created, original remains unchanged.

From EXPIRED: Can refresh. New template created, original remains unchanged.

From DELETED: Can refresh. New template created, original remains unchanged.

Common Scenarios

Scenario 1: User's barcode expired

Original template: EXPIRED
Action: Call refresh with original template ID
Result: New template created with fresh barcode, same transaction details

Scenario 2: User wants to change the amount

Original template: CREATED (sealed)
Action: Cannot update (sealed). Create new template with new amount.
Result: Original deleted (limit reached), new template created

Scenario 3: User successfully completes purchase, wants to buy again

Original template: COMPLETED
Action: Call refresh with original template ID
Result: New template created, ready for next purchase

Summary

Order Template: Contains all data for a cash crypto purchase; generates a barcode.

Refresh: Creates a NEW template from an existing one (not a resume).

Sealed: Green Dot templates cannot be updated after creation.

Active Limit: Green Dot allows 1 active template; oldest is auto-deleted when limit reached.

CONSUMED: Brief state between payment receipt and transaction initiation.

Updated 23 days ago