DART_TEFIP


Dart SDK for communicating with TEF IP terminals, enabling transactions, printing, and display management.
Explore the docs »

Report Bug · Request Feature


Version Pub Points Dart


Table of Contents
  1. About The Project
  2. Getting Started
  3. How to Use
  4. Features
  5. Contributing
  6. Contact
  7. Acknowledgements

About The Project

dart_tefip is a Dart SDK for interacting with TEF IP payment terminals. It provides a structured way to:

  • Perform transactions (pix, credit, debit) and reversals
  • Query transaction status and terminal info
  • Display text, images, and carousels on the terminal
  • Print text, images, or XML documents
  • Ask user input through terminal questions
  • Restart terminals (returns 403 on non-Android/iOS devices by business rules)

The SDK uses a consistent exception handling pattern:

  • TefIPRequestException for network or endpoint errors
  • TefIPUnexpectedException for unhandled exceptions

The goal is to centralize communication with TEF IP devices with minimal boilerplate.

This project is distributed under the MIT License. See LICENSE for more information.

(back to top)

Getting Started

Add dart_tefip to your project:

dependencies:
  dart_tefip: x.x.x

Or using Dart Pub:

dart pub add dart_tefip

(back to top)

How to Use

Initialize the terminal instance:

final tefIP = TefIP.instance;

Terminal Info & Status

final info = await tefIP.info.get();
final status = await tefIP.status.get();

Transactions

Get all transactions:

final transactions = await tefIP.transaction.getAll();

Get a single transaction:

final transaction = await tefIP.transaction.get(referenceId: transactions.first.referenceId);

Create a new transaction:

final postTransaction = await tefIP.transaction.post(
  transactionRequest: TransactionRequestModel(
    referenceId: '12345',
    type: TefIPTransactionType.pix,
    amount: 777.77,
  ),
);

Perform a reversal:

final reversalTransaction = await tefIP.reversal.post(referenceId: '12345');

Printing

Print an image:

final result = await tefIP.printImage.post(imageData: await _imageFromPathToBytes('assets/example.png'));

Print text:

final result = await tefIP.printText.post(
  text: List<Map<String, dynamic>>.from(await _jsonFromPath('assets/print_text_example.json')),
);

Print XML:

final result = await tefIP.printXml.post(xml: await _xmlFromPath('assets/example.xml'));

Display

Display images, carousels, or text:

final displayImageResult = await tefIP.displayImage.post(
  imageData: await _imageFromPathToBytes('assets/example_display.png'),
);

final displayTextResult = await tefIP.displayText.post(
  displayTextRequest: DisplayTextRequestModel(
    content: List<Map<String, dynamic>>.from(await _jsonFromPath('assets/display_text_example.json')),
    backgroundColor: 'white',
    showCloseButton: false,
  ),
);

final displayClearResult = await tefIP.displayClear.post();

Ask for user input:

final askResult = await tefIP.ask.post(
  questionRequest: QuestionRequestModel(type: TefIPQuestionType.cpfOrcnpj),
);

Restart terminal:

try {
  final restartResult = await tefIP.restart.post();
} catch (e) {
  print('Restart not allowed on this device.');
}

(back to top)

Features

  • ✅ Transaction management (pix, debit, credit)
  • ✅ Reversal support
  • ✅ Terminal info and status queries
  • ✅ Display text, image, and carousel
  • ✅ Printing: text, images, XML
  • ✅ Asking user input via terminal
  • ✅ Restart terminal (Android/iOS only)
  • ✅ Consistent exception handling (TefIPRequestException, TefIPUnexpectedException)
  • ✅ Async operations

(back to top)

Contributing

Contributions are welcome. Fork the repo, create a branch, commit, and submit a pull request. Follow Conventional Commits and Semantic Versioning.

(back to top)

Contact

(back to top)

Maintained by

Built and maintained by DJSYSTEM.

(back to top)

Libraries

dart_tefip