Schema Payment Details

Resumen

Puedes enviar un objeto paymentDetails dentro de originDetails y/o 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). 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:

{
  "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:

{
  "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 — originDetails y destinationDetails
Enum Razón de Transacción — Campo opcional reason

​Resumen

​Parte desconocida (visualización en grafos)

​Tarjeta (CARD)

​PIX (Brasil)

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

​CBU / CVU (Argentina)

​SPEI (México)

​PSE (Colombia)

​DEBIN (Argentina)

​Criptomonedas

​Efectivo

​Cheque

​E-Wallet / billetera digital

​Otro / genérico

​Ejemplos

​Ver también