DART_TEFIP

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

Report Bug · Request Feature

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 #

• GitHub: TefIP
• Website: https://www.djsystem.com.br

(back to top)

Maintained by #

Built and maintained by DJSYSTEM.

(back to top)