These types are building blocks used across different transaction requests. Each one is designed to modularly encapsulate account, risk, and customer details.

Legend

Type	Description
✅	Required.
☑️	Optional field depending on content.
🚫	Not required.

Account Information (PayGateAccountType)

<Account>
  <PayGateId>10011072130</PayGateId>
  <Password>test</Password>
</Account>

Field	Description	Type	Required
PayGateId	Your PayGate ID, assigned by PayGate.	Number(11)	✅
Password	Your password set in the Merchant Access Portal.	Varchar(32)	✅

Risk Information (RiskType)

<Risk>
  <AccountNumber>12345678</AccountNumber>
  <SessionId>345tg345</SessionId>
  <IpV4Address>192.168.1.1</IpV4Address>
  <IpV6Address>2001:0db8:85a3:0000:0000:8a2e:0370:7334</IpV6Address>
  <UserId>TestId</UserId>
  <MachineId>4d36e968-e325-11ce-bfc1-08002be10318</MachineId>
  <UserProfile>basic</UserProfile>
  <ConsumerWatch>No</ConsumerWatch>
  <Browser>(BrowserType)</Browser>
</Risk>

Field	Description	Type	Required if
AccountNumber	Unique reference number tied to the customer at the merchant.	Varchar(30)	☑️If Fraud and Risk screening is activated
SessionId	Web server-generated session ID.	Varchar(255)	🚫
IpV4Address	Customer's IPv4 address. Required if subscribed to PayProtector.	Varchar(15)	☑️If PayProtector or Fraud and Risk screening is activated
IpV6Address	Customer's IPv6 address. Required if subscribed to PayProtector.	Varchar(15)	☑️If PayProtector or Fraud and Risk screening is activated
UserId	Merchant-configured ID uniquely identifying a customer across accounts.	Varchar(36)	☑️
MachineId	Unique identifier for the customer’s hardware (e.g. motherboard ID, HDD ID, CPU ID).	Varchar(255)	☑️
UserProfile	Custom classification used in fraud screening (e.g., VIP, promo user, etc). Can be repeated.	Varchar(20)	☑️
ConsumerWatch	Register customer for Consumer Watch. Values: `Y` (Yes), `N` (No).	Char(1)	☑️
Browser	Contains browser information fields.	BrowserType	☑️

Customer Details (PersonType)

<Customer>
  <Title>Mr</Title>
  <FirstName>PayGate</FirstName>
  <MiddleName>Soap</MiddleName>
  <LastName>Test</LastName>
  <Telephone>0211234567</Telephone>
  <Telephone>0214567891</Telephone>
  <Mobile>0821234567</Mobile>
  <Email>itsupport@paygate.co.za</Email>
  <DateOfBirth>2013-01-10</DateOfBirth>
  <Nationality>ZAF</Nationality>
  <IdNumber>20130110123456789</IdNumber>
  <IdType>3</IdType>
  <Address>(AddressType)</Address>
</Customer>

Field	Description	Type	Required if
Title	Customer's title (e.g., Mr, Mrs).	Varchar(5)	☑️
FirstName	Customer's first name.	Varchar(50)	✅
MiddleName	Customer's middle name.	Varchar(50)	☑️
LastName	Customer's last name.	Varchar(50)	✅
Telephone	Customer's telephone number. Repeatable.	Varchar(45)	☑️If Fraud and Risk screening is activated
Mobile	Customer's mobile phone number. Repeatable.	Varchar(45)	☑️
Fax	Customer's fax number. Repeatable.	Varchar(45)	☑️
Email	Customer's email address. Repeatable.	Varchar(255)	✅
DateOfBirth	Customer's date of birth. Format: `YYYY-MM-DD` (e.g., `2013-01-10`).	Date	☑️
Nationality	Customer’s nationality. Use ISO Alpha-3 country codes (e.g., `GBR` for the UK).	Char(3)	☑️
IdNumber	Customer’s ID, passport, or other verification document number.	Varchar(40)	☑️
IdType	Type of ID supplied. See table below.	Number(2)	☑️
SocialSecurityNumber	US only – last 4 digits of Social Security Number.	Number(4)	☑️
Address	Contains customer’s address details. See `AddressType`.	AddressType	☑️

