This offers enhanced security and allows for seamless integration with your existing systems, providing a more streamlined and efficient payment process.

▶️ Test in Postman

View WSDL Specification ›

Process Flow Overview

The high-level flow of a card payment using the Host-to-Host method:

Customer enters card details on the merchant's website.
Merchant server submits a CardPaymentRequest to PayHost.
If a 3D Secure challenge is required:
- Redirect the customer's browser to PayGate’s MPI.
- MPI sends the customer to their bank's 3D Secure page.
- After authentication, the bank returns the customer to PayGate, which completes the transaction.
PayGate sends a server-to-server notification to your NotifyUrl.
Your server responds with 'OK'.
The customer is redirected back to your ReturnUrl.

sequenceDiagram
    participant C as Customer
    participant M as Merchant System
    participant PG as PayGate
    participant B as Issuing Bank

    C->>M: Enter card details
    M->>PG: Send CardPaymentRequest
    alt 3D Secure required?
        PG-->>M: Return Redirect (MPI required)
        M->>C: Redirect customer to MPI
        C->>PG: Customer lands on PayGate MPI
        PG->>B: Redirect to 3D Secure authentication (ACS)
        B->>C: Customer completes authentication
        B->>PG: Return result
        alt Auth successful
            PG->>PG: Process transaction
            PG->>M: Notify via NotifyUrl
            M->>PG: Respond with OK
            PG->>C: Redirect back to Merchant
        else Auth failed
            PG->>C: Redirect to Merchant with failure
        end
    else No 3D Secure
        PG->>PG: Process transaction
        PG->>M: Notify via NotifyUrl
        M->>PG: Respond with OK
        PG->>C: Redirect back to Merchant
    end

For full 3DS details, refer to 3D Secure using PayGate’s MPI.

CardPaymentRequest

Send this XML payload as the body of your SinglePaymentRequest.

Example 1: Basic Card Payment

<SinglePaymentRequest>
  <CardPaymentRequest>
    <Account>
      <PayGateId>10011013800</PayGateId>
      <Password>test</Password>
    </Account>
    <Customer>
      <Title>Mr</Title>
      <FirstName>Joe</FirstName>
      <LastName>Soap</LastName>
      <Telephone>0861234567</Telephone>
      <Mobile>0735552233</Mobile>
      <Email>joe@soap.com</Email>
    </Customer>
    <CardNumber>4000000000000002</CardNumber>
    <CardExpiryDate>122015</CardExpiryDate>
    <CVV>999</CVV>
    <BudgetPeriod>0</BudgetPeriod>
    <Redirect>
      <NotifyUrl>https://www.mytestsite.com/notify</NotifyUrl>
      <ReturnUrl>https://www.mytestsite.com/return</ReturnUrl>
    </Redirect>
    <Order>
      <MerchantOrderId>INV101</MerchantOrderId>
      <Currency>ZAR</Currency>
      <Amount>100</Amount>
    </Order>
  </CardPaymentRequest>
</SinglePaymentRequest>

Example 2: Requesting Tokenisation (PayVault)

<CardPaymentRequest>
  ...
  <Vault>true</Vault>
  ...
</CardPaymentRequest>

This will store the card in PayVault and return a token (VaultId) in the response.

Example 3: Using a Token

<CardPaymentRequest>
  ...
  <VaultId>eb9c11c5-e564-46e2-a087-2207ab8afadd</VaultId>
  <CVV>123</CVV>
  ...
</CardPaymentRequest>

💡
You can use a previously vaulted card by including a VaultId in your request.

Request Fields

