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:

Campo	Tipo	Notas
`taxId`	string	Ej. CPF, CNPJ. Se usa para agrupar la misma parte en varias transacciones; mismo taxId = un nodo en el grafo.
`accountNumber`	string	Número de cuenta. Se usa si no hay taxId; se agrupa con `bankCode` opcional.
`bankCode`	string	Opcional; mejora la agrupación con `accountNumber`.

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

Documentation Index

​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