Token Payment (Host-to-Host)

Use tokens securely and seamlessly.

This streamlined approach reduces PCI DSS scope and simplifies your integration, letting you focus on enhancing the customer experience.

▶️ Test in Postman

View WSDL Specification ›

How It Works (Process Flow)

The customer is redirected to a secure encryption service (e.g. Visa Checkout) to authorise the transaction.
The payment provider returns a token to the merchant’s system (includes payment and customer metadata).
The merchant submits the token and other required details to PayGate via TokenPaymentRequest.
PayGate decrypts the token payload and sends the transaction to the acquiring bank.
PayGate receives the authorisation result from the bank and returns it to the merchant.

TokenPaymentRequest Example

<SinglePaymentRequest>
  <TokenPaymentRequest>
    <Account>
      <PayGateId>10011072130</PayGateId>
      <Password>test</Password>
    </Account>
    <Customer>
      <Title>Mr</Title>
      <FirstName>Joe</FirstName>
      <LastName>Soap</LastName>
      <Email>[email protected]</Email>
    </Customer>
    <Token>2258098676320541501</Token>
    <TokenDetail>VCO</TokenDetail>
    <Order>
      <MerchantOrderId>Reference</MerchantOrderId>
      <Currency>ZAR</Currency>
      <Amount>1000</Amount>
    </Order>
  </TokenPaymentRequest>
</SinglePaymentRequest>

Fields Reference

Field	Description	Type	Required
`Account`	Your PayGate account credentials.	`PayGateAccountType`	✅
`Customer`	Customer information. Required depending on token detail (see note below).	`[PersonType](/reference/request-message-types#customer-details-persontype)`	✅
`Token`	The encrypted token provided by the external provider.	`Text`	⚠️
`TokenDetail`	Indicates the encryption service used. E.g. `VCO` = Visa Checkout.	`Varchar`	✅
`Vault`	Optional. If `true`, enables PayVault tokenisation.	`Boolean`	❌
`Order`	Order-related data, such as merchant reference and amount.	`[OrderType](/reference/request-message-types#ordertype)`	✅
`BillingDescriptor`	Optional. Custom text shown on the customer's bank statement (if supported by acquirer).	`Varchar(45)`	❌
`UserDefinedField`	Optional. Key-value metadata to pass additional data.	`[UserDefinedFieldType](/reference/request-message-types#user-defined-fields-userdefinedfieldtype)`	❌

Notes

Customer Info Requirement: Whether you must pass customer details depends on the token service used. PayGate will guide you for each TokenDetail value.
Visa Checkout Specifics: Customer, shipping, and billing details will default to what’s inside the token. However:
- If Customer or Shipping fields are explicitly included in your request, these will override token values.
- BillingDetails will always come from the Visa Checkout token.

Sample response:

<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:TokenPaymentResponse>
                <ns2:Status>
                    <ns2:TransactionId>1034868888</ns2:TransactionId>
                    <ns2:Reference>Reference</ns2:Reference>
                    <ns2:AcquirerCode>00</ns2:AcquirerCode>
                    <ns2:StatusName>Completed</ns2:StatusName>
                    <ns2:AuthCode>ABC123</ns2:AuthCode>
                    <ns2:PayRequestId>D3F33DA9-8432-4EA1-BB4A-16E4C582D3A2</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>1000</ns2:Amount>
                    <ns2:RiskIndicator>XX</ns2:RiskIndicator>
                    <ns2:PaymentType>
                        <ns2:Method>CC</ns2:Method>
                        <ns2:Detail>Visa Checkout</ns2:Detail>
                    </ns2:PaymentType>
                </ns2:Status>
            </ns2:TokenPaymentResponse>
        </ns2:SinglePaymentResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>