# Detalhes de execução do payout

Quando um pagamento é processado, Payments Direct pode retornar metadados de execução vindos do payout network em um campo opcional chamado `payoutExecutionDetails` na resposta do Get Payment by ID. Quando presente, esse objeto traz informações de rastreamento que podem ser usadas para auditoria, conciliação ou resolução de dúvidas de clientes.

O `payoutExecutionDetails` não é retornado em todos os pagamentos. A presença dele depende de a rede que processou o pagamento oferecer o reporte de detalhes de execução. Trate este campo como um enriquecimento opcional e não construa fluxos obrigatórios que dependam da presença dele.

## Campos

O objeto `payoutExecutionDetails` contém os seguintes campos:

| Campo  | Tipo | Descrição |
|  --- | --- | --- |
| `paymentRailUsed` | string | O payment rail ou a rede usada para executar o payout (por exemplo, `FEDWIRE`, `ACH`, `SEPA_CT`). |
| `payoutStartTime` | timestamp ISO 8601 | O momento em que a execução do payout começou, em UTC. |
| `payoutEndTime` | timestamp ISO 8601 | O momento em que a execução do payout foi concluída ou atualizada pela última vez, em UTC. Em payouts em andamento, pode representar o horário da última atualização de status. |
| `trackingReferences` | array | Um ou mais identificadores de rastreamento específicos da rede. Consulte [Referências de rastreamento](#refer%C3%AAncias-de-rastreamento). |


## Referências de rastreamento

Cada entrada do array `trackingReferences` representa um identificador do pagamento específico da rede. O array pode conter mais de uma entrada.

| Campo  | Tipo | Descrição |
|  --- | --- | --- |
| `referenceType` | string | Identifica o que o valor da referência representa (por exemplo, `IMAD`, `END_TO_END_REFERENCE`, `CRYPTO_TRANSACTION_HASH`). |
| `value` | string | O valor da referência. |
| `displayName` | string | Um rótulo legível por humanos para o tipo de referência. |
| `description` | string | Uma breve explicação do tipo de referência. |


Use o campo `referenceType` para identificar o que cada valor representa. Não confie na posição das entradas no array, porque a ordem não é garantida.

## Exemplo

Veja a seguir um exemplo de objeto `payoutExecutionDetails` como ele apareceria em uma resposta do Get Payment by ID:

```json
{
  "payoutExecutionDetails": {
    "paymentRailUsed": "FEDWIRE",
    "payoutStartTime": "2026-02-18T14:22:15.789Z",
    "payoutEndTime": "2026-02-18T14:25:30.123Z",
    "trackingReferences": [
      {
        "referenceType": "IMAD",
        "value": "20260218MMQFMP2P003836",
        "displayName": "Input Message Accountability Data",
        "description": "A unique identifier assigned by the Fedwire system to each transaction."
      }
    ]
  }
}
```

## Orientações

- O `payoutExecutionDetails` deve ser tratado apenas como informativo. Não construa fluxos obrigatórios que dependam da presença dele, porque a disponibilidade varia e não é garantida para nenhum pagamento específico.
- Quando presente, o `trackingReferences` fornece identificadores específicos da rede, úteis para auditoria, conciliação ou resolução de dúvidas de clientes.
- Use o campo `referenceType` de cada referência de rastreamento para identificar o que um valor representa, em vez de confiar na posição dele no array.
- A cobertura vai aumentar conforme novos corredores e redes forem integrados.