ID Type Values

Type	Description
1	Passport
2	Personal ID
3	Identity Card
4	Driver’s License
5	Other
8	Travel Document
12	Residence Permit
13	Identity Certificate
16	Registro Federal de Contribuyentes
17	Credencial de Elector
18	DNI
19	NIE
20	CPR Number

BrowserType

Field	Description	Type	Required
UserAgent	USER_AGENT of the browser used	Varchar(255)	🚫
Language	Language of the browser used	Varchar(30)	🚫

AddressType

<Address>
    <AddressLine>Apartment 2A</AddressLine>
    <AddressLine>1 Main Rd</AddressLine>
    <City>Cape Town</City>
    <Country>ZAF</Country>
    <State>Western Cape</State>
    <Zip>7700</Zip>
</Address>

Field	Description	Type	Required
AddressLine	Customer’s address line. Repeatable.	Varchar(60)	✅
City	Customer’s city	Varchar(25)	☑️ If Fraud and Risk screening is activated
Country	Customer’s country. Refer to Country Codes. E.g. GBR	Char(3)	☑️ If Fraud and Risk screening is activated
State	Customer's State/Province/District. Special codes required for certain countries.	Varchar(25)	🚫
Zip	Customer’s zip/postal code	Varchar(10)	🚫

ShippingDetailsType

<ShippingDetails>
    <Customer>(PersonType)</Customer>
    <Address>(AddressType)</Address>
    <DeliveryDate>2019-01-02T12:00:00+02:00</DeliveryDate>
    <DeliveryMethod>Over Night</DeliveryMethod>
    <InstallationRequested>N</InstallationRequested>
</ShippingDetails>

Field	Description	Type	Required
Customer	Contains a complex type of customer fields	PersonType
Address	Contains a complex type of address fields	AddressType
DeliveryDate	Delivery date in UTC format (e.g. 2019-01-02T12:00:00+02:00)	Datetime YYYY-MM-DDThh:mm:ss	☑️
DeliveryMethod	Method of delivery	Varchar(30)	☑️
InstallationRequested	Whether goods include physical installation: `Y` or `N`	Char(1)	☑️

BillingDetailsType

<BillingDetails>
    <Customer>(PersonType)</Customer>
    <Address>(AddressType)</Address>
</BillingDetails>

Field	Description	Type	Required
Customer	Contains a complex type of customer fields	PersonType
Address	Contains a complex type of address fields	AddressType

OrderItemType

<OrderItems>
    <ProductCode>ABC-123</ProductCode>
    <ProductDescription>Description</ProductDescription>
    <ProductCategory>Category</ProductCategory>
    <ProductRisk>Low</ProductRisk>
    <OrderQuantity>1</OrderQuantity>
    <UnitPrice>3295</UnitPrice>
    <Currency>ZAR</Currency>
</OrderItems>

Field	Description	Type	Required
ProductCode	Line item product code. If one tag is populated, all must be	Varchar(50)	☑️
ProductDescription	Product description	Varchar(50)	☑️
ProductCategory	Product category	Varchar(50)	☑️
ProductRisk	Product risk level (High, Medium, Low)	Varchar(50)	☑️
OrderQuantity	Quantity ordered	Number(11)	☑️
UnitPrice	Price per unit in cents (e.g. R32.95 = 3295)	Number(11)	☑️
Currency	Currency code (Refer to Currency Codes)	Char(3)

OrderType

