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

# Schema Payment Details

> Estruturas opcionais para originDetails.paymentDetails e destinationDetails.paymentDetails — na API de monitoramento de transações gu1 para fraude e AML.

## Resumo

Você pode enviar um objeto **paymentDetails** dentro de [originDetails](/pt/use-cases/transaction-monitoring/api-reference#origindetails) e/ou [destinationDetails](/pt/use-cases/transaction-monitoring/api-reference#destinationdetails) ao criar uma transação. Esta página descreve **estruturas sugeridas** por método de pagamento. **Nada é exigido:** a API aceita qualquer formato e campos extras; use apenas como referência.

* **Onde:** `originDetails.paymentDetails`, `destinationDetails.paymentDetails`
* **Opcional:** Sim. Omita se não precisar de detalhes de pagamento.
* **Campos custom:** Qualquer chave adicional é armazenada como está. Você não está restrito aos campos abaixo.

### Parte desconhecida (visualização em grafos)

Quando a **origem** ou o **destino** **não** é uma entidade no gu1 (você não envia `originEntityId`/`originExternalId` ou `destinationEntityId`/`destinationExternalId`), pode enviar dados identificadores para que os **grafos de rede** mostrem um único nó "pseudo" por parte desconhecida.

O grafo usa o **primeiro** identificador que corresponder (ordem de prioridade). Os valores são normalizados (apenas alfanuméricos) antes do agrupamento:

| Prioridade | Campo             | Tipo   | Notas                                                                                                                                         |
| ---------- | ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 1          | `taxId`           | string | Ex.: CPF, CNPJ. Mesmo valor normalizado = um nó.                                                                                              |
| 2          | `cbu`             | string | CBU Argentina (22 dígitos).                                                                                                                   |
| 3          | `cvu`             | string | CVU Argentina (22 dígitos).                                                                                                                   |
| 4          | `pixKey`          | string | Chave PIX (Brasil).                                                                                                                           |
| 5          | `clabe`           | string | CLABE (México).                                                                                                                               |
| 6          | `alias`           | string | Alias de pagamento.                                                                                                                           |
| 7          | `iban`            | string | IBAN.                                                                                                                                         |
| 8          | `holderId`        | string | Documento do titular quando não há `taxId`.                                                                                                   |
| 9          | `debinId`         | string | ID DEBIN (Argentina).                                                                                                                         |
| 10         | `cardFingerprint` | string | Token/impressão digital do cartão (mín. 8 caracteres). Preferir a `bin` ou `cardLast4` isolados.                                              |
| 11         | `accountNumber`   | string | Número de conta genérico; agrupado com `bankCode` opcional. Também aparece inline na tabela de transações quando CBU/CVU/etc. estão ausentes. |
| —          | `bankCode`        | string | Modificador opcional para agrupar `accountNumber` e exibir inline na tabela.                                                                  |

**Não usados para agrupar nós pseudo (ambíguos):** `bin`, `cardLast4` sozinhos. Para cartões sem entidade vinculada, envie `cardFingerprint`.

Estes campos são **opcionais** e de uso interno (visualização em grafos). Não são obrigatórios para criar a transação.

**Vínculo com entidade vs só grafo:** para **vincular** pessoa/empresa (terceiro critério e enriquecimento de nome/país), use `originTaxId` / `destinationTaxId` no **raiz** do corpo; ver [Criar transação (origem)](/pt/api-reference/transactions/create#origem-entidade). Só `taxId` em `*Details` **não** faz o match; só ajuda a agrupar no grafo.

***

## Cartão (CARD)

Campos sugeridos quando `paymentMethod` é `CARD`:

| Campo            | Tipo   | Notas                                                  |
| ---------------- | ------ | ------------------------------------------------------ |
| `cardholderName` | string | Nome no cartão                                         |
| `cardLast4`      | string | Últimos 4 dígitos (4 caracteres)                       |
| `cardBrand`      | string | ex.: `Visa`, `Mastercard`, `Amex`, `Discover`, `Other` |
| `cardType`       | string | `credit`, `debit`, `prepaid`                           |
| `expiryMonth`    | string | MM (01-12)                                             |
| `expiryYear`     | string | YYYY                                                   |
| `bankName`       | string | Banco emissor                                          |
| `bankCode`       | string | Código do banco                                        |
| `accountType`    | string | `personal`, `business`, `merchant`                     |
| `issuerCountry`  | string | País emissor (ISO 2 letras)                            |
| `bin`            | string | Primeiros 6 dígitos (BIN)                              |
| `timestamp`      | string | Quando o pagamento ocorreu                             |
| `transactionId`  | string | Sua referência de transação                            |
| `reference`      | string | Referência adicional                                   |
| `country`        | string | ISO 2 letras                                           |

***

## PIX (Brasil)

Campos sugeridos para PIX:

| Campo                  | Tipo   | Notas                                               |
| ---------------------- | ------ | --------------------------------------------------- |
| `pixKey`               | string | Chave PIX (email, telefone, CPF, CNPJ ou aleatória) |
| `pixType`              | string | `email`, `phone`, `cpf`, `cnpj`, `random`           |
| `bankName`             | string | Nome do banco                                       |
| `bankCode`             | string | Código do banco                                     |
| `endToEndId`           | string | ID end-to-end PIX                                   |
| `returnIdentification` | string | Identificação de retorno                            |
| `timestamp`            | string |                                                     |
| `transactionId`        | string |                                                     |
| `reference`            | string |                                                     |
| `country`              | string | ISO 2 letras                                        |

***

## Transferência bancária (ACH, wire, SEPA, TED)

Campos sugeridos genéricos:

| Campo           | Tipo   | Notas                                 |
| --------------- | ------ | ------------------------------------- |
| `accountNumber` | string | Número da conta                       |
| `routingNumber` | string | Routing number (EUA)                  |
| `swiftCode`     | string | SWIFT/BIC                             |
| `iban`          | string | IBAN                                  |
| `bankName`      | string | Nome do banco                         |
| `bankCode`      | string | Código do banco                       |
| `accountType`   | string | `checking`, `savings`, `business`     |
| `transferType`  | string | `wire`, `ach`, `sepa`, `ted`, `other` |
| `timestamp`     | string |                                       |
| `transactionId` | string |                                       |
| `reference`     | string |                                       |
| `country`       | string | ISO 2 letras                          |

***

## CBU / CVU (Argentina)

Campos sugeridos para CBU/CVU:

| Campo           | Tipo   | Notas                             |
| --------------- | ------ | --------------------------------- |
| `cbu`           | string | CBU (22 dígitos)                  |
| `cvu`           | string | CVU (22 dígitos)                  |
| `alias`         | string | Alias                             |
| `bankName`      | string | Nome do banco                     |
| `bankCode`      | string | Código do banco                   |
| `accountType`   | string | `caja_ahorro`, `cuenta_corriente` |
| `timestamp`     | string |                                   |
| `transactionId` | string |                                   |
| `reference`     | string |                                   |
| `country`       | string | ISO 2 letras                      |

***

## SPEI (México)

Campos sugeridos: `clabe` (18 dígitos), `bankName`, `bankCode`, `trackingKey`, `timestamp`, `transactionId`, `reference`, `country`.

***

## PSE (Colômbia)

Campos sugeridos: `bankName`, `bankCode`, `transactionReference`, `pseTransactionId`, `timestamp`, `transactionId`, `reference`, `country`.

***

## DEBIN (Argentina)

Campos sugeridos: `debinId`, `bankName`, `bankCode`, `cbu` (22 dígitos), `timestamp`, `transactionId`, `reference`, `country`.

***

## Criptomoedas

Campos sugeridos: `walletAddress`, `cryptoType` (`bitcoin`, `ethereum`, `usdt`, `usdc`, `stablecoin`, `other`), `network`, `txHash`, `confirmations`, `gasFee`, `timestamp`, `transactionId`, `reference`, `country`.

***

## Dinheiro

Campos sugeridos: `location`, `receiptNumber`, `cashierName`, `timestamp`, `transactionId`, `reference`, `country`.

***

## Cheque

Campos sugeridos: `checkNumber`, `bankName`, `routingNumber`, `accountNumber`, `timestamp`, `transactionId`, `reference`, `country`.

***

## E-Wallet / carteira digital

Campos sugeridos: `walletProvider` (ex.: PayPal, Mercado Pago), `walletId`, `accountEmail`, `accountPhone`, `walletType` (`digital`, `mobile`, `crypto`), `timestamp`, `transactionId`, `reference`, `country`.

***

## Outro / genérico

Para qualquer outro método: `timestamp`, `transactionId`, `reference`, `country` e qualquer chave custom que precisar.

***

## Exemplos

**Origem com paymentDetails de cartão:**

```json theme={null}
{
  "originDetails": {
    "deviceType": "mobile",
    "ipAddress": "189.123.45.67",
    "country": "BR",
    "paymentDetails": {
      "cardLast4": "4242",
      "cardBrand": "Visa",
      "cardType": "credit",
      "issuerCountry": "BR",
      "bin": "123456"
    }
  }
}
```

**Destino com paymentDetails PIX:**

```json theme={null}
{
  "destinationDetails": {
    "merchantName": "Loja XYZ",
    "mcc": "5411",
    "paymentDetails": {
      "pixKey": "loja@email.com",
      "pixType": "email",
      "bankName": "Banco do Brasil",
      "endToEndId": "E12345678202101011200abc123"
    }
  }
}
```

**Campos sugeridos + custom:** Você pode misturar qualquer campo acima com chaves próprias; a API não restringe as chaves dentro de `paymentDetails`.

***

## Ver também

* [Referência API Criar Transação](/pt/use-cases/transaction-monitoring/api-reference) — `originDetails` e `destinationDetails`
* [Enum Motivo da Transação](/pt/api-reference/transactions/reason-enum) — Campo opcional `reason`