# Models (/en/docs/cartao/endpoints/models) {/* Gerado por scripts/generate-models.mjs a partir dos specs OpenAPI. Não edite manualmente. */} The models below describe the objects accepted and returned by the endpoints. Field names are case sensitive and monetary values are always in cents. ## Address [#address] Billing address | Field | Type | Required | Description | | ------------ | ------ | -------- | --------------------------- | | `street` | string | Yes | Billing address street | | `number` | string | Yes | Billing address number | | `complement` | string | No | Billing address complement | | `zipCode` | string | Yes | Billing address postal code | | `city` | string | Yes | Billing address city | | `state` | string | Yes | Billing address state | | `country` | string | Yes | Billing address country | | `district` | string | Yes | Billing address district | ## CustomerRequest [#customerrequest] Buyer data | Field | Type | Required | Description | | -------------- | ------------------- | -------- | -------------------------------------- | | `name` | string | Yes | Buyer's full name | | `identity` | string | No | Buyer's identification document number | | `identityType` | string | No | Buyer's identification document type | | `email` | string | No | Buyer's email | | `birthdate` | string | No | Buyer's birthdate | | `phone` | string | No | Buyer's phone number | | `address` | [Address](#address) | No | | ## CustomerResponse [#customerresponse] Buyer data | Field | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------- | | `id` | number | No | Internal buyer identifier | | `name` | string | No | Buyer's full name | | `identity` | string | No | Buyer's identification document number | | `identityType` | string | No | Buyer's identification document type | | `email` | string | No | Buyer's email | | `birthdate` | string | No | Buyer's birthdate | | `phone` | string | No | Buyer's phone number | | `address` | object | No | Billing address | ## CartItem [#cartitem] | Field | Type | Required | Description | | ----------- | ------ | -------- | -------------------------------- | | `name` | string | Yes | Product name | | `quantity` | number | Yes | Product quantity | | `sku` | string | Yes | Product SKU (Stock Keeping Unit) | | `unitPrice` | number | Yes | Product unit price in cents | ## CardRequest [#cardrequest] Card details | Field | Type | Required | Description | | ------------ | ------ | -------- | --------------------------------------------- | | `number` | string | Yes | Credit card number | | `holder` | string | Yes | Cardholder name as printed on the credit card | | `expiration` | string | Yes | Credit card expiration date | | `cvv` | string | Yes | Security code on the back of the credit card | ## CardResponse [#cardresponse] Details of the card used in the charge | Field | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `id` | number | No | Internal card identifier | | `number` | string | No | Credit card number | | `holder` | string | No | Cardholder name as printed on the credit card | | `expiration` | string | No | Credit card expiration date | | `brand` | string | No | Card brand. See [Brand](https://docs.payzu.com.br/docs/cartao/reference-codes). Values: `Visa`, `Master`, `Elo`, `Diners`, `Hipercard` | ## ExternalAuthentication [#externalauthentication] 3DS authentication data performed outside PayZu (external authentication) | Field | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `cavv` | string | Yes | Signature returned on successful authentication scenarios | | `xid` | string | No | XID returned in the authentication process | | `eci` | string | Yes | Electronic Commerce Indicator returned in the authentication process. See [ECI table](https://docs.payzu.com.br/docs/cartao/three-d-secure#tabela-eci) | | `version` | string | Yes | 3DS version applied in the authentication process | | `referenceId` | string | Yes | RequestID returned in the authentication process | ## FraudAnalysis [#fraudanalysis] Data for the antifraud engine. Required on international charges. See [Using Antifraud](https://docs.payzu.com.br/docs/cartao/antifraud) | Field | Type | Required | Description | | --------------- | --------- | -------- | ---------------------------------------------------------------------------------------- | | `fingerPrintId` | string | Yes | Identifier used to correlate information collected from the buyer's device | | `browser` | object | Yes | Information about the buyer's browser | | `definedFields` | object\[] | Yes | Merchant Defined Data (MDD). See [MDD table](https://docs.payzu.com.br/docs/cartao/mdds) | ## Chargeback [#chargeback] | Field | Type | Required | Description | | ------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | number | No | Chargeback identifier | | `number` | string | No | Chargeback number at the acquirer | | `amount` | number | No | Chargeback amount in cents | | `status` | string | No | Chargeback status. See [Chargeback status list](https://docs.payzu.com.br/docs/cartao/transaction-status). Values: `RECEIVED`, `ACCEPTED`, `DEFENDED` | | `reasonCode` | string | No | Reason code provided by the card brand | | `reasonDescription` | string | No | Reason description provided by the card brand | | `issuedAt` | string | No | Chargeback issue date | | `createdAt` | string | No | Record creation date | | `updatedAt` | string | No | Date the record was last updated | ## CreditCardPaymentResponse [#creditcardpaymentresponse] Credit card payment details | Field | Type | Required | Description | | ------------------------ | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `installments` | number | No | Number of installments | | `authenticate` | boolean | No | Indicates whether the buyer was redirected to the issuer for 3DS authentication | | `currency` | string | No | Charge currency. See [Supported currencies](https://docs.payzu.com.br/docs/cartao/currencies) | | `acquirerTransactionId` | string | No | Transaction identifier at the acquirer | | `authorizationCode` | string | No | Authorization code returned by the acquirer | | `reasonCode` | number | No | Reason code of the result. See [Transaction status and reasons](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `reasonMessage` | string | No | Reason message of the result. See [Transaction status and reasons](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `status` | integer | No | Transaction status. See [Transaction status list](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `returnCode` | string | No | Return code from the acquirer. See [Error Codes](https://docs.payzu.com.br/docs/cartao/error-codes) and [ABECS return codes](https://docs.payzu.com.br/docs/cartao/abecs-codes) | | `returnMessage` | string | No | Return message from the acquirer | | `externalAuthentication` | object | No | External 3DS authentication data, when sent at creation | | `reversedAmount` | number | No | Reversed amount in cents, when a reversal exists | | `reversedDate` | string | No | Reversal date, when present | | `chargeId` | string | No | Charge identifier | | `card` | [CardResponse](#cardresponse) | No | | | `chargebacks` | [Chargeback](#chargeback)\[] | No | Chargebacks linked to the charge | ## RecurrenceRequest [#recurrencerequest] Recurring payment configuration. The first charge is created immediately; the following cycles are generated automatically. Requires `installments` equal to 1. See [Recurring payments](https://docs.payzu.com.br/docs/cartao/recurrence) | Field | Type | Required | Description | | ---------- | ------ | -------- | ---------------------------------------------------------------------------------------- | | `interval` | string | Yes | Interval between charges: `Monthly` or `Annual`. Values: `Monthly`, `Annual` | | `endDate` | string | No | Recurrence end date in `YYYY-MM-DD` format. Without it, the recurrence runs indefinitely | ## Recurrence [#recurrence] State of a recurrence | Field | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `recurrentPaymentId` | string | No | Recurrence identifier. Use it on the recurrence query and management endpoints | | `interval` | string | No | Configured interval. Values: `MONTHLY`, `ANNUAL` | | `status` | string | No | Recurrence status. See [Recurring payments](https://docs.payzu.com.br/docs/cartao/recurrence). Values: `ACTIVE`, `INACTIVE`, `ENDED` | | `amount` | number | No | Amount of each cycle, in cents | | `nextRecurrency` | string | No | Date of the next automatic charge | | `endDate` | string | No | End date, if provided at creation | ## Charge [#charge] | Field | Type | Required | Description | | ------------------- | ------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | No | Charge identifier | | `externalId` | string | No | Unique identifier generated externally | | `postbackUrl` | string | No | Url for notifications about the charge status | | `amount` | number | No | Charge amount in cents | | `paymentType` | string | No | Charge payment type. See [Payment types](https://docs.payzu.com.br/docs/cartao/reference-codes) | | `createdAt` | string | No | Charge creation date | | `updatedAt` | string | No | Date the charge was last updated | | `customer` | [CustomerResponse](#customerresponse) | No | | | `cart` | [CartItem](#cartitem)\[] | No | Buyer's cart | | `creditCardPayment` | [CreditCardPaymentResponse](#creditcardpaymentresponse) | No | | | `recurrence` | [Recurrence](#recurrence) | No | Present when the charge belongs to a recurrence | | `recurrenceCycle` | integer | No | Cycle number of the recurrence this charge belongs to: 0 is the initial charge, 1..n are the automatically generated cycles. Present only on recurrence charges | ## ChargeRequest [#chargerequest] | Field | Type | Required | Description | | ------------------- | --------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | `amount` | number | Yes | Charge amount in cents | | `customer` | [CustomerRequest](#customerrequest) | Yes | | | `postbackUrl` | string | No | Url for notifications about the charge status. See [Webhooks](https://docs.payzu.com.br/docs/cartao/webhooks) | | `paymentType` | string | Yes | Charge payment type. See [Payment types](https://docs.payzu.com.br/docs/cartao/reference-codes). Values: `creditcard` | | `cart` | [CartItem](#cartitem)\[] | Yes | Buyer's cart | | `creditCardPayment` | object | Yes | Settings for the payment type: credit card | | `recurrence` | [RecurrenceRequest](#recurrencerequest) | No | | | `externalId` | string | Yes | Unique identifier generated externally | ## CurrencyRate [#currencyrate] | Field | Type | Required | Description | | ------ | ------ | -------- | ----------- | | `code` | string | Yes | | | `rate` | object | Yes | | ## CurrencyConvertResponse [#currencyconvertresponse] | Field | Type | Required | Description | | ---------- | ------ | -------- | --------------------------------------------------------------- | | `amount` | number | Yes | Converted amount in the target currency, rounded to 2 decimals. | | `currency` | object | Yes | |