Developers
Developer PortalMerchant Access PortalPayFast Dev Docs

Request Message Types

This section describes the various XML data types used in PayHost integrations.

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

Legend

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

Account Information (PayGateAccountType)

<Account>
  <PayGateId>10011072130</PayGateId>
  <Password>test</Password>
</Account>
FieldDescriptionTypeRequired
PayGateIdYour PayGate ID, assigned by PayGate.Number(11)✅
PasswordYour 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>
FieldDescriptionTypeRequired if
AccountNumberUnique reference number tied to the customer at the merchant.Varchar(30)☑️If Fraud and Risk screening is activated
SessionIdWeb server-generated session ID.Varchar(255)🚫
IpV4AddressCustomer's IPv4 address. Required if subscribed to PayProtector.Varchar(15)☑️If PayProtector or Fraud and Risk screening is activated
IpV6AddressCustomer's IPv6 address. Required if subscribed to PayProtector.Varchar(15)☑️If PayProtector or Fraud and Risk screening is activated
UserIdMerchant-configured ID uniquely identifying a customer across accounts.Varchar(36)☑️
MachineIdUnique identifier for the customer’s hardware (e.g. motherboard ID, HDD ID, CPU ID).Varchar(255)☑️
UserProfileCustom classification used in fraud screening (e.g., VIP, promo user, etc). Can be repeated.Varchar(20)☑️
ConsumerWatchRegister customer for Consumer Watch. Values: Y (Yes), N (No).Char(1)☑️
BrowserContains 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>[email protected]</Email>
  <DateOfBirth>2013-01-10</DateOfBirth>
  <Nationality>ZAF</Nationality>
  <IdNumber>20130110123456789</IdNumber>
  <IdType>3</IdType>
  <Address>(AddressType)</Address>
</Customer>
FieldDescriptionTypeRequired if
TitleCustomer's title (e.g., Mr, Mrs).Varchar(5)☑️
FirstNameCustomer's first name.Varchar(50)✅
MiddleNameCustomer's middle name.Varchar(50)☑️
LastNameCustomer's last name.Varchar(50)✅
TelephoneCustomer's telephone number. Repeatable.Varchar(45)☑️If Fraud and Risk screening is activated
MobileCustomer's mobile phone number. Repeatable.Varchar(45)☑️
FaxCustomer's fax number. Repeatable.Varchar(45)☑️
EmailCustomer's email address. Repeatable.Varchar(255)✅
DateOfBirthCustomer's date of birth. Format: YYYY-MM-DD (e.g., 2013-01-10).Date☑️
NationalityCustomer’s nationality. Use ISO Alpha-3 country codes (e.g., GBR for the UK).Char(3)☑️
IdNumberCustomer’s ID, passport, or other verification document number.Varchar(40)☑️
IdTypeType of ID supplied. See table below.Number(2)☑️
SocialSecurityNumberUS only – last 4 digits of Social Security Number.Number(4)☑️
AddressContains customer’s address details. See AddressType.AddressType☑️

ID Type Values

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

BrowserType

