Modelos

A estrutura de cada objeto que entra e sai da API: quais campos existem, o tipo de cada um e quais são obrigatórios.

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

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

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	Não

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

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

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

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. Valores: `Visa`, `Master`, `Elo`, `Diners`, `Hipercard`

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
`version`	string	Sim	Versão do 3DS aplicado no processo de autenticação
`referenceId`	string	Sim	RequestID retornado no processo de autenticação

FraudAnalysis

Dados para o motor antifraude. Obrigatório em cobranças internacionais. Veja Utilizando Antifraude

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

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

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
`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
`reasonMessage`	string	Não	Mensagem do motivo do resultado. Veja Lista de ReasonCode/ReasonMessage
`status`	integer	Não	Status da transação. Veja Lista de status da Transação
`returnCode`	string	Não	Código de retorno da adquirente. Veja Códigos de Erros e Código de retorno ABECS
`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	Não
`chargebacks`	Chargeback[]	Não	Chargebacks vinculados à cobrança

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

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

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

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
`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	Não
`cart`	CartItem[]	Não	Carrinho do comprador
`creditCardPayment`	CreditCardPaymentResponse	Não
`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

Campo	Tipo	Obrigatório	Descrição
`amount`	number	Sim	Valor da cobrança em centavos
`customer`	CustomerRequest	Sim
`postbackUrl`	string	Não	Url para notificações sobre o status da cobrança. Veja Webhooks
`paymentType`	string	Sim	Tipo de pagamento da cobrança. Veja Tipos de pagamento. Valores: `creditcard`
`cart`	CartItem[]	Sim	Carrinho do comprador
`creditCardPayment`	object	Sim	Definições para o tipo de pagamento: cartão de crédito
`recurrence`	RecurrenceRequest	Não
`externalId`	string	Sim	Identificador único gerado externamente