Skip to main content

​
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:
PrioridadCampoTipoNotas
1taxIdstringEj. CPF, CNPJ, CUIT. Mismo valor normalizado = un nodo.
2cbustringCBU Argentina (22 dígitos). Recomendado si la contraparte se identifica por CBU.
3cvustringCVU Argentina (22 dígitos).
4pixKeystringClave PIX (Brasil).
5clabestringCLABE (México).
6aliasstringAlias de pago (ej. alias CVU).
7ibanstringIBAN.
8holderIdstringDocumento del titular cuando no hay taxId.
9debinIdstringID DEBIN (Argentina).
10cardFingerprintstringToken/huella de tarjeta (mín. 8 caracteres). Preferir sobre bin o cardLast4 solos.
11accountNumberstringNú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.
—bankCodestringModificador 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:
CampoTipoNotas
cardholderNamestringNombre en la tarjeta
cardLast4stringÚltimos 4 dígitos (4 caracteres)
cardBrandstringej. Visa, Mastercard, Amex, Discover, Other
cardTypestringcredit, debit, prepaid
expiryMonthstringMM (01-12)
expiryYearstringYYYY
bankNamestringBanco emisor
bankCodestringCódigo banco
accountTypestringpersonal, business, merchant
issuerCountrystringPaís emisor (ISO 2 letras)
binstringPrimeros 6 dígitos (BIN)
timestampstringCuándo ocurrió el pago
transactionIdstringTu referencia de transacción
referencestringReferencia adicional
countrystringISO 2 letras

​
PIX (Brasil)

Campos sugeridos para PIX:
CampoTipoNotas
pixKeystringClave PIX (email, teléfono, CPF, CNPJ o aleatoria)
pixTypestringemail, phone, cpf, cnpj, random
bankNamestringNombre del banco
bankCodestringCódigo del banco
endToEndIdstringID end-to-end PIX
returnIdentificationstringIdentificación de retorno
timestampstring
transactionIdstring
referencestring
countrystringISO 2 letras

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

Campos sugeridos genéricos:
CampoTipoNotas
accountNumberstringNúmero de cuenta
routingNumberstringRouting number (EE.UU.)
swiftCodestringSWIFT/BIC
ibanstringIBAN
bankNamestringNombre del banco
bankCodestringCódigo del banco
accountTypestringchecking, savings, business
transferTypestringwire, ach, sepa, ted, other
timestampstring
transactionIdstring
referencestring
countrystringISO 2 letras

​
CBU / CVU (Argentina)

Campos sugeridos para CBU/CVU:
CampoTipoNotas
cbustringCBU (22 dígitos)
cvustringCVU (22 dígitos)
aliasstringAlias
bankNamestringNombre del banco
bankCodestringCódigo del banco
accountTypestringcaja_ahorro, cuenta_corriente
timestampstring
transactionIdstring
referencestring
countrystringISO 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