<Order>
    <MerchantOrderId>13E22035FC</MerchantOrderId>
    <Currency>ZAR</Currency>
    <Amount>3295</Amount>
    <Discount>295</Discount>
    <TransactionDate>2019-01-01T12:00:00+02:00</TransactionDate>
    <BiilingDetails>(BillingDetailsType)</BiilingDetails>
    <ShippingDetailsType>(ShippingDetailsType)</ShippingDetailsType>
    <OrderItems>(OrderItemsType)</OrderItems>
    <Locale>en</Locale>
</Order>

Field	Description	Type	Required
MerchantOrderId	Your reference number for internal use (e.g. Customer, Invoice, Order No.)	Varchar(80)	✅
Currency	Currency code (Refer to Currency Codes)	Char(3)	✅
Amount	Transaction amount in cents (e.g. R32.95 = 3295)	Number(11)	✅
Discount	Discount amount in cents (passed to fraud service if applicable). Not deducted from Amount	Number(11)	☑️
TransactionDate	UTC transaction timestamp (e.g. 2013-01-01T18:30:00+02:00)	Datetime YYYY-MM-DDThh:mm:ss	✅
BillingDetails	Contains billing info	BillingType	🚫
ShippingDetails	Contains shipping info	ShippingType	🚫
OrderItems	Contains line item info. Repeatable	OrderItemType	🚫
Locale	Customer's locale/language	LanguageType	🚫

PassengerType

Contains passenger details for airline bookings.

<Passengers>
  <Passenger>(PersonType)</Passenger>
  <TravellerType>Adult</TravellerType>
  <LoyaltyNumber>123456789123456789</LoyaltyNumber>
  <LoyaltyType>FlyAir</LoyaltyType>
  <LoyaltyTier>Platinum</LoyaltyTier>
</Passengers>

Field	Description	Type	Required
`Passenger`	Contains a complex type of customer fields. Repeatable. Refer to PersonType	`PersonType`
`TravellerType`	Type of passenger: `A` = Adult, `C` = Child, `I` = Infant	`Char(1)`	✅
`LoyaltyNumber`	Passenger’s loyalty scheme number	`Varchar(20)`	🚫
`LoyaltyType`	Passenger’s loyalty scheme name (e.g. Voyager)	`Varchar(20)`	🚫
`LoyaltyTier`	Loyalty tier level: 1 = Platinum, 2 = Gold, 3 = Silver, etc.	`Number(3)`	🚫

FlightLegType

Details of each flight leg in the booking.

<FlightLegs>
  <DepartureAirport>LHR</DepartureAirport>
  <DepartureCountry>GBR</DepartureCountry>
  <DepartureCity>LON</DepartureCity>
  <DepartDateTime>2019-01-01T21:40:00</DepartDateTime>
  <DepartAirportTimeZone>+02:00</DepartAirportTimeZone>
  <ArrivalAirport>CPT</ArrivalAirport>
  <ArrivalCountry>ZAF</ArrivalCountry>
  <ArrivalCity>CPT</ArrivalCity>
  <ArrivalDateTime>2019-01-02T10:10:00</ArrivalDateTime>
  <ArrivalAirportTimeZone>+02:00</ArrivalAirportTimeZone>
  <Carrier>BA</Carrier>
  <FlightNumber>6428</FlightNumber>
  <FareBasisCode>HL7LNR</FareBasisCode>
  <FareClass>CR</FareClass>
  <BaseFare>52597</BaseFare>
  <BaseFareCurrency>GBP</BaseFareCurrency>
</FlightLegs>