Field	Description	Type	Required
`Account`	PayGate account credentials (`PayGateId`, `Password`)	PayGateAccountType	✅
`Customer`	Customer's personal details	PersonType	✅
`CardNumber`	Full card number (exclude if using `VaultId`)	Number(19)	✅
`CardExpiryDate`	Format: `MMYYYY` (e.g. Jan 2026 = `012026`)	Number(6)	✅
`CVV`	Card security code (3–4 digits)	Number(4)	✅
`Vault`	`true` if you want to store this card in PayVault	Boolean	Optional
`VaultId`	Use tokenised card from PayVault (skip `CardNumber` and `CardExpiryDate`)	String (GUID)	Optional
`BudgetPeriod`	Set to `0` for standard payment. Budget is only supported on South African cards.	Number(2)	✅
`Redirect`	Contains `NotifyUrl` and `ReturnUrl` for 3D Secure	RedirectRequestType	✅ if 3DS
`Order`	Includes order reference, amount, and currency	OrderType	✅
`ThreeDSecure`	Only include if using your own MPI. Do not use with the `Redirect` block.	ThreeDSecureType	Conditional
`BillingDescriptor`	Text shown on customer's statement (if supported by acquirer)	String(45)	Optional
`UserDefinedField`	Optional key-value metadata for reporting	Complex	Optional
`Risk`	Risk settings (only if fraud screening is enabled)	RiskType	Optional

Sample Response
Here’s an example of a successful Card Payment response from the PayHost API:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header />
  <SOAP-ENV:Body>
    <ns2:SinglePaymentResponse xmlns:ns2="http://www.paygate.co.za/PayHOST">
      <ns2:CardPaymentResponse>
        <ns2:Status>
          <ns2:TransactionId>1034851367</ns2:TransactionId>
          <ns2:Reference>INV109</ns2:Reference>
          <ns2:AcquirerCode>00</ns2:AcquirerCode>
          <ns2:StatusName>Completed</ns2:StatusName>
          <ns2:AuthCode>GTOPI8</ns2:AuthCode>
          <ns2:PayRequestId>10179EF4-6FC7-4F57-BEC8-6D84CB9FFF26</ns2:PayRequestId>
          <ns2:TransactionStatusCode>1</ns2:TransactionStatusCode>
          <ns2:TransactionStatusDescription>Approved</ns2:TransactionStatusDescription>
          <ns2:ResultCode>990017</ns2:ResultCode>
          <ns2:ResultDescription>Auth Done</ns2:ResultDescription>
          <ns2:Currency>ZAR</ns2:Currency>
          <ns2:Amount>100</ns2:Amount>
          <ns2:RiskIndicator>XX</ns2:RiskIndicator>
          <ns2:PaymentType>
            <ns2:Method>CC</ns2:Method>
            <ns2:Detail>Visa</ns2:Detail>
          </ns2:PaymentType>
        </ns2:Status>
      </ns2:CardPaymentResponse>
    </ns2:SinglePaymentResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Response Field Highlights

Field	Description
TransactionId	Unique identifier assigned by PayGate to the transaction. Use this for reconciliations and support queries.
Reference	The `MerchantOrderId` you supplied in the request.
AuthCode	Authorisation code returned by the issuing bank. Only present for successful transactions.
StatusName	High-level transaction status. For a successful payment, this will be `Completed`.
TransactionStatusCode	Numeric status code (1 = Approved, 0 = Not Done).
ResultCode	System-level result identifier. `990017` typically means the payment was authorised successfully.
ResultDescription	Friendly status message. In this case, `Auth Done`.
Currency	Currency used in the transaction (3-letter ISO code).
Amount	Total amount in minor units (e.g. 100 = R1.00 if ZAR).
RiskIndicator	2-character field describing the result of 3D Secure authentication (first character only currently used).
PaymentType.Method	Payment method code, e.g. `CC` for Credit Card.
PaymentType.Detail	Card brand or network used (e.g. Visa, MasterCard).

💡 Include logging for TransactionId, StatusName, ResultCode, and AuthCodein your system for traceability.

Best Practices

Always use HTTPS for all URLs in your Redirect object.
Store VaultId securely and only on backend systems.
Use NotifyUrl for backend confirmation of payment — don’t rely solely on the return page.
Test with 3D Secure test cards provided by your acquirer.

Would you like me to turn this into a markdown-ready copy (with ReadMe tags like <Callout>, <Tabs>, or <Accordion>) for quick pasting? Or do you prefer to paste in manually and tweak there?