Models

Structure of every object exchanged with the API: fields, types, whether they are required, and descriptions.

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

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

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	No

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

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

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

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

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
`version`	string	Yes	3DS version applied in the authentication process
`referenceId`	string	Yes	RequestID returned in the authentication process

FraudAnalysis

Data for the antifraud engine. Required on international charges. See Using 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

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

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
`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
`reasonMessage`	string	No	Reason message of the result. See Transaction status and reasons
`status`	integer	No	Transaction status. See Transaction status list
`returnCode`	string	No	Return code from the acquirer. See Error Codes and ABECS return 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	No
`chargebacks`	Chargeback[]	No	Chargebacks linked to the charge

RecurrenceRequest

Recurring payment configuration. The first charge is created immediately; the following cycles are generated automatically. Requires installments equal to 1. See Recurring payments

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

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

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
`createdAt`	string	No	Charge creation date
`updatedAt`	string	No	Date the charge was last updated
`customer`	CustomerResponse	No
`cart`	CartItem[]	No	Buyer's cart
`creditCardPayment`	CreditCardPaymentResponse	No
`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

Field	Type	Required	Description
`amount`	number	Yes	Charge amount in cents
`customer`	CustomerRequest	Yes
`postbackUrl`	string	No	Url for notifications about the charge status. See Webhooks
`paymentType`	string	Yes	Charge payment type. See Payment types. Values: `creditcard`
`cart`	CartItem[]	Yes	Buyer's cart
`creditCardPayment`	object	Yes	Settings for the payment type: credit card
`recurrence`	RecurrenceRequest	No
`externalId`	string	Yes	Unique identifier generated externally

CurrencyRate

Field	Type	Required	Description
`code`	string	Yes
`rate`	object	Yes

CurrencyConvertResponse

Field	Type	Required	Description
`amount`	number	Yes	Converted amount in the target currency, rounded to 2 decimals.
`currency`	object	Yes