Consultar estado de transacción

GET /api/pix/transaction/{id}

GET https://api.avista.global/api/pix/transaction/{id}

Requiere un Bearer token en el header Authorization. Vea Generar Token para obtener uno.

Retorna el estado actual de una transacción PIX con información detallada sobre montos, contraparte y marcas de tiempo.

El identificador puede ser:

ID numérico: Identificador interno de la transacción retornado por Avista
externalId: Identificador externo que usted proporcionó al crear la transacción

Autenticación

Requiere un Bearer token en el header Authorization.

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`id`	string	Sí	ID de la transacción (numérico) o externalId (cadena)

Ejemplos de Código

cURL

curl -X GET "https://api.avista.global/api/pix/transaction/txn_abc123" \
  -H "Authorization: Bearer $AVISTA_TOKEN"

const axios = require('axios');

const response = await axios.get('https://api.avista.global/api/pix/transaction/txn_abc123', {
  headers: { 'Authorization': `Bearer ${process.env.AVISTA_TOKEN}` },
});
console.log(response.data);

import os, requests

response = requests.get(
    'https://api.avista.global/api/pix/transaction/txn_abc123',
    headers={'Authorization': f'Bearer {os.environ["AVISTA_TOKEN"]}'},
)
print(response.json())

$ch = curl_init('https://api.avista.global/api/pix/transaction/txn_abc123');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVISTA_TOKEN'),
    ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.avista.global/api/pix/transaction/txn_abc123"))
    .header("Authorization", "Bearer " + System.getenv("AVISTA_TOKEN"))
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Respuesta (200)

Campo	Tipo	Descripción
`id`	string	ID de la transacción
`externalId`	string \| null	ID externo proporcionado por el cliente
`type`	string	Tipo de transacción: `PAYMENT`, `WITHDRAW`, `REFUND_IN`, `REFUND_OUT`, `TRANSFER`
`status`	string	Estado: `PENDING`, `CONFIRMED`, `ERROR`
`originalAmount`	number	Monto original en BRL
`feeAmount`	number	Monto de la tarifa en BRL
`finalAmount`	number	Monto final en BRL
`e2eId`	string \| null	ID End-to-end de PIX
`counterpartName`	string \| null	Nombre de la contraparte
`counterpartDocument`	string \| null	Documento de la contraparte (CPF/CNPJ)
`counterpartAccountBankCode`	string \| null	Código del banco de la contraparte
`counterpartAccountBranch`	string \| null	Sucursal de la contraparte
`counterpartAccountNumber`	string \| null	Número de cuenta de la contraparte
`counterpartAccountIspb`	string \| null	ISPB del banco de la contraparte
`counterpartAccountBankName`	string \| null	Nombre del banco de la contraparte
`createdAt`	string	Fecha de creación (ISO 8601)
`updatedAt`	string	Fecha de actualización (ISO 8601)
`processedAt`	string \| null	Fecha de procesamiento (ISO 8601)
`refunded`	boolean	Indica si la transacción fue reembolsada (parcial o totalmente). True si hay al menos un reembolso CONFIRMED vinculado.
`partiallyRefunded`	boolean	Indica si la transacción fue reembolsada parcialmente (`refundedAmount > 0` y `refundedAmount < amount`).
`refundedAmount`	number	Suma de los reembolsos CONFIRMED en reales. `0` cuando no hay reembolso o el tipo no es reembolsable.
`refundableAmount`	number	Saldo aún reembolsable en reales. `0` para PENDING/ERROR o tipos no reembolsables.
`relatedTransactions`	array	Transacciones relacionadas. Bidireccional: para PAYMENT/WITHDRAW lista los reembolsos (children); para REFUND_IN/REFUND_OUT lista el parent.

{
  "id": "123",
  "externalId": "ext-001",
  "type": "PAYMENT",
  "status": "CONFIRMED",
  "originalAmount": 100,
  "feeAmount": 1.5,
  "finalAmount": 98.5,
  "e2eId": "E00416968202512121343VX5Sx8fIpkY",
  "counterpartName": "John Marvin",
  "counterpartDocument": "12312312387",
  "counterpartAccountBankCode": "001",
  "counterpartAccountBranch": "0001",
  "counterpartAccountNumber": "123456-7",
  "counterpartAccountIspb": "00000000",
  "counterpartAccountBankName": "Banco do Brasil",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:35:00.000Z",
  "processedAt": "2026-01-15T10:35:00.000Z",
  "refunded": true,
  "partiallyRefunded": true,
  "refundedAmount": 30,
  "refundableAmount": 70,
  "relatedTransactions": [
    {
      "id": "456",
      "externalId": "ext-refund-001",
      "type": "REFUND_IN",
      "status": "CONFIRMED",
      "amount": 30,
      "e2eId": "E0041696820260120ABCxyz1234567",
      "createdAt": "2026-01-20T14:22:00.000Z"
    }
  ]
}

Reembolsos correlacionados

El campo relatedTransactions es bidireccional:

Cuando consultas una transacción PAYMENT o WITHDRAW, lista todos los reembolsos vinculados (REFUND_IN o REFUND_OUT), en cualquier estado.
Cuando consultas una transacción REFUND_IN o REFUND_OUT, lista la transacción original (parent), con 1 elemento en el array.
Para otros tipos (TRANSFER, o transacciones sin relaciones registradas), retorna [].

Solo reembolsos con status: "CONFIRMED" entran en refundedAmount y refundableAmount. Reembolsos PENDING o ERROR aparecen en relatedTransactions pero no afectan los totales.

Errores

Estado	Descripción
401	Token faltante o inválido
404	Transacción no encontrada