# Modelos (/docs/cartao/endpoints/models) {/* Gerado por scripts/generate-models.mjs a partir dos specs OpenAPI. Não edite manualmente. */} Os modelos abaixo descrevem os objetos aceitos e retornados pelos endpoints. Os nomes de campo diferenciam maiúsculas de minúsculas e os valores monetários são sempre em centavos. ## Address [#address] Endereço de cobrança | Campo | Tipo | Obrigatório | Descrição | | ------------ | ------ | ----------- | ------------------------------------- | | `street` | string | Sim | Logradouro do endereço de cobrança | | `number` | string | Sim | Número do endereço de cobrança | | `complement` | string | Não | Complemento do endereço de cobrança | | `zipCode` | string | Sim | Código postal do endereço de cobrança | | `city` | string | Sim | Cidade do endereço de cobrança | | `state` | string | Sim | Estado do endereço de cobrança | | `country` | string | Sim | País do endereço de cobrança | | `district` | string | Sim | Bairro do endereço de cobrança | ## CustomerRequest [#customerrequest] Dados do comprador | Campo | Tipo | Obrigatório | Descrição | | -------------- | ------------------- | ----------- | ------------------------------------------------- | | `name` | string | Sim | Nome completo do comprador | | `identity` | string | Não | Número do documento de identificação do comprador | | `identityType` | string | Não | Tipo de documento de identificação do comprador | | `email` | string | Não | E-mail do comprador | | `birthdate` | string | Não | Data de nascimento do comprador | | `phone` | string | Não | Número do telefone do comprador | | `address` | [Address](#address) | Não | | ## CustomerResponse [#customerresponse] Dados do comprador | Campo | Tipo | Obrigatório | Descrição | | -------------- | ------ | ----------- | ------------------------------------------------- | | `id` | number | Não | Identificador interno do comprador | | `name` | string | Não | Nome completo do comprador | | `identity` | string | Não | Número do documento de identificação do comprador | | `identityType` | string | Não | Tipo de documento de identificação do comprador | | `email` | string | Não | E-mail do comprador | | `birthdate` | string | Não | Data de nascimento do comprador | | `phone` | string | Não | Número do telefone do comprador | | `address` | object | Não | Endereço de cobrança | ## CartItem [#cartitem] | Campo | Tipo | Obrigatório | Descrição | | ----------- | ------ | ----------- | -------------------------------------------------------------------- | | `name` | string | Sim | Nome do produto | | `quantity` | number | Sim | Quantidade do produto | | `sku` | string | Sim | SKU (Stock Keeping Unit - Unidade de Controle de Estoque) do produto | | `unitPrice` | number | Sim | Preço unitário do produto em centavos | ## CardRequest [#cardrequest] Detalhes do cartão | Campo | Tipo | Obrigatório | Descrição | | ------------ | ------ | ----------- | ------------------------------------------------- | | `number` | string | Sim | Número do cartão de crédito | | `holder` | string | Sim | Nome do portador impresso no cartão de crédito | | `expiration` | string | Sim | Data de validade do cartão de crédito | | `cvv` | string | Sim | Código de segurança no verso do cartão de crédito | ## CardResponse [#cardresponse] Detalhes do cartão utilizado na cobrança | Campo | Tipo | Obrigatório | Descrição | | ------------ | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | number | Não | Identificador interno do cartão | | `number` | string | Não | Número do cartão de crédito | | `holder` | string | Não | Nome do portador impresso no cartão de crédito | | `expiration` | string | Não | Data de validade do cartão de crédito | | `brand` | string | Não | Bandeira do cartão. Veja [Brand](https://docs.payzu.com.br/docs/cartao/reference-codes). Valores: `Visa`, `Master`, `Elo`, `Diners`, `Hipercard` | ## ExternalAuthentication [#externalauthentication] Dados de autenticação 3DS realizada fora da PayZu (autenticação externa) | Campo | Tipo | Obrigatório | Descrição | | ------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `cavv` | string | Sim | Assinatura retornada nos cenários de sucesso na autenticação | | `xid` | string | Não | XID retornado no processo de autenticação | | `eci` | string | Sim | Electronic Commerce Indicator retornado no processo de autenticação. Veja [Tabela ECI](https://docs.payzu.com.br/docs/cartao/three-d-secure) | | `version` | string | Sim | Versão do 3DS aplicado no processo de autenticação | | `referenceId` | string | Sim | RequestID retornado no processo de autenticação | ## FraudAnalysis [#fraudanalysis] Dados para o motor antifraude. Obrigatório em cobranças internacionais. Veja [Utilizando Antifraude](https://docs.payzu.com.br/docs/cartao/antifraud) | Campo | Tipo | Obrigatório | Descrição | | --------------- | --------- | ----------- | ---------------------------------------------------------------------------------------------- | | `fingerPrintId` | string | Sim | Identificador utilizado para cruzar informações obtidas do dispositivo do comprador | | `browser` | object | Sim | Informações sobre o navegador do comprador | | `definedFields` | object\[] | Sim | Merchant Defined Data (MDD). Veja [Tabela de MDDs](https://docs.payzu.com.br/docs/cartao/mdds) | ## Chargeback [#chargeback] | Campo | Tipo | Obrigatório | Descrição | | ------------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | number | Não | Identificador do chargeback | | `number` | string | Não | Número do chargeback junto à adquirente | | `amount` | number | Não | Valor do chargeback em centavos | | `status` | string | Não | Status do chargeback. Veja [Lista de status do Chargeback](https://docs.payzu.com.br/docs/cartao/transaction-status). Valores: `RECEIVED`, `ACCEPTED`, `DEFENDED` | | `reasonCode` | string | Não | Código do motivo informado pela bandeira | | `reasonDescription` | string | Não | Descrição do motivo informado pela bandeira | | `issuedAt` | string | Não | Data de emissão do chargeback | | `createdAt` | string | Não | Data de criação do registro | | `updatedAt` | string | Não | Data da última atualização do registro | ## CreditCardPaymentResponse [#creditcardpaymentresponse] Detalhes do pagamento com cartão de crédito | Campo | Tipo | Obrigatório | Descrição | | ------------------------ | ----------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `installments` | number | Não | Número de parcelas | | `authenticate` | boolean | Não | Indica se o comprador foi direcionado ao emissor para autenticação 3DS | | `currency` | string | Não | Moeda da cobrança. Veja [Moedas](https://docs.payzu.com.br/docs/cartao/currencies) | | `acquirerTransactionId` | string | Não | Identificador da transação na adquirente | | `authorizationCode` | string | Não | Código de autorização retornado pela adquirente | | `reasonCode` | number | Não | Código do motivo do resultado. Veja [Lista de ReasonCode/ReasonMessage](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `reasonMessage` | string | Não | Mensagem do motivo do resultado. Veja [Lista de ReasonCode/ReasonMessage](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `status` | integer | Não | Status da transação. Veja [Lista de status da Transação](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `returnCode` | string | Não | Código de retorno da adquirente. Veja [Códigos de Erros](https://docs.payzu.com.br/docs/cartao/error-codes) e [Código de retorno ABECS](https://docs.payzu.com.br/docs/cartao/abecs-codes) | | `returnMessage` | string | Não | Mensagem de retorno da adquirente | | `externalAuthentication` | object | Não | Dados da autenticação externa 3DS, quando enviados na criação | | `reversedAmount` | number | Não | Valor estornado em centavos, quando houver estorno | | `reversedDate` | string | Não | Data do estorno, quando houver | | `chargeId` | string | Não | Identificador da cobrança | | `card` | [CardResponse](#cardresponse) | Não | | | `chargebacks` | [Chargeback](#chargeback)\[] | Não | Chargebacks vinculados à cobrança | ## RecurrenceRequest [#recurrencerequest] Configuração de pagamento recorrente. A primeira cobrança é criada na hora; os ciclos seguintes são gerados automaticamente. Exige `installments` igual a 1. Veja [Pagamentos Recorrentes](https://docs.payzu.com.br/docs/cartao/recurrence) | Campo | Tipo | Obrigatório | Descrição | | ---------- | ------ | ----------- | -------------------------------------------------------------------------------------------------- | | `interval` | string | Sim | Intervalo entre as cobranças: `Monthly` (mensal) ou `Annual` (anual). Valores: `Monthly`, `Annual` | | `endDate` | string | Não | Data final da recorrência no formato `YYYY-MM-DD`. Sem ela, a recorrência segue indefinidamente | ## Recurrence [#recurrence] Estado de uma recorrência | Campo | Tipo | Obrigatório | Descrição | | -------------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `recurrentPaymentId` | string | Não | Identificador da recorrência. Use nos endpoints de consulta e gestão de recorrências | | `interval` | string | Não | Intervalo configurado. Valores: `MONTHLY`, `ANNUAL` | | `status` | string | Não | Status da recorrência. Veja [Pagamentos Recorrentes](https://docs.payzu.com.br/docs/cartao/recurrence). Valores: `ACTIVE`, `INACTIVE`, `ENDED` | | `amount` | number | Não | Valor de cada ciclo, em centavos | | `nextRecurrency` | string | Não | Data da próxima cobrança automática | | `endDate` | string | Não | Data final, se informada na criação | ## Charge [#charge] | Campo | Tipo | Obrigatório | Descrição | | ------------------- | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Não | Identificador da cobrança | | `externalId` | string | Não | Identificador único gerado externamente | | `postbackUrl` | string | Não | Url para notificações sobre o status da cobrança | | `amount` | number | Não | Valor da cobrança em centavos | | `paymentType` | string | Não | Tipo de pagamento da cobrança. Veja [Tipos de pagamento](https://docs.payzu.com.br/docs/cartao/reference-codes) | | `createdAt` | string | Não | Data de criação da cobrança | | `updatedAt` | string | Não | Data da última atualização da cobrança | | `customer` | [CustomerResponse](#customerresponse) | Não | | | `cart` | [CartItem](#cartitem)\[] | Não | Carrinho do comprador | | `creditCardPayment` | [CreditCardPaymentResponse](#creditcardpaymentresponse) | Não | | | `recurrence` | [Recurrence](#recurrence) | Não | Presente quando a cobrança pertence a uma recorrência | | `recurrenceCycle` | integer | Não | Número do ciclo da recorrência a que esta cobrança pertence: 0 é a cobrança inicial, 1..n são os ciclos gerados automaticamente. Presente apenas em cobranças de recorrência | ## ChargeRequest [#chargerequest] | Campo | Tipo | Obrigatório | Descrição | | ------------------- | --------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `amount` | number | Sim | Valor da cobrança em centavos | | `customer` | [CustomerRequest](#customerrequest) | Sim | | | `postbackUrl` | string | Não | Url para notificações sobre o status da cobrança. Veja [Webhooks](https://docs.payzu.com.br/docs/cartao/webhooks) | | `paymentType` | string | Sim | Tipo de pagamento da cobrança. Veja [Tipos de pagamento](https://docs.payzu.com.br/docs/cartao/reference-codes). Valores: `creditcard` | | `cart` | [CartItem](#cartitem)\[] | Sim | Carrinho do comprador | | `creditCardPayment` | object | Sim | Definições para o tipo de pagamento: cartão de crédito | | `recurrence` | [RecurrenceRequest](#recurrencerequest) | Não | | | `externalId` | string | Sim | Identificador único gerado externamente |