Modelos

Estrutura de cada objeto trafegado pela API: campos, tipos, obrigatoriedade e descrição.

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. Valores em Códigos de referência. 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 devolvido na autenticação. Tabela em 3-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

Dados para o motor antifraude. Obrigatório em cobranças internacionais. Regras em 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). Lista em 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. Lista em Status e motivos da transação. 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. Lista em Moedas suportadas
`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. Lista em Status e motivos da transação
`reasonMessage`	string	Não	Mensagem do motivo do resultado. Lista em Status e motivos da transação
`status`	integer	Não	Status da transação. Lista em Status e motivos da transação
`returnCode`	string	Não	Código de retorno da adquirente, lido na tabela de Códigos de erro. O mesmo número tem outro significado na tabela ABECS, que é o padrão das bandeiras para recusas.
`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 e installments precisa ser 1. Regras em 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. Valores em 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. Valores em Códigos de referência
`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 que recebe as notificações de status da cobrança. Formato em Webhooks
`paymentType`	string	Sim	Tipo de pagamento da cobrança. Valores em Códigos de referência. 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

CurrencyRate

Campo	Tipo	Obrigatório	Descrição
`code`	string	Sim	Código ISO 4217 da moeda.
`rate`	object	Sim	Cotação de compra e de venda da moeda, em BRL por unidade estrangeira.

CurrencyConvertResponse

Campo	Tipo	Obrigatório	Descrição
`amount`	number	Sim	Valor convertido, em centavos da moeda de destino (`amount` dividido pela cotação), arredondado a 2 casas decimais.
`currency`	object	Sim	Moeda de destino e a cotação usada na conversão.