Field	Description	Type	Required
`DepartureAirport`	Departure airport code (e.g. `LHR`)	`Char(3)`	✅
`DepartureCountry`	Departure country code. Refer to Country Codes (e.g. `GBR`)	`Char(3)`	✅
`DepartureCity`	Departure city code (e.g. `LON`)	`Char(3)`	✅
`DepartDateTime`	Local date and time of scheduled departure	`Datetime`	✅
`DepartAirportTimeZone`	Local timezone (e.g. `+01:00`)	`Varchar(6)`	🚫
`ArrivalAirport`	Arrival airport code (e.g. `CPT`)	`Char(3)`	✅
`ArrivalCountry`	Arrival country code. Refer to Country Codes (e.g. `ZAF`)	`Char(3)`	✅
`ArrivalCity`	Arrival city code (e.g. `CPT`)	`Char(3)`	✅
`ArrivalDateTime`	Local date and time of scheduled arrival	`Datetime`	✅
`ArrivalAirportTimeZone`	Local timezone (e.g. `+01:00`)	`Varchar(6)`	🚫
`Carrier`	Airline code (e.g. `BA`)	`Char(2)`	✅
`FlightNumber`	Flight number (e.g. `6428`)	`Char(4)`	✅
`FareBasisCode`	Fare basis code (e.g. `HL7LNR`)	`Char(10)`	🚫
`FareClass`	Class of flight. example: `F (=Unrestricted First Class)` `FR (=Restricted First Class)` `F (=Unrestricted Business Class)` `CR (=Restricted Business Class)` `Y (=Unrestricted Coach/Economy Class)` `YD (=Restricted Coach/Economy Class)` (Data Capture - not fed into rules engine)	`Char(3)`	🚫
`BaseFare`	Fare amount in minor currency units (e.g. `52597` for R525.97)	`Number(11)`	✅
`BaseFareCurrency`	ISO currency code (e.g. `ZAR`). Required if`BaseFare` is populated. Refer to Currency Codes	`Char(3)`	✅if `BaseFare` is populated.

AirlineBookingType

Captures booking details for an airline transaction.

<AirlineBookingDetails>
  <TicketNumber>123459846354968451</TicketNumber>
  <InternalCustomerCode>ABC1235432136475342</InternalCustomerCode>
  <ReservationSystem>FlyMyAirline</ReservationSystem>
  <TravelAgencyCode>FMA123</TravelAgencyCode>
  <PayerTravelling>Y</PayerTravelling>
  <PNR>IB6840F</PNR>
  <Passengers>(PassengersType)</Passengers>
  <FlightLegs>(FlightLegType)</FlightLegs>
</AirlineBookingDetails>

Field	Description	Type	Required
`TicketNumber`	Ticket number assigned to the journey	`Varchar(30)`	🚫
`InternalCustomerCode`	Internal customer reference (merchant-defined)	`Text`	🚫
`ReservationSystem`	Reservation or booking system used (e.g. `Amadeus`, `Sabre`, etc.)	`Text`	🚫
`TravelAgencyCode`	Travel agency's identifying code	`Text`	🚫
`TravelAgencyName`	Name of the travel agency (if available)	`Text`	🚫
`PayerTravelling`	Is the payer also travelling? (`Y` = Yes, `N` = No)	`Char(1)`	🚫
`PNR`	Passenger Name Record	`Varchar(10)`	✅
`Passengers`	Contains a complex type of passenger fields. Refer to PassengerType	`PassengerType`	✅
`FlightLegs`	Contains a complex type of flight leg fields. Refer to FlightLegType	`FlightLegType`	✅

LanguageType

"Locale" and "Browser Language" are examples of elements that use the "LanguageType" element.

<Language>en-US</Language>

Field	Description	Type	Required
`Language`	Language format: e.g. `en-US`, `fr-FR`, `es-ES`. Must match regex: `[a-zA-Z]{2}(-[a-zA-Z]{2})?`	`Varchar(30)`	✅

User Defined Fields (UserDefinedFieldType)

Use this to add custom metadata or merchant-specific values to the transaction.

<UserDefinedFields>
    <key>BookingRef</key>
    <value>ABC123XYZ</value>
</UserDefinedFields>

Field	Description	Type	Required
`UserDefinedFields`	An unbounded list of `key/value` pairs. Useful for merchant-specific data.	`KeyValueType`	🚫

Vaulting a Card (VaultType)

If you want to tokenize the card for reuse, set Vault to true.