FieldDescriptionTypeRequired
UserAgentUSER_AGENT of the browser usedVarchar(255)🚫
LanguageLanguage of the browser usedVarchar(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>
FieldDescriptionTypeRequired
AddressLineCustomer’s address line. Repeatable.Varchar(60)✅
CityCustomer’s cityVarchar(25)☑️ If Fraud and Risk screening is activated
CountryCustomer’s country. Refer to Country Codes. E.g. GBRChar(3)☑️ If Fraud and Risk screening is activated
StateCustomer's State/Province/District. Special codes required for certain countries.Varchar(25)🚫
ZipCustomer’s zip/postal codeVarchar(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>
FieldDescriptionTypeRequired
CustomerContains a complex type of customer fieldsPersonType
AddressContains a complex type of address fieldsAddressType
DeliveryDateDelivery date in UTC format (e.g. 2019-01-02T12:00:00+02:00)Datetime YYYY-MM-DDThh:mm:ss☑️
DeliveryMethodMethod of deliveryVarchar(30)☑️
InstallationRequestedWhether goods include physical installation: Y or NChar(1)☑️

BillingDetailsType

<BillingDetails>
    <Customer>(PersonType)</Customer>
    <Address>(AddressType)</Address>
</BillingDetails>
FieldDescriptionTypeRequired
CustomerContains a complex type of customer fieldsPersonType
AddressContains a complex type of address fieldsAddressType

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>
FieldDescriptionTypeRequired
ProductCodeLine item product code. If one tag is populated, all must beVarchar(50)☑️
ProductDescriptionProduct descriptionVarchar(50)☑️
ProductCategoryProduct categoryVarchar(50)☑️
ProductRiskProduct risk level (High, Medium, Low)Varchar(50)☑️
OrderQuantityQuantity orderedNumber(11)☑️
UnitPricePrice per unit in cents (e.g. R32.95 = 3295)Number(11)☑️
CurrencyCurrency 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>
FieldDescriptionTypeRequired
MerchantOrderIdYour reference number for internal use (e.g. Customer, Invoice, Order No.)Varchar(80)✅
CurrencyCurrency code (Refer to Currency Codes)Char(3)✅
AmountTransaction amount in cents (e.g. R32.95 = 3295)Number(11)✅
DiscountDiscount amount in cents (passed to fraud service if applicable). Not deducted from AmountNumber(11)☑️
TransactionDateUTC transaction timestamp (e.g. 2013-01-01T18:30:00+02:00)Datetime YYYY-MM-DDThh:mm:ss✅
BillingDetailsContains billing infoBillingType🚫
ShippingDetailsContains shipping infoShippingType🚫
OrderItemsContains line item info. RepeatableOrderItemType🚫
LocaleCustomer's locale/languageLanguageType🚫

PassengerType

Contains passenger details for airline bookings.

<Passengers>
  <Passenger>(PersonType)</Passenger>
  <TravellerType>Adult</TravellerType>
  <LoyaltyNumber>123456789123456789</LoyaltyNumber>
  <LoyaltyType>FlyAir</LoyaltyType>
  <LoyaltyTier>Platinum</LoyaltyTier>
</Passengers>
FieldDescriptionTypeRequired
PassengerContains a complex type of customer fields. Repeatable. Refer to PersonTypePersonType
TravellerTypeType of passenger: A = Adult, C = Child, I = InfantChar(1)✅
LoyaltyNumberPassenger’s loyalty scheme numberVarchar(20)🚫
LoyaltyTypePassenger’s loyalty scheme name (e.g. Voyager)Varchar(20)🚫
LoyaltyTierLoyalty 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>
FieldDescriptionTypeRequired
DepartureAirportDeparture airport code (e.g. LHR)Char(3)✅
DepartureCountryDeparture country code. Refer to Country Codes (e.g. GBR)Char(3)✅
DepartureCityDeparture city code (e.g. LON)Char(3)✅
DepartDateTimeLocal date and time of scheduled departureDatetime✅
DepartAirportTimeZoneLocal timezone (e.g. +01:00)Varchar(6)🚫
ArrivalAirportArrival airport code (e.g. CPT)Char(3)✅
ArrivalCountryArrival country code. Refer to Country Codes (e.g. ZAF)Char(3)✅
ArrivalCityArrival city code (e.g. CPT)Char(3)✅
ArrivalDateTimeLocal date and time of scheduled arrivalDatetime✅
ArrivalAirportTimeZoneLocal timezone (e.g. +01:00)Varchar(6)🚫
CarrierAirline code (e.g. BA)Char(2)✅
FlightNumberFlight number (e.g. 6428)Char(4)✅
FareBasisCodeFare basis code (e.g. HL7LNR)Char(10)🚫
FareClassClass 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)🚫
BaseFareFare amount in minor currency units (e.g. 52597 for R525.97)Number(11)✅
BaseFareCurrencyISO currency code (e.g. ZAR). Required ifBaseFare is populated. Refer to Currency CodesChar(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>
FieldDescriptionTypeRequired
TicketNumberTicket number assigned to the journeyVarchar(30)🚫
InternalCustomerCodeInternal customer reference (merchant-defined)Text🚫
ReservationSystemReservation or booking system used (e.g. Amadeus, Sabre, etc.)Text🚫
TravelAgencyCodeTravel agency's identifying codeText🚫
TravelAgencyNameName of the travel agency (if available)Text🚫
PayerTravellingIs the payer also travelling? (Y = Yes, N = No)Char(1)🚫
PNRPassenger Name RecordVarchar(10)✅
PassengersContains a complex type of passenger fields. Refer to PassengerTypePassengerType✅
FlightLegsContains a complex type of flight leg fields. Refer to FlightLegTypeFlightLegType✅

LanguageType

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

<Language>en-US</Language>
FieldDescriptionTypeRequired
LanguageLanguage 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>
FieldDescriptionTypeRequired
UserDefinedFieldsAn 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>
FieldDescriptionTypeRequired
VaultIf 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>
FieldDescriptionTypeRequired
VaultIdTokenized card ID to use in the transactionstring🚫

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>
FieldDescriptionTypeRequired
InitialAuthIndicates whether this is the initial authorisation in a recurring sequence. Default is false.boolean🚫
RecurringTransactionTypeSpecifies the type of recurring transaction.RecurringTransactionType🚫
InitiatedTypeIndicates who initiated the transaction (e.g. merchant or cardholder).InitiatedType🚫
OriginalRecurringReferenceIDReference ID of the original transaction in the recurring sequence.string🚫

Usage Rules

ScenarioRequirement
Vaulting a cardInitialAuth = true
Using a vaulted cardInitialAuth = false
Subsequent stored credential transactionOriginalRecurringReferenceID 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>
FieldDescriptionTypeRequired
NotifyUrlPayGate will POST the transaction result to this URL (back-end callback).Text✅ (if using 3D Secure)
ReturnUrlCustomer will be redirected here after completing payment.Text✅ (if using 3D Secure)
TargetFrame 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>
FieldDescriptionTypeRequired
EnrolledCard enrolled in 3D Secure (Y, N, U)Char(1)✅ (if 3DS)
ParesstatusResult of the authentication (Y, N, U, A)Char(1)✅ (if 3DS)
EciECI indicator for liability shiftVarchar(3)✅
XidBase64-encoded transaction IDText✅
CavvBase64-encoded authentication valueText✅

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>
FieldDescriptionTypeRequired
MethodCode for the payment method used (e.g., CC = Credit Card, BT = EFT)Varchar(2)✅
DetailMore detail on the method (e.g., Visa, SID, SnapScan, MasterCard)Text🚫

Updated 4 months ago

Did this page help you?

Updated 4 months ago

Did this page help you?