> ## 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

> Estructuras opcionales para originDetails.paymentDetails y destinationDetails.paymentDetails — en la API de monitoreo transaccional gu1 para fraude y AML.

## Resumen

Puedes enviar un objeto **paymentDetails** dentro de [originDetails](/es/use-cases/transaction-monitoring/api-reference#origindetails) y/o [destinationDetails](/es/use-cases/transaction-monitoring/api-reference#destinationdetails) al crear una transacción. Esta página describe **estructuras sugeridas** por método de pago. **Nada se exige:** la API acepta cualquier forma y campos extra; usalo solo como referencia.

* **Dónde:** `originDetails.paymentDetails`, `destinationDetails.paymentDetails`
* **Opcional:** Sí. Omitir si no necesitás detalles de pago.
* **Campos custom:** Cualquier clave adicional se almacena tal cual. No estás restringido a los campos de abajo.

### Parte desconocida (visualización en grafos)

Cuando el **origen** o **destino** **no** es una entidad en gu1 (no enviás `originEntityId`/`originExternalId` o `destinationEntityId`/`destinationExternalId`), podés enviar datos identificadores para que los **grafos de red** muestren un único nodo "pseudo" por parte desconocida.

El grafo usa el **primer** identificador que coincida (orden de prioridad). Los valores se normalizan (solo alfanuméricos) antes de agrupar:

| Prioridad | Campo             | Tipo   | Notas                                                                                                                                           |
| --------- | ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| 1         | `taxId`           | string | Ej. CPF, CNPJ, CUIT. Mismo valor normalizado = un nodo.                                                                                         |
| 2         | `cbu`             | string | CBU Argentina (22 dígitos). Recomendado si la contraparte se identifica por CBU.                                                                |
| 3         | `cvu`             | string | CVU Argentina (22 dígitos).                                                                                                                     |
| 4         | `pixKey`          | string | Clave PIX (Brasil).                                                                                                                             |
| 5         | `clabe`           | string | CLABE (México).                                                                                                                                 |
| 6         | `alias`           | string | Alias de pago (ej. alias CVU).                                                                                                                  |
| 7         | `iban`            | string | IBAN.                                                                                                                                           |
| 8         | `holderId`        | string | Documento del titular cuando no hay `taxId`.                                                                                                    |
| 9         | `debinId`         | string | ID DEBIN (Argentina).                                                                                                                           |
| 10        | `cardFingerprint` | string | Token/huella de tarjeta (mín. 8 caracteres). Preferir sobre `bin` o `cardLast4` solos.                                                          |
| 11        | `accountNumber`   | string | Número de cuenta genérico; se agrupa con `bankCode` opcional. También se muestra inline en la tabla de transacciones cuando no hay CBU/CVU/etc. |
| —         | `bankCode`        | string | Modificador opcional para agrupar `accountNumber` y mostrar inline en la tabla.                                                                 |

**No se usan para agrupar nodos pseudo (demasiado ambiguos):** `bin`, `cardLast4` por sí solos. Para tarjetas sin entidad vinculada, enviá `cardFingerprint`.

Estos campos son **opcionales** y de uso interno (visualización en grafos). No son obligatorios para crear la transacción.

**Vincular entidad real vs solo grafo:** para **vincular** a una persona/empresa (tercer criterio tras `*EntityId` y `*ExternalId` y, si hay match, rellenar nombre/país), enviá `originTaxId` / `destinationTaxId` en el **cuerpo raíz**; ver [Crear transacción (origen/destino)](/es/api-reference/transactions/create#origen-entidad). Un `taxId` **solo** dentro de `*Details` **no** ejecuta esa vinculación; solo agrupa en el grafo.

***

## Tarjeta (CARD)

Campos sugeridos cuando `paymentMethod` es `CARD`:

| Campo            | Tipo   | Notas                                                 |
| ---------------- | ------ | ----------------------------------------------------- |
| `cardholderName` | string | Nombre en la tarjeta                                  |
| `cardLast4`      | string | Últimos 4 dígitos (4 caracteres)                      |
| `cardBrand`      | string | ej. `Visa`, `Mastercard`, `Amex`, `Discover`, `Other` |
| `cardType`       | string | `credit`, `debit`, `prepaid`                          |
| `expiryMonth`    | string | MM (01-12)                                            |
| `expiryYear`     | string | YYYY                                                  |
| `bankName`       | string | Banco emisor                                          |
| `bankCode`       | string | Código banco                                          |
| `accountType`    | string | `personal`, `business`, `merchant`                    |
| `issuerCountry`  | string | País emisor (ISO 2 letras)                            |
| `bin`            | string | Primeros 6 dígitos (BIN)                              |
| `timestamp`      | string | Cuándo ocurrió el pago                                |
| `transactionId`  | string | Tu referencia de transacción                          |
| `reference`      | string | Referencia adicional                                  |
| `country`        | string | ISO 2 letras                                          |

***

## PIX (Brasil)

Campos sugeridos para PIX:

| Campo                  | Tipo   | Notas                                              |
| ---------------------- | ------ | -------------------------------------------------- |
| `pixKey`               | string | Clave PIX (email, teléfono, CPF, CNPJ o aleatoria) |
| `pixType`              | string | `email`, `phone`, `cpf`, `cnpj`, `random`          |
| `bankName`             | string | Nombre del banco                                   |
| `bankCode`             | string | Código del banco                                   |
| `endToEndId`           | string | ID end-to-end PIX                                  |
| `returnIdentification` | string | Identificación de retorno                          |
| `timestamp`            | string |                                                    |
| `transactionId`        | string |                                                    |
| `reference`            | string |                                                    |
| `country`              | string | ISO 2 letras                                       |

***

## Transferencia bancaria (ACH, wire, SEPA, TED)

Campos sugeridos genéricos:

| Campo           | Tipo   | Notas                                 |
| --------------- | ------ | ------------------------------------- |
| `accountNumber` | string | Número de cuenta                      |
| `routingNumber` | string | Routing number (EE.UU.)               |
| `swiftCode`     | string | SWIFT/BIC                             |
| `iban`          | string | IBAN                                  |
| `bankName`      | string | Nombre del banco                      |
| `bankCode`      | string | Código del 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 | Nombre del banco                  |
| `bankCode`      | string | Código del 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 (Colombia)

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`.

***

## Criptomonedas

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

***

## Efectivo

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

***

## Cheque

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

***

## E-Wallet / billetera digital

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

***

## Otro / genérico

Para cualquier otro método: `timestamp`, `transactionId`, `reference`, `country` y cualquier clave custom que necesites.

***

## Ejemplos

**Origen con paymentDetails de tarjeta:**

```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 con 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:** Podés mezclar cualquier campo de arriba con claves propias; la API no restringe las claves dentro de `paymentDetails`.

***

## Ver también

* [Referencia API Crear Transacción](/es/use-cases/transaction-monitoring/api-reference) — `originDetails` y `destinationDetails`
* [Enum Razón de Transacción](/es/api-reference/transactions/reason-enum) — Campo opcional `reason`