Skip to main content
POST
Create transaction

Authorizations

Authorization
string
header
required

API key authentication. Include your API key as a Bearer token.

Example: Bearer sk_prod_xxxxxx

Get your API key from the Stell Dashboard.

Body

application/json

Data required to record a new transaction.

passId
string
required

ID of the pass to record transaction for

type
enum<string>
required

What happened to the pass. Use channel for in-store vs online and tapMode for single- vs double-tap; the legacy ONLINE / PASS_AND_PAYMENT / PASS_ONLY / PAYMENT_ONLY values are rejected.

Available options:
PURCHASE,
REDEMPTION,
POINTS_ADJUSTMENT,
SCAN_ONLY,
CHECK_IN,
CHECK_OUT,
UNKNOWN
tapMode
enum<string>

Whether pass and payment were captured in one terminal tap (SINGLE_TAP), separate taps (DOUBLE_TAP), or without a terminal (NONE)

Available options:
SINGLE_TAP,
DOUBLE_TAP,
NONE
pointsSpent
integer

Loyalty points redeemed in this transaction

Required range: x >= 0
channel
enum<string>

Where the customer was: IN_STORE or ONLINE

Available options:
IN_STORE,
ONLINE
instrument
enum<string>

How the pass was presented (Apple VAS, Google Smart Tap, QR, NFC, MIFARE). The payment method goes in payment.method.

Available options:
APPLE_VAS,
GOOGLE_SMART_TAP,
QR,
NFC_TYPE_1,
NFC_TYPE_2,
NFC_TYPE_3,
NFC_TYPE_4,
NFC_TYPE_5,
MIFARE,
OTHER
remainingUsesBefore
integer

Number of remaining uses before this transaction (for access control)

terminalId
string

ID of the terminal that processed the transaction

storeId
string

ID of the store where transaction occurred

transactionDate
string

ISO 8601 timestamp when transaction occurred (defaults to now). Accepts both timezone-bearing (2026-06-02T12:13:14Z) and timezone-less (2026-06-02T12:13:14, treated as UTC) forms.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$
reference
string

External transaction reference or receipt number

Maximum string length: 255
pointsEarned
integer

Loyalty points earned in this transaction

Required range: x >= 0
statusReason
string

Reason for transaction status (e.g., denial reason)

Maximum string length: 500
remainingUsesAfter
integer

Number of remaining uses after this transaction (for access control)

payment
object

Payment details for the transaction

additionalData
object

Custom data attached to the transaction. Only pos, posData, posRegisterId, posEftPosText, pspData, mcc, and lineItems are accepted — posData/pspData accept arbitrary JSON, everything else does not.

status
enum<string>

Transaction status

Available options:
APPROVED,
DENIED,
FAILED,
PENDING

Response

201 response

Response envelope carrying a transaction.

data
TransactionModel · object
required

Record of a pass scan, purchase, or redemption.

requestId
string
required

Unique request identifier for debugging

Pattern: ^[0-9A-Z]{26}$