Schema Payment Details

Resumo

Você pode enviar um objeto paymentDetails dentro de originDetails e/ou destinationDetails ao criar uma transação. Esta página descreve estruturas sugeridas por método de pagamento. Nada é exigido: a API aceita qualquer formato e campos extras; use apenas como referência.

Onde: originDetails.paymentDetails, destinationDetails.paymentDetails
Opcional: Sim. Omita se não precisar de detalhes de pagamento.
Campos custom: Qualquer chave adicional é armazenada como está. Você não está restrito aos campos abaixo.

Parte desconhecida (visualização em grafos)

Quando a origem ou o destino não é uma entidade no gu1 (você não envia originEntityId/originExternalId ou destinationEntityId/destinationExternalId), pode enviar dados identificadores para que os grafos de rede mostrem um único nó “pseudo” por parte desconhecida. O grafo usa o primeiro identificador que corresponder (ordem de prioridade). Os valores são normalizados (apenas alfanuméricos) antes do agrupamento:

Prioridade	Campo	Tipo	Notas
1	`taxId`	string	Ex.: CPF, CNPJ. Mesmo valor normalizado = um nó.
2	`cbu`	string	CBU Argentina (22 dígitos).
3	`cvu`	string	CVU Argentina (22 dígitos).
4	`pixKey`	string	Chave PIX (Brasil).
5	`clabe`	string	CLABE (México).
6	`alias`	string	Alias de pagamento.
7	`iban`	string	IBAN.
8	`holderId`	string	Documento do titular quando não há `taxId`.
9	`debinId`	string	ID DEBIN (Argentina).
10	`cardFingerprint`	string	Token/impressão digital do cartão (mín. 8 caracteres). Preferir a `bin` ou `cardLast4` isolados.
11	`accountNumber`	string	Número de conta genérico; agrupado com `bankCode` opcional. Também aparece inline na tabela de transações quando CBU/CVU/etc. estão ausentes.
—	`bankCode`	string	Modificador opcional para agrupar `accountNumber` e exibir inline na tabela.

Não usados para agrupar nós pseudo (ambíguos): bin, cardLast4 sozinhos. Para cartões sem entidade vinculada, envie cardFingerprint. Estes campos são opcionais e de uso interno (visualização em grafos). Não são obrigatórios para criar a transação. Vínculo com entidade vs só grafo: para vincular pessoa/empresa (terceiro critério e enriquecimento de nome/país), use originTaxId / destinationTaxId no raiz do corpo; ver Criar transação (origem). Só taxId em *Details não faz o match; só ajuda a agrupar no grafo.

Cartão (CARD)

Campos sugeridos quando paymentMethod é CARD:

Campo	Tipo	Notas
`cardholderName`	string	Nome no cartão
`cardLast4`	string	Últimos 4 dígitos (4 caracteres)
`cardBrand`	string	ex.: `Visa`, `Mastercard`, `Amex`, `Discover`, `Other`
`cardType`	string	`credit`, `debit`, `prepaid`
`expiryMonth`	string	MM (01-12)
`expiryYear`	string	YYYY
`bankName`	string	Banco emissor
`bankCode`	string	Código do banco
`accountType`	string	`personal`, `business`, `merchant`
`issuerCountry`	string	País emissor (ISO 2 letras)
`bin`	string	Primeiros 6 dígitos (BIN)
`timestamp`	string	Quando o pagamento ocorreu
`transactionId`	string	Sua referência de transação
`reference`	string	Referência adicional
`country`	string	ISO 2 letras

PIX (Brasil)

Campos sugeridos para PIX:

Campo	Tipo	Notas
`pixKey`	string	Chave PIX (email, telefone, CPF, CNPJ ou aleatória)
`pixType`	string	`email`, `phone`, `cpf`, `cnpj`, `random`
`bankName`	string	Nome do banco
`bankCode`	string	Código do banco
`endToEndId`	string	ID end-to-end PIX
`returnIdentification`	string	Identificação de retorno
`timestamp`	string
`transactionId`	string
`reference`	string
`country`	string	ISO 2 letras

Transferência bancária (ACH, wire, SEPA, TED)

Campos sugeridos genéricos:

Campo	Tipo	Notas
`accountNumber`	string	Número da conta
`routingNumber`	string	Routing number (EUA)
`swiftCode`	string	SWIFT/BIC
`iban`	string	IBAN
`bankName`	string	Nome do banco
`bankCode`	string	Código do 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	Nome do banco
`bankCode`	string	Código do 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 (Colômbia)

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.

Criptomoedas

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

Dinheiro

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

Cheque

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

E-Wallet / carteira digital

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

Outro / genérico

Para qualquer outro método: timestamp, transactionId, reference, country e qualquer chave custom que precisar.

Exemplos

Origem com paymentDetails de cartão:

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

Destino com paymentDetails PIX:

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

Campos sugeridos + custom: Você pode misturar qualquer campo acima com chaves próprias; a API não restringe as chaves dentro de paymentDetails.

Ver também

Referência API Criar Transação — originDetails e destinationDetails
Enum Motivo da Transação — Campo opcional reason

​Resumo

​Parte desconhecida (visualização em grafos)

​Cartão (CARD)

​PIX (Brasil)

​Transferência bancária (ACH, wire, SEPA, TED)

​CBU / CVU (Argentina)

​SPEI (México)

​PSE (Colômbia)

​DEBIN (Argentina)

​Criptomoedas

​Dinheiro

​Cheque

​E-Wallet / carteira digital

​Outro / genérico

​Exemplos

​Ver também