Transações

Endpoints para processar pagamentos, consultar histórico e realizar estornos.

Autenticação

Todas as requisições exigem Basic Auth. Use as credenciais configuradas no TEF IP (admin / senha definida na instalação).

POST /transaction

Inicia um pagamento no terminal. O TEF IP aguarda o app estar em primeiro plano por até 15 segundos antes de processar — se o app estiver minimizado, o endpoint retorna 503.

App em segundo plano

Se o TEF IP estiver minimizado, aguarda até 15 s pelo retorno ao primeiro plano antes de processar — caso contrário retorna 503. Veja Comportamento → App em segundo plano.

Corpo da requisição

{
  "tPag": "17",
  "amount": 50.00,
  "referenceId": "pedido-001",
  "installments": 1,
  "installmentType": "single",
  "details": {}
}

Campo	Tipo	Obrigatório	Descrição
`tPag`	string	Sim	Tipo de pagamento (ver tabela abaixo)
`amount`	number	Sim	Valor da transação
`referenceId`	string	Não	Identificador externo para conciliação. Sem este campo, a transação não pode ser estornada individualmente — aparece apenas na listagem geral. Use o número do pedido ou UUID da venda.
`installments`	int	Não	Número de parcelas (padrão: `1`)
`installmentType`	string	Não	Modalidade de parcelamento (padrão: `"single"`)
`details`	object	Não	Metadados adicionais da transação

referenceId é necessário para estornos

Sem referenceId, a transação só aparece na listagem geral (GET /transaction) e não pode ser estornada individualmente. Defina-o sempre que a operação puder precisar de estorno futuro.

Valores de tPag

Valor	Descrição
`"01"`	Dinheiro
`"03"`	Crédito
`"04"`	Débito
`"05"`	Cartão-presente
`"17"`	PIX
`"99"`	Desconhecido

Valores de installmentType

Valor	Descrição
`"single"`	Pagamento à vista (padrão)
`"seller"`	Parcelado pelo lojista (sem juros ao comprador)
`"buyer"`	Parcelado pelo comprador (juros ao comprador)

Resposta — 200

{
  "nsu": "123456",
  "cnpj": "05481336000137",
  "cAut": "123456",
  "txid": null,
  "tBand": "01",
  "tPag": "17",
  "details": {}
}

Campo	Tipo	Descrição
`nsu`	string	Número sequencial único gerado pelo adquirente
`cnpj`	string	CNPJ do adquirente/emissor retornado pelo terminal
`cAut`	string	Código de autorização — presente em crédito/débito; `null` em PIX
`txid`	string	Identificador da transação — presente apenas em PIX; `null` nos demais tipos
`tBand`	string	Bandeira do cartão retornada pelo adquirente
`tPag`	string	Código do tipo de pagamento (ver tabela de `tPag`)
`details`	object	Dados adicionais retornados pelo adquirente

Resposta — 503 (app em segundo plano)

{
  "code": 503,
  "message": "Aplicativo em segundo plano. Abra o app para concluir o pagamento."
}

Exemplos de integração

cURLDartJavaScriptPHPRuby

curl -u admin:1234 \
     -H "Content-Type: application/json" \
     -X POST http://localhost:9050/transaction \
     -d '{"tPag":"17","amount":50.00,"referenceId":"pedido-001"}'

// pub.dev/packages/dart_tefip — configure uma vez; demais exemplos nesta página omitem esta etapa
TefIP.baseUrl = 'http://localhost:9050';
TefIP.username = 'admin';
TefIP.password = '1234';
final result = await TefIP.instance.transaction.post(
  transactionRequest: TransactionRequestModel(
    type: TefIPTransactionType.pix,
    amount: 50.00,
    referenceId: 'pedido-001',
  ),
);
print(result.nsu);          // NSU do adquirente
print(result.txid);         // preenchido em PIX
print(result.cAut);         // preenchido em crédito/débito

// TODO: pacote JavaScript ainda não criado — usando fetch diretamente
const res = await fetch('http://localhost:9050/transaction', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('admin:1234'),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ tPag: '17', amount: 50.00, referenceId: 'pedido-001' }),
});
const data = await res.json();

<?php
// TODO: pacote PHP ainda não criado — usando curl diretamente
$ch = curl_init('http://localhost:9050/transaction');
curl_setopt($ch, CURLOPT_USERPWD, 'admin:1234');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'tPag' => '17',
    'amount' => 50.00,
    'referenceId' => 'pedido-001',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

# TODO: pacote Ruby ainda não criado — usando Net::HTTP diretamente
require 'net/http'
require 'json'

uri = URI('http://localhost:9050/transaction')
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req.basic_auth('admin', '1234')
req.body = { tPag: '17', amount: 50.00, referenceId: 'pedido-001' }.to_json
res = Net::HTTP.start(uri.hostname, uri.port) { |h| h.request(req) }
data = JSON.parse(res.body)

GET /transaction

Lista todas as transações registradas no terminal.

Resposta — 200

