> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stylepay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar Transação

> Consulta o status e detalhes de uma transação específica via ID da transação, ID externo ou ambos.

## Autenticação

Esta requisição requer autenticação via headers customizados:

<ParamField header="stpi" type="string" required>
  Seu Client ID.
</ParamField>

<ParamField header="stps" type="string" required>
  Seu Client Secret.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Envie sempre como `application/json`.
</ParamField>

## Body

Você deve enviar um corpo em JSON informando qual transação deseja buscar.

A consulta aceita `payment_id`, `external_id` ou os dois campos juntos.

<ParamField body="payment_id" type="string">
  O ID único da transação gerado pela StylePay.
</ParamField>

<ParamField body="external_id" type="string">
  O seu ID da transação, usado como referência externa gerada pelo seu sistema.
</ParamField>

Quando `payment_id` e `external_id` forem enviados juntos, ambos devem corresponder à mesma transação.

## Resposta

<ResponseField name="statusCode" type="number">
  Código de status HTTP da requisição. Exemplo: `200`.
</ResponseField>

<ResponseField name="message" type="string">
  Mensagem descritiva da operação.
</ResponseField>

<ResponseField name="data" type="object">
  Objeto contendo os detalhes da transação encontrada.

  <Expandable title="propriedades">
    <ResponseField name="payment_id" type="string">
      O ID único da transação na StylePay.
    </ResponseField>

    <ResponseField name="external_id" type="string">
      O seu ID da transação, usado como referência externa.
    </ResponseField>

    <ResponseField name="status" type="string">
      O status atual da transação. Valores possíveis: `PENDING`, `PAID`, `CANCELLED`, `REFUNDED`, `REVERSED`.
    </ResponseField>

    <ResponseField name="amount" type="number">
      O valor bruto da transação em reais.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Data de criação da transação no formato ISO 8601.
    </ResponseField>

    <ResponseField name="confirmed_date" type="string">
      Data de confirmação do pagamento no formato ISO 8601. Retorna `null` quando a transação ainda não foi paga.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://api.stylepay.com.br/api/v1/wallet/transaction' \
    --header 'stpi: seu_client_id' \
    --header 'stps: seu_client_secret' \
    --header 'Content-Type: application/json' \
    --data '{
      "payment_id": "1e6c9f53-fddb-4994-bc02-fd6fe61007fa",
      "external_id": "pedido-1010"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.stylepay.com.br/api/v1/wallet/transaction', {
    method: 'POST',
    headers: {
      stpi: 'seu_client_id',
      stps: 'seu_client_secret',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      payment_id: '1e6c9f53-fddb-4994-bc02-fd6fe61007fa',
      external_id: 'pedido-1010'
    })
  });

  const json = await response.json();

  if (response.ok) {
    const transacao = json.data;

    console.log(`Transação ${transacao.payment_id} está com status: ${transacao.status}`);
  } else {
    console.error(`Erro: ${json.message}`);
  }
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.stylepay.com.br/api/v1/wallet/transaction"

  headers = {
      "stpi": "seu_client_id",
      "stps": "seu_client_secret",
      "Content-Type": "application/json"
  }

  payload = {
      "payment_id": "1e6c9f53-fddb-4994-bc02-fd6fe61007fa",
      "external_id": "pedido-1010"
  }

  response = requests.post(url, headers=headers, json=payload)
  json_response = response.json()

  if response.status_code == 200:
      transacao = json_response["data"]

      print(f"Transação {transacao['payment_id']} está com status: {transacao['status']}")
  else:
      print(f"Erro: {json_response.get('message', 'Erro desconhecido')}")
  ```

  ```php PHP theme={null}
  <?php

  $url = "https://api.stylepay.com.br/api/v1/wallet/transaction";

  $headers = [
      "stpi: seu_client_id",
      "stps: seu_client_secret",
      "Content-Type: application/json"
  ];

  $body = json_encode([
      "payment_id" => "1e6c9f53-fddb-4994-bc02-fd6fe61007fa",
      "external_id" => "pedido-1010"
  ]);

  $ch = curl_init($url);

  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

  $response = curl_exec($ch);

  curl_close($ch);

  $json = json_decode($response, true);

  if (isset($json["data"])) {
      $transacao = $json["data"];

      echo "Transação " . $transacao["payment_id"] . " está com status: " . $transacao["status"];
  } else {
      echo "Erro: " . $json["message"];
  }

  ?>
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "statusCode": 200,
    "message": "Transação encontrada com sucesso.",
    "data": {
      "payment_id": "1e6c9f53-fddb-4994-bc02-fd6fe61007fa",
      "external_id": "pedido-1010",
      "status": "PAID",
      "amount": 150.00,
      "created_at": "2026-05-05T10:00:00.000Z",
      "confirmed_date": "2026-05-05T10:02:15.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "message": "Informe 'payment_id', 'external_id' ou ambos para buscar a transação."
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "message": "O 'payment_id' e o 'external_id' informados não correspondem à mesma transação."
  }
  ```

  ```json 401 theme={null}
  {
    "statusCode": 401,
    "message": "Falha na autenticação."
  }
  ```

  ```json 404 theme={null}
  {
    "statusCode": 404,
    "message": "Transação não encontrada."
  }
  ```

  ```json 500 theme={null}
  {
    "statusCode": 500,
    "message": "Erro interno."
  }
  ```
</ResponseExample>