Skip to main content

Transaction Processing

Transaction Flow Overview​

The diagram below illustrates the standard transaction flow between the terminal, Stitch, and the payment acquirer:

Transaction Operations​

1. Charge Transaction​

The charge request initiates a payment transaction with the following key components:

  • Encrypted EMV TLV Data: Contains card and transaction details
  • Encrypted PIN (optional): Required when online PIN verification is needed
  • Unique Reference ID: Generated by the terminal app to prevent duplicate transactions

Data Encryption Requirements​

  • EMV TLV data and PIN blocks are typically encrypted using DUKPT with keys created during RKI
  • The TLV data should be wrapped in a tag 0x70 template before padding and encryption
  • RSA encryption is also supported using PKCS 1 or PKCS 5 padding (keys generated via the transaction-keys API)
note

Tag 0x70 wrapping might not be possible on all terminals. For example, the Miura M010 uses a combination of encrypted and unencrypted tags.

2. Transaction Confirmation​

A successful transaction requires confirmation to prevent automatic reversal by the Stitch platform:

  • Signature Confirmation: If the EMV CVM requires a cardholder signature, submit a base64-encoded signature image using the sign API
  • Standard Confirmation: When no signature is required, use the confirm API

3. Reversals and Voids​

There are two ways to cancel a transaction:

  • Reversal: Used for technical issues or when the card rejects the response
    • Can be performed using the reference ID (when transaction ID is not available)
    • Can be performed using the transaction ID (when available)
  • Void: A user-initiated cancellation of the transaction
    • The charge response includes a voidableUntilTime field indicating the deadline for voiding
note

If a reversal occurs at or after acquirer cut-over time, it may fail and require a manual refund instead.

4. Refunds​

A refund is a new transaction that returns funds to the cardholder:

  • Can be for the full or partial amount of the original transaction.
  • Flows money in the opposite direction of the original charge.
note

The Stitch platform supports both card-present and card-not-present refunds. Card-not-present refunds are not available for app integrations and require a B2B API integration.

5. Single TAP & PIN Processing​

For contactless transactions that require PIN verification, Stitch supports a "Single TAP & PIN" flow that doesn't require the card to be inserted:

  • A decline with response code 65 indicates the cardholder should provide a PIN rather than insert their card
  • The TLV must contain tag 0xDFCF50 (a 4-bit numeric value) to support this flow:
    • bit 1: Not used.
    • bit 2: Indicates support for Single Tap & PIN.
    • bit 3: Indicates a reply with PIN.
    • bit 4: Indicates a request for PIN.
note

Response code 65 is treated as a "fall forward" indicator instructing the cardholder to attempt the transaction again with a PIN. Traditionally, "fall forward" would mean inserting the card, but in this flow, the card remains tapped.

Single TAP & PIN Flow​

APIs​