# 模型 (/zh/docs/cartao/endpoints/models) {/* Gerado por scripts/generate-models.mjs a partir dos specs OpenAPI. Não edite manualmente. */} 下面的模型描述了各端点接受和返回的对象。字段名区分大小写,金额始终以分为单位。 ## Address [#address] Billing address | 字段 | 类型 | 必填 | 说明 | | ------------ | ------ | -- | --------------------------- | | `street` | string | 是 | Billing address street | | `number` | string | 是 | Billing address number | | `complement` | string | 否 | Billing address complement | | `zipCode` | string | 是 | Billing address postal code | | `city` | string | 是 | Billing address city | | `state` | string | 是 | Billing address state | | `country` | string | 是 | Billing address country | | `district` | string | 是 | Billing address district | ## CustomerRequest [#customerrequest] Buyer data | 字段 | 类型 | 必填 | 说明 | | -------------- | ------------------- | -- | -------------------------------------- | | `name` | string | 是 | Buyer's full name | | `identity` | string | 否 | Buyer's identification document number | | `identityType` | string | 否 | Buyer's identification document type | | `email` | string | 否 | Buyer's email | | `birthdate` | string | 否 | Buyer's birthdate | | `phone` | string | 否 | Buyer's phone number | | `address` | [Address](#address) | 否 | | ## CustomerResponse [#customerresponse] Buyer data | 字段 | 类型 | 必填 | 说明 | | -------------- | ------ | -- | -------------------------------------- | | `id` | number | 否 | Internal buyer identifier | | `name` | string | 否 | Buyer's full name | | `identity` | string | 否 | Buyer's identification document number | | `identityType` | string | 否 | Buyer's identification document type | | `email` | string | 否 | Buyer's email | | `birthdate` | string | 否 | Buyer's birthdate | | `phone` | string | 否 | Buyer's phone number | | `address` | object | 否 | Billing address | ## CartItem [#cartitem] | 字段 | 类型 | 必填 | 说明 | | ----------- | ------ | -- | -------------------------------- | | `name` | string | 是 | Product name | | `quantity` | number | 是 | Product quantity | | `sku` | string | 是 | Product SKU (Stock Keeping Unit) | | `unitPrice` | number | 是 | Product unit price in cents | ## CardRequest [#cardrequest] Card details | 字段 | 类型 | 必填 | 说明 | | ------------ | ------ | -- | --------------------------------------------- | | `number` | string | 是 | Credit card number | | `holder` | string | 是 | Cardholder name as printed on the credit card | | `expiration` | string | 是 | Credit card expiration date | | `cvv` | string | 是 | Security code on the back of the credit card | ## CardResponse [#cardresponse] Details of the card used in the charge | 字段 | 类型 | 必填 | 说明 | | ------------ | ------ | -- | ---------------------------------------------------------------------------------------------------------------------------------- | | `id` | number | 否 | Internal card identifier | | `number` | string | 否 | Credit card number | | `holder` | string | 否 | Cardholder name as printed on the credit card | | `expiration` | string | 否 | Credit card expiration date | | `brand` | string | 否 | Card brand. See [Brand](https://docs.payzu.com.br/docs/cartao/reference-codes). 取值: `Visa`, `Master`, `Elo`, `Diners`, `Hipercard` | ## ExternalAuthentication [#externalauthentication] 3DS authentication data performed outside PayZu (external authentication) | 字段 | 类型 | 必填 | 说明 | | ------------- | ------ | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `cavv` | string | 是 | Signature returned on successful authentication scenarios | | `xid` | string | 否 | XID returned in the authentication process | | `eci` | string | 是 | 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 | 是 | 3DS version applied in the authentication process | | `referenceId` | string | 是 | 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) | 字段 | 类型 | 必填 | 说明 | | --------------- | --------- | -- | ---------------------------------------------------------------------------------------- | | `fingerPrintId` | string | 是 | Identifier used to correlate information collected from the buyer's device | | `browser` | object | 是 | Information about the buyer's browser | | `definedFields` | object\[] | 是 | Merchant Defined Data (MDD). See [MDD table](https://docs.payzu.com.br/docs/cartao/mdds) | ## Chargeback [#chargeback] | 字段 | 类型 | 必填 | 说明 | | ------------------- | ------ | -- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | number | 否 | Chargeback identifier | | `number` | string | 否 | Chargeback number at the acquirer | | `amount` | number | 否 | Chargeback amount in cents | | `status` | string | 否 | Chargeback status. See [Chargeback status list](https://docs.payzu.com.br/docs/cartao/transaction-status). 取值: `RECEIVED`, `ACCEPTED`, `DEFENDED` | | `reasonCode` | string | 否 | Reason code provided by the card brand | | `reasonDescription` | string | 否 | Reason description provided by the card brand | | `issuedAt` | string | 否 | Chargeback issue date | | `createdAt` | string | 否 | Record creation date | | `updatedAt` | string | 否 | Date the record was last updated | ## CreditCardPaymentResponse [#creditcardpaymentresponse] Credit card payment details | 字段 | 类型 | 必填 | 说明 | | ------------------------ | ----------------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `installments` | number | 否 | Number of installments | | `authenticate` | boolean | 否 | Indicates whether the buyer was redirected to the issuer for 3DS authentication | | `currency` | string | 否 | Charge currency. See [Supported currencies](https://docs.payzu.com.br/docs/cartao/currencies) | | `acquirerTransactionId` | string | 否 | Transaction identifier at the acquirer | | `authorizationCode` | string | 否 | Authorization code returned by the acquirer | | `reasonCode` | number | 否 | Reason code of the result. See [Transaction status and reasons](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `reasonMessage` | string | 否 | Reason message of the result. See [Transaction status and reasons](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `status` | integer | 否 | Transaction status. See [Transaction status list](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `returnCode` | string | 否 | 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 | 否 | Return message from the acquirer | | `externalAuthentication` | object | 否 | External 3DS authentication data, when sent at creation | | `reversedAmount` | number | 否 | Reversed amount in cents, when a reversal exists | | `reversedDate` | string | 否 | Reversal date, when present | | `chargeId` | string | 否 | Charge identifier | | `card` | [CardResponse](#cardresponse) | 否 | | | `chargebacks` | [Chargeback](#chargeback)\[] | 否 | 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) | 字段 | 类型 | 必填 | 说明 | | ---------- | ------ | -- | ---------------------------------------------------------------------------------------- | | `interval` | string | 是 | Interval between charges: `Monthly` or `Annual`. 取值: `Monthly`, `Annual` | | `endDate` | string | 否 | Recurrence end date in `YYYY-MM-DD` format. Without it, the recurrence runs indefinitely | ## Recurrence [#recurrence] State of a recurrence | 字段 | 类型 | 必填 | 说明 | | -------------------- | ------ | -- | -------------------------------------------------------------------------------------------------------------------------------- | | `recurrentPaymentId` | string | 否 | Recurrence identifier. Use it on the recurrence query and management endpoints | | `interval` | string | 否 | Configured interval. 取值: `MONTHLY`, `ANNUAL` | | `status` | string | 否 | Recurrence status. See [Recurring payments](https://docs.payzu.com.br/docs/cartao/recurrence). 取值: `ACTIVE`, `INACTIVE`, `ENDED` | | `amount` | number | 否 | Amount of each cycle, in cents | | `nextRecurrency` | string | 否 | Date of the next automatic charge | | `endDate` | string | 否 | End date, if provided at creation | ## Charge [#charge] | 字段 | 类型 | 必填 | 说明 | | ------------------- | ------------------------------------------------------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | 否 | Charge identifier | | `externalId` | string | 否 | Unique identifier generated externally | | `postbackUrl` | string | 否 | Url for notifications about the charge status | | `amount` | number | 否 | Charge amount in cents | | `paymentType` | string | 否 | Charge payment type. See [Payment types](https://docs.payzu.com.br/docs/cartao/reference-codes) | | `createdAt` | string | 否 | Charge creation date | | `updatedAt` | string | 否 | Date the charge was last updated | | `customer` | [CustomerResponse](#customerresponse) | 否 | | | `cart` | [CartItem](#cartitem)\[] | 否 | Buyer's cart | | `creditCardPayment` | [CreditCardPaymentResponse](#creditcardpaymentresponse) | 否 | | | `recurrence` | [Recurrence](#recurrence) | 否 | Present when the charge belongs to a recurrence | | `recurrenceCycle` | integer | 否 | 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] | 字段 | 类型 | 必填 | 说明 | | ------------------- | --------------------------------------- | -- | ----------------------------------------------------------------------------------------------------------------- | | `amount` | number | 是 | Charge amount in cents | | `customer` | [CustomerRequest](#customerrequest) | 是 | | | `postbackUrl` | string | 否 | Url for notifications about the charge status. See [Webhooks](https://docs.payzu.com.br/docs/cartao/webhooks) | | `paymentType` | string | 是 | Charge payment type. See [Payment types](https://docs.payzu.com.br/docs/cartao/reference-codes). 取值: `creditcard` | | `cart` | [CartItem](#cartitem)\[] | 是 | Buyer's cart | | `creditCardPayment` | object | 是 | Settings for the payment type: credit card | | `recurrence` | [RecurrenceRequest](#recurrencerequest) | 否 | | | `externalId` | string | 是 | Unique identifier generated externally | ## CurrencyRate [#currencyrate] | 字段 | 类型 | 必填 | 说明 | | ------ | ------ | -- | -- | | `code` | string | 是 | | | `rate` | object | 是 | | ## CurrencyConvertResponse [#currencyconvertresponse] | 字段 | 类型 | 必填 | 说明 | | ---------- | ------ | -- | --------------------------------------------------------------- | | `amount` | number | 是 | Converted amount in the target currency, rounded to 2 decimals. | | `currency` | object | 是 | |