<Vault>true</Vault>

Field	Description	Type	Required
`Vault`	If set to `true`, the card will be tokenized.	`boolean`	🚫

Use a Vaulted Card (VaultIdType)

Reference a previously vaulted/tokenized card for payment.

<VaultId>0bf77509-4bd7-4fa4-b954-8f1c7ebb4c24</VaultId>

Field	Description	Type	Required
VaultId	Tokenized card ID to use in the transaction	`string`	🚫

Recurring Payment Details (RecurringType)

Use the Recurring object to indicate that a transaction is part of a recurring or stored credential payment flow.

<Recurring>
    <InitialAuth>true</InitialAuth>
    <RecurringTransactionType>...</RecurringTransactionType>
    <InitiatedType>...</InitiatedType>
    <OriginalRecurringReferenceID>...</OriginalRecurringReferenceID>
</Recurring>

Field	Description	Type	Required
`InitialAuth`	Indicates whether this is the initial authorisation in a recurring sequence. Default is `false`.	`boolean`	🚫
`RecurringTransactionType`	Specifies the type of recurring transaction.	`RecurringTransactionType`	🚫
`InitiatedType`	Indicates who initiated the transaction (e.g. merchant or cardholder).	`InitiatedType`	🚫
`OriginalRecurringReferenceID`	Reference ID of the original transaction in the recurring sequence.	`string`	🚫

Usage Rules

Scenario	Requirement
Vaulting a card	`InitialAuth = true`
Using a vaulted card	`InitialAuth = false`
Subsequent stored credential transaction	`OriginalRecurringReferenceID` required

Use this for card-on-file, subscription, or merchant-initiated transactions where recurring or stored credential data must be supplied.

Redirect Details (RedirectRequestType)

Used when PayGate handles 3D Secure via Hosted Payment Page or MPI.

<Redirect>
    <NotifyUrl>https://your.site/notify</NotifyUrl>
    <ReturnUrl>https://your.site/return</ReturnUrl>
    <Target>_self</Target>
</Redirect>

Field	Description	Type	Required
`NotifyUrl`	PayGate will `POST` the transaction result to this URL (back-end callback).	`Text`	✅ (if using 3D Secure)
`ReturnUrl`	Customer will be redirected here after completing payment.	`Text`	✅ (if using 3D Secure)
`Target`	Frame target for redirect (`_self`, `_parent`). Default is `_self`.	`Varchar(30)`	🚫

3D Secure Fields (ThreeDSecureType)

Used if merchant has handled 3D Secure via their own MPI.

<ThreeDSecure>
    <Enrolled>Y</Enrolled>
    <Paresstatus>Y</Paresstatus>
    <Eci>05</Eci>
    <Xid>eY4hCbMdj9FQ0X5CV9iQHt2y82T4=</Xid>
    <Cavv>Td7wOfSL7kueWouRKPhX883w8ReT=</Cavv>
</ThreeDSecure>

Field	Description	Type	Required
`Enrolled`	Card enrolled in 3D Secure (`Y`, `N`, `U`)	`Char(1)`	✅ (if 3DS)
`Paresstatus`	Result of the authentication (`Y`, `N`, `U`, `A`)	`Char(1)`	✅ (if 3DS)
`Eci`	ECI indicator for liability shift	`Varchar(3)`	✅
`Xid`	Base64-encoded transaction ID	`Text`	✅
`Cavv`	Base64-encoded authentication value	`Text`	✅

Payment Method Details (PaymentType)

Identifies the payment method and extra info (e.g., card or wallet type).

<PaymentType>
    <Method>CC</Method>
    <Detail>MasterCard</Detail>
</PaymentType>

Field	Description	Type	Required
`Method`	Code for the payment method used (e.g., `CC` = Credit Card, `BT` = EFT)	`Varchar(2)`	✅
`Detail`	More detail on the method (e.g., Visa, SID, SnapScan, MasterCard)	`Text`	🚫