DART_TEFIP

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

Report Bug · Request Feature

---

Table of Contents

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

---

Platform Support

Android	iOS	Web	macOS	Windows	Linux
✅	✅	✅	✅	✅	✅

---

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
• Manage sales: items, payments, finalization, and cancellation
• 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 and configure the connection:

TefIP.baseUrl = "http://localhost:8080";
TefIP.username = "admin";
TefIP.password = "1234";

Timeout

By default, requests wait indefinitely — suitable for TEF IP terminals that may take an unpredictable amount of time to respond (e.g., waiting for payment confirmation on the physical terminal).

To apply a global timeout:

TefIP.requestsTimeOut = const Duration(minutes: 2);

You can also pass a per-call timeout to individual endpoint methods that support it.

Initialize the terminal instance:

final tefIP = TefIP.instance;

Error Handling

All endpoints throw typed exceptions — wrap calls with a try/catch:

try {
  final result = await tefIP.transaction.post(
    transactionRequest: TransactionRequestModel(
      referenceId: '12345',
      type: TefIPTransactionType.pix,
      amount: 100.00,
    ),
  );
} on TefIPRequestException catch (e) {
  // HTTP 4xx/5xx or connection refused (statusCode == -1)
  print('Request error ${e.statusCode}: ${e.message}');
  print('Raw body: ${e.rawBody}');
} on TefIPUnexpectedException catch (e) {
  // Unhandled/unexpected error
  print('Unexpected error: ${e.exception}');
}

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,
  ),
);

Access acquirer fields from the response:

// PIX — access the txid returned by the acquirer
print(postTransaction.txid); // e.g. "abc123txid"

// Credit/debit — access the authorization code
print(postTransaction.cAut); // e.g. "123456"

Perform a reversal:

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

Sale

Start a sale:

await tefIP.sale.post(
  request: SaleStartRequestModel(...),
);

Update an active sale:

await tefIP.sale.patch(
  request: SaleStartRequestModel(...),
);

Add an item:

await tefIP.saleItem.post(item: SaleItemModel(...));

Update an item:

await tefIP.saleItem.patch(itemId: 'ITEM-001', item: SaleItemModel(...));

Remove an item:

await tefIP.saleItem.delete(itemId: 'ITEM-001');

Cancel an item:

await tefIP.saleItem.cancel(itemId: 'ITEM-001');

Add a payment:

await tefIP.salePayment.post(payment: SalePaymentModel(...));

Update a payment:

await tefIP.salePayment.patch(paymentId: 'PGTO-001', payment: SalePaymentModel(...));

Remove a payment:

await tefIP.salePayment.delete(paymentId: 'PGTO-001');

Finalize the sale:

await tefIP.saleFinalize.post();

Cancel the sale:

await tefIP.saleCancel.post();

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();

final displayPopResult = await tefIP.displayPop.post();

Ask for user input (single question):

final askResult = await tefIP.ask.post(
  askRequest: AskSingleQuestionRequestModel(
    question: AskQuestionModel(type: TefIPQuestionType.cpfOrcnpj),
    parameters: AskParametersModel(),
  ),
);

Ask for user input (multiple questions form):

final askFormResult = await tefIP.askForm.post(
  askFormRequest: AskFormRequestModel(
    questions: [
      AskQuestionModel(type: TefIPQuestionType.cpfOrcnpj),
      AskQuestionModel(type: TefIPQuestionType.customString),
    ],
    parameters: AskParametersModel(),
  ),
);

Cancel an ongoing ask request:

final cancelResult = await tefIP.askCancel.post();

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
• ✅ Sale management (items, payments, finalize, cancel)
• ✅ Terminal info and status queries
• ✅ Display text, image, and carousel
• ✅ Printing: text, images, XML
• ✅ Question endpoint for terminal input (single and form)
• ✅ Cancel terminal input
• ✅ 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: TEF IP
• Website: https://www.djsystem.com.br

(back to top)

---

Maintained by

Built and maintained by DJSYSTEM.

(back to top)