Card Payment (Host-to-Host)

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

Process Flow Overview

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

1. Customer enters card details on the merchant's website.

2. Merchant server submits a CardPaymentRequest to PayHost.

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

4. PayGate sends a server-to-server notification to your NotifyUrl.

5. Your server responds with 'OK'.

6. 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>[email protected]</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

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

💡 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?