Payment Details Schema

Overview

You can send a paymentDetails object inside originDetails and/or 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). 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:

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

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

Mixing suggested + custom fields:

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

​Overview

​Unknown Party (Graph Visualization)

​Card (CARD)

​PIX (Brasil)

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

​CBU / CVU (Argentina)

​SPEI (México)

​PSE (Colombia)

​DEBIN (Argentina)

​Cryptocurrency

​Cash

​Check

​Money Order

​E-Wallet / Digital Wallet

​Other / Generic

​Examples

​See Also