Array de transações, cada uma com a mesma estrutura do retorno de POST /transaction.

[
  {
    "nsu": "123456",
    "cnpj": "05481336000137",
    "cAut": "123456",
    "txid": null,
    "tBand": "01",
    "tPag": "17",
    "details": {}
  }
]

Exemplos de integração

cURLDartJavaScriptPHPRuby

curl -u admin:1234 \
     http://localhost:9050/transaction

final transactions = await TefIP.instance.transaction.getAll();
for (final t in transactions) {
  print(t.nsu);
}

// TODO: pacote JavaScript ainda não criado — usando fetch diretamente
const res = await fetch('http://localhost:9050/transaction', {
  headers: {
    'Authorization': 'Basic ' + btoa('admin:1234'),
  },
});
const data = await res.json();

<?php
// TODO: pacote PHP ainda não criado — usando curl diretamente
$ch = curl_init('http://localhost:9050/transaction');
curl_setopt($ch, CURLOPT_USERPWD, 'admin:1234');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

# TODO: pacote Ruby ainda não criado — usando Net::HTTP diretamente
require 'net/http'
require 'json'

uri = URI('http://localhost:9050/transaction')
req = Net::HTTP::Get.new(uri)
req.basic_auth('admin', '1234')
res = Net::HTTP.start(uri.hostname, uri.port) { |h| h.request(req) }
data = JSON.parse(res.body)

GET /transaction/{referenceId}

Busca uma transação específica pelo identificador externo informado no momento do pagamento.

Parâmetros de rota

Parâmetro	Tipo	Descrição
`referenceId`	string	Identificador externo da transação

Resposta — 200

{
  "nsu": "123456",
  "cnpj": "05481336000137",
  "cAut": "123456",
  "txid": null,
  "tBand": "01",
  "tPag": "17",
  "details": {}
}

Exemplos de integração

cURLDartJavaScriptPHPRuby

curl -u admin:1234 \
     http://localhost:9050/transaction/pedido-001

final transaction = await TefIP.instance.transaction.get(referenceId: 'pedido-001');
print(transaction.nsu);

// TODO: pacote JavaScript ainda não criado — usando fetch diretamente
const res = await fetch('http://localhost:9050/transaction/pedido-001', {
  headers: {
    'Authorization': 'Basic ' + btoa('admin:1234'),
  },
});
const data = await res.json();

<?php
// TODO: pacote PHP ainda não criado — usando curl diretamente
$referenceId = 'pedido-001';
$ch = curl_init("http://localhost:9050/transaction/{$referenceId}");
curl_setopt($ch, CURLOPT_USERPWD, 'admin:1234');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

# TODO: pacote Ruby ainda não criado — usando Net::HTTP diretamente
require 'net/http'
require 'json'

reference_id = 'pedido-001'
uri = URI("http://localhost:9050/transaction/#{reference_id}")
req = Net::HTTP::Get.new(uri)
req.basic_auth('admin', '1234')
res = Net::HTTP.start(uri.hostname, uri.port) { |h| h.request(req) }
data = JSON.parse(res.body)

POST /transaction/{referenceId}/reversal

Realiza o estorno de uma transação pelo seu referenceId. Assim como o pagamento, aguarda o app estar em primeiro plano por até 15 segundos.

Parâmetros de rota

Parâmetro	Tipo	Descrição
`referenceId`	string	Identificador externo da transação a estornar

Não há corpo na requisição.

Resposta — 200

Mesma estrutura de POST /transaction.

{
  "nsu": "123456",
  "cnpj": "05481336000137",
  "cAut": "123456",
  "txid": null,
  "tBand": "01",
  "tPag": "17",
  "details": {}
}

Resposta — 503 (app em segundo plano)

{
  "code": 503,
  "message": "Aplicativo em segundo plano. Abra o app para concluir o estorno."
}

Exemplos de integração

cURLDartJavaScriptPHPRuby

curl -u admin:1234 \
     -X POST http://localhost:9050/transaction/pedido-001/reversal

final result = await TefIP.instance.reversal.post(referenceId: 'pedido-001');
print(result.nsu);

// TODO: pacote JavaScript ainda não criado — usando fetch diretamente
const res = await fetch('http://localhost:9050/transaction/pedido-001/reversal', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('admin:1234'),
  },
});
const data = await res.json();

<?php
// TODO: pacote PHP ainda não criado — usando curl diretamente
$referenceId = 'pedido-001';
$ch = curl_init("http://localhost:9050/transaction/{$referenceId}/reversal");
curl_setopt($ch, CURLOPT_USERPWD, 'admin:1234');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

# TODO: pacote Ruby ainda não criado — usando Net::HTTP diretamente
require 'net/http'
require 'json'

reference_id = 'pedido-001'
uri = URI("http://localhost:9050/transaction/#{reference_id}/reversal")
req = Net::HTTP::Post.new(uri)
req.basic_auth('admin', '1234')
res = Net::HTTP.start(uri.hostname, uri.port) { |h| h.request(req) }
data = JSON.parse(res.body)