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

# Payment Details Schema

> Optional structures for originDetails.paymentDetails and destinationDetails.paymentDetails — in the gu1 transaction monitoring API for fraud and AML.

## Overview

You can send a **paymentDetails** object inside [originDetails](/en/api-reference/transactions/create#origindetails) and/or [destinationDetails](/en/api-reference/transactions/create#destinationdetails) when creating a transaction. This page describes **suggested** structures by payment method so the client knows what can be sent. **Nothing is enforced:** the API accepts any shape and any extra fields; use these as a reference only.

* **Where:** `originDetails.paymentDetails`, `destinationDetails.paymentDetails`
* **Optional:** Yes. Omit if you don't need payment-level details.
* **Custom fields:** Any additional keys are stored as-is. You are not restricted to the fields below.

### Unknown Party (Graph Visualization)

When **origin** or **destination** is **not** an entity in gu1 (you do not send `originEntityId`/`originExternalId` or `destinationEntityId`/`destinationExternalId`), you can still send identifying data so that **network graphs** show a single "pseudo" node per unknown party instead of hiding the flow.

The graph uses the **first** matching identifier below (priority order). Values are normalized (alphanumeric only) before grouping:

| Priority | Field             | Type   | Notes                                                                                                                     |
| -------- | ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| 1        | `taxId`           | string | Tax ID (e.g. CPF, CNPJ, CUIT). Same normalized value = one node.                                                          |
| 2        | `cbu`             | string | Argentina CBU (22 digits). Recommended when the unknown party is identified by CBU.                                       |
| 3        | `cvu`             | string | Argentina CVU (22 digits).                                                                                                |
| 4        | `pixKey`          | string | Brazil PIX key.                                                                                                           |
| 5        | `clabe`           | string | Mexico CLABE.                                                                                                             |
| 6        | `alias`           | string | Payment alias (e.g. AR CVU alias).                                                                                        |
| 7        | `iban`            | string | IBAN.                                                                                                                     |
| 8        | `holderId`        | string | Holder document / beneficiary ID when no `taxId`.                                                                         |
| 9        | `debinId`         | string | Argentina DEBIN id.                                                                                                       |
| 10       | `cardFingerprint` | string | Card token/fingerprint (min. 8 chars). Prefer over `bin` or `cardLast4` alone.                                            |
| 11       | `accountNumber`   | string | Generic account number; grouped with optional `bankCode`. Shown inline in transaction table when CBU/CVU/etc. are absent. |
| —        | `bankCode`        | string | Optional modifier for `accountNumber` grouping and inline display.                                                        |

**Not used for pseudo-node grouping (too weak / ambiguous):** `bin`, `cardLast4` by themselves. Send `cardFingerprint` for card flows when you want graph grouping without a linked entity.

These fields are **optional** and for internal use only (graph visualization). They are not required for creating the transaction.

**Linking a real entity by document vs graph-only:** to **auto-link** a person/company to the transaction (and optionally fill name/country from the entity), send **`originTaxId` / `destinationTaxId` on the root body** of the create request (third fallback after `*EntityId` and `*ExternalId` — see [Create transaction — origin/destination fields](/en/api-reference/transactions/create#origin-entity-fields)). A `taxId` **only** inside `originDetails` / `destinationDetails` does **not** run that link; it only helps the graph for unknown parties.

***

## Card (CARD)

Suggested fields when `paymentMethod` is `CARD` (or for card-related context):

| Field            | Type   | Notes                                                  |
| ---------------- | ------ | ------------------------------------------------------ |
| `cardholderName` | string | Name on card                                           |
| `cardLast4`      | string | Last 4 digits (4 chars)                                |
| `cardBrand`      | string | e.g. `Visa`, `Mastercard`, `Amex`, `Discover`, `Other` |
| `cardType`       | string | `credit`, `debit`, `prepaid`                           |
| `expiryMonth`    | string | MM (01-12)                                             |
| `expiryYear`     | string | YYYY                                                   |
| `bankName`       | string | Issuer bank                                            |
| `bankCode`       | string | Bank code                                              |
| `accountType`    | string | `personal`, `business`, `merchant`                     |
| `issuerCountry`  | string | ISO 2-letter country                                   |
| `bin`            | string | First 6 digits (BIN)                                   |
| `timestamp`      | string | When the payment occurred                              |
| `transactionId`  | string | Your transaction reference                             |
| `reference`      | string | Additional reference                                   |
| `country`        | string | ISO 2-letter                                           |

***

## PIX (Brasil)

Suggested fields for PIX:

| Field                  | Type   | Notes                                        |
| ---------------------- | ------ | -------------------------------------------- |
| `pixKey`               | string | PIX key (email, phone, CPF, CNPJ, or random) |
| `pixType`              | string | `email`, `phone`, `cpf`, `cnpj`, `random`    |
| `bankName`             | string | Bank name                                    |
| `bankCode`             | string | Bank code                                    |
| `endToEndId`           | string | PIX end-to-end ID                            |
| `returnIdentification` | string | Return identification                        |
| `timestamp`            | string |                                              |
| `transactionId`        | string |                                              |
| `reference`            | string |                                              |
| `country`              | string | ISO 2-letter                                 |

***

## Bank Transfer (ACH, Wire, SEPA, TED)

Generic bank transfer suggested fields:

| Field           | Type   | Notes                                 |
| --------------- | ------ | ------------------------------------- |
| `accountNumber` | string | Account number                        |
| `routingNumber` | string | US routing number                     |
| `swiftCode`     | string | SWIFT/BIC                             |
| `iban`          | string | IBAN                                  |
| `bankName`      | string | Bank name                             |
| `bankCode`      | string | Bank code                             |
| `accountType`   | string | `checking`, `savings`, `business`     |
| `transferType`  | string | `wire`, `ach`, `sepa`, `ted`, `other` |
| `timestamp`     | string |                                       |
| `transactionId` | string |                                       |
| `reference`     | string |                                       |
| `country`       | string | ISO 2-letter                          |

***

## CBU / CVU (Argentina)

Suggested fields for Argentine CBU/CVU:

| Field           | Type   | Notes                             |
| --------------- | ------ | --------------------------------- |
| `cbu`           | string | CBU (22 digits)                   |
| `cvu`           | string | CVU (22 digits)                   |
| `alias`         | string | Alias                             |
| `bankName`      | string | Bank name                         |
| `bankCode`      | string | Bank code                         |
| `accountType`   | string | `caja_ahorro`, `cuenta_corriente` |
| `timestamp`     | string |                                   |
| `transactionId` | string |                                   |
| `reference`     | string |                                   |
| `country`       | string | ISO 2-letter                      |

***

## SPEI (México)

Suggested fields for SPEI:

| Field           | Type   | Notes             |
| --------------- | ------ | ----------------- |
| `clabe`         | string | CLABE (18 digits) |
| `bankName`      | string | Bank name         |
| `bankCode`      | string | Bank code         |
| `trackingKey`   | string | Tracking key      |
| `timestamp`     | string |                   |
| `transactionId` | string |                   |
| `reference`     | string |                   |
| `country`       | string | ISO 2-letter      |

***

## PSE (Colombia)

Suggested fields for PSE:

| Field                  | Type   | Notes                     |
| ---------------------- | ------ | ------------------------- |
| `bankName`             | string | Bank name                 |
| `bankCode`             | string | Bank code                 |
| `transactionReference` | string | PSE transaction reference |
| `pseTransactionId`     | string | PSE transaction ID        |
| `timestamp`            | string |                           |
| `transactionId`        | string |                           |
| `reference`            | string |                           |
| `country`              | string | ISO 2-letter              |

***

## DEBIN (Argentina)

Suggested fields for DEBIN:

| Field           | Type   | Notes           |
| --------------- | ------ | --------------- |
| `debinId`       | string | DEBIN ID        |
| `bankName`      | string | Bank name       |
| `bankCode`      | string | Bank code       |
| `cbu`           | string | CBU (22 digits) |
| `timestamp`     | string |                 |
| `transactionId` | string |                 |
| `reference`     | string |                 |
| `country`       | string | ISO 2-letter    |

***

## Cryptocurrency

Suggested fields for crypto payments:

| Field           | Type   | Notes                                                        |
| --------------- | ------ | ------------------------------------------------------------ |
| `walletAddress` | string | Wallet address                                               |
| `cryptoType`    | string | `bitcoin`, `ethereum`, `usdt`, `usdc`, `stablecoin`, `other` |
| `network`       | string | Blockchain network                                           |
| `txHash`        | string | Transaction hash                                             |
| `confirmations` | number | Number of confirmations                                      |
| `gasFee`        | string | Gas fee                                                      |
| `timestamp`     | string |                                                              |
| `transactionId` | string |                                                              |
| `reference`     | string |                                                              |
| `country`       | string | ISO 2-letter                                                 |

***

## Cash

Suggested fields for cash:

| Field           | Type   | Notes                      |
| --------------- | ------ | -------------------------- |
| `location`      | string | Where the payment was made |
| `receiptNumber` | string | Receipt number             |
| `cashierName`   | string | Cashier name               |
| `timestamp`     | string |                            |
| `transactionId` | string |                            |
| `reference`     | string |                            |
| `country`       | string | ISO 2-letter               |

***

## Check

Suggested fields for check payments:

| Field           | Type   | Notes          |
| --------------- | ------ | -------------- |
| `checkNumber`   | string | Check number   |
| `bankName`      | string | Bank name      |
| `routingNumber` | string | Routing number |
| `accountNumber` | string | Account number |
| `timestamp`     | string |                |
| `transactionId` | string |                |
| `reference`     | string |                |
| `country`       | string | ISO 2-letter   |

***

## Money Order

Suggested fields:

| Field              | Type   | Notes              |
| ------------------ | ------ | ------------------ |
| `moneyOrderNumber` | string | Money order number |
| `issuer`           | string | Issuer             |
| `timestamp`        | string |                    |
| `transactionId`    | string |                    |
| `reference`        | string |                    |

***

## E-Wallet / Digital Wallet

Suggested fields for wallets (PayPal, Mercado Pago, etc.):

| Field            | Type   | Notes                            |
| ---------------- | ------ | -------------------------------- |
| `walletProvider` | string | e.g. PayPal, Venmo, Mercado Pago |
| `walletId`       | string | Wallet identifier                |
| `accountEmail`   | string | Email linked to wallet           |
| `accountPhone`   | string | Phone linked to wallet           |
| `walletType`     | string | `digital`, `mobile`, `crypto`    |
| `timestamp`      | string |                                  |
| `transactionId`  | string |                                  |
| `reference`      | string |                                  |
| `country`        | string | ISO 2-letter                     |

***

## Other / Generic

For any other method you can send:

| Field           | Type   | Notes        |
| --------------- | ------ | ------------ |
| `timestamp`     | string |              |
| `transactionId` | string |              |
| `reference`     | string |              |
| `country`       | string | ISO 2-letter |

Plus any custom keys you need.

***

## Examples

**Origin with card paymentDetails:**

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

**Destination with PIX paymentDetails:**

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

**Mixing suggested + custom fields:**

```json theme={null}
{
  "originDetails": {
    "paymentDetails": {
      "cardLast4": "1234",
      "cardBrand": "Mastercard",
      "myCustomField": "any value",
      "internalRef": "ABC-999"
    }
  }
}
```

All of the above are accepted. The API does not restrict keys inside `paymentDetails`.

***

## See Also

* [Create Transaction](/en/api-reference/transactions/create) — `originDetails` and `destinationDetails`
* [Transaction Reason Enum](/en/api-reference/transactions/reason-enum) — Optional `reason` field