PayGate

https://docs.paygate.co.za/
Admin
PayGate is a PCI DSS-compliant payment service provider offering secure hosted payment pages and...
Tokens:79,593
Snippets:736
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install PayGate Node.js SDK

Source: https://docs.paygate.co.za/paygate-by-network/reference/sdk-quick-start-guide

Install the SDK using npm or yarn.

```bash
npm install paygate-sdk
# or
yarn add paygate-sdk
```

--------------------------------

### Example SOAP Response

Source: https://docs.paygate.co.za/paygate-by-network/reference/cardvault

This is an example of a successful SOAP response from the PayHost service after a CardVaultRequest.

```xml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <!-- PayHost response payload -->
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

--------------------------------

### PaySubs POST Request Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/paysubs-introduction

This example demonstrates the parameters required for a POST request to initiate a PaySubs subscription. Ensure all required fields are included and correctly formatted.

```html
<form action="https://www.paygate.co.za/paysubs/process.trans" method="POST">
  <input type="hidden" name="VERSION" value="21">
  <input type="hidden" name="PAYGATE_ID" value="YOUR_PAYGATE_ID">
  <input type="hidden" name="REFERENCE" value="YOUR_REFERENCE">
  <input type="hidden" name="AMOUNT" value="3299">
  <input type="hidden" name="CURRENCY" value="ZAR">
  <input type="hidden" name="RETURN_URL" value="YOUR_RETURN_URL">
  <input type="hidden" name="TRANSACTION_DATE" value="2025-06-30 10:00">
  <input type="hidden" name="SUBS_START_DATE" value="2025-07-01">
  <input type="hidden" name="SUBS_END_DATE" value="2025-12-31">
  <input type="hidden" name="SUBS_FREQUENCY" value="1">
  <input type="hidden" name="PROCESS_NOW" value="YES">
  <input type="hidden" name="PROCESS_NOW_AMOUNT" value="3299">
  <input type="hidden" name="EMAIL" value="customer@example.com">
  <input type="hidden" name="CHECKSUM" value="YOUR_CHECKSUM">
  <button type="submit">Subscribe</button>
</form>
```

--------------------------------

### TokenPaymentRequest Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/token-payment-host-to-host

This example demonstrates the structure of a TokenPaymentRequest for authorising a payment using a token. It includes account credentials, customer details, the token itself, and order information.

```APIDOC
## Token Payment (Host-to-Host)

### Description
Authorise payments using a tokenised payload from a supported encryption service provider like **Visa Checkout (VCO)** — no raw card data required. This streamlined approach reduces PCI DSS scope and simplifies your integration.

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

### Fields Reference

| Field               | Description                                                                              | Type                                                                                                | Required |
| ------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------- |
| `Account`           | Your PayGate account credentials.                                                        | [`PayGateAccountType`](/reference/request-message-types#account-information-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)` | ❌        |

### TokenPaymentRequest Example

```xml
<SinglePaymentRequest>
  <TokenPaymentRequest>
    <Account>
      <PayGateId>10011072130</PayGateId>
      <Password>test</Password>
    </Account>
    <Customer>
      <Title>Mr</Title>
      <FirstName>Joe</FirstName>
      <LastName>Soap</LastName>
      <Email>joe@soap.com</Email>
    </Customer>
    <Token>2258098676320541501</Token>
    <TokenDetail>VCO</TokenDetail>
    <Order>
      <MerchantOrderId>Reference</MerchantOrderId>
      <Currency>ZAR</Currency>
      <Amount>1000</Amount>
    </Order>
  </TokenPaymentRequest>
</SinglePaymentRequest>
```
```

--------------------------------

### Example CSV Batch Filename

Source: https://docs.paygate.co.za/paygate-by-network/reference/batch-file-structure

An example of a correctly formatted batch CSV filename.

```text
BATCH_10011072130_20250624.csv
```

--------------------------------

### SOAP Web Payment Request Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/webpayment

This is an example of a SOAP request for initiating a single web payment. It includes account, customer, redirect, and order details.

```xml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
    	<SinglePaymentRequest xmlns="http://www.paygate.co.za/PayHOST">
	    	<WebPaymentRequest>
				 <!-- Account Details -->
                <Account>
                    <PayGateId>10011072130</PayGateId>
                    <Password>test</Password>
                </Account>
                <!-- Customer Details -->
                <Customer>
                    <FirstName>PayGate</FirstName>
                    <LastName>Test</LastName>
                    <Email>customer@email.co.za</Email>
                    <!-- Address Details -->
                    <Address>
                        <Country>ZAF</Country>
                    </Address>
                </Customer>
                <VaultId>046cb857-c41a-46f6-bd5d-901fd970af9f</VaultId>
                <!-- Redirect Details -->
                <Redirect>
                    <NotifyUrl>https://webhook.site</NotifyUrl>
                    <ReturnUrl>https://redirecturl.co.za</ReturnUrl>
                </Redirect>
                <!-- Order Details -->
                <Order>
                    <MerchantOrderId>utiliapp_41250008624_20210120104596</MerchantOrderId><!--eg. appname_timestamp> -->
                    <Currency>ZAR</Currency>
                    <Amount>100</Amount>
                    <BillingDetails>
                        <!-- Customer Details -->
                        <Customer>
                            <FirstName>PayGate</FirstName>
                            <LastName>Test</LastName>
                            <Email>customer@email.co.za</Email>
                            <!-- Address Details -->
                            <Address>
                                <Country>ZAF</Country>
                            </Address>
                        </Customer>
                        <!-- Address Details -->
                        <Address>
                            <Country>ZAF</Country>
                        </Address>
                    </BillingDetails>
                    <Locale>en</Locale>
                </Order>
			</WebPaymentRequest>
		</SinglePaymentRequest>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

```

--------------------------------

### Example Return URL with Transaction Outcome

Source: https://docs.paygate.co.za/paygate-by-network/reference/return-to-merchant

Illustrates how PayWeb appends transaction outcome parameters to the merchant's RETURN_URL. This example shows a typical structure with PAY_REQUEST_ID, TRANSACTION_STATUS, and CHECKSUM.

```http
https://yourdomain.com/return-handler?PAY_REQUEST_ID=23B785AE-C96C-32AF-4879-D2C9363DB6E8&TRANSACTION_STATUS=1&CHECKSUM=abcdef1234567890
```

--------------------------------

### Create Subscription

Source: https://docs.paygate.co.za/paygate-by-network/reference/paysubs-introduction

Initiates a subscription setup by redirecting the customer to PaySubs. This involves posting subscription details via an HTML form.

```APIDOC
## POST https://www.paygate.co.za/paysubs/process.trans

### Description
Initiates a subscription setup by redirecting the customer to PaySubs. This involves posting subscription details via an HTML form.

### Method
POST

### Endpoint
https://www.paygate.co.za/paysubs/process.trans

### Parameters
#### Request Body
- **VERSION** (string) - Required - PaySubs Web Interface version (use `21`)
- **PAYGATE_ID** (string) - Required - Your assigned PayGate ID
- **REFERENCE** (string) - Required - Your internal reference for the subscription
- **AMOUNT** (integer) - Required - Amount in cents (e.g. R32.99 = `3299`)
- **CURRENCY** (string) - Required - Always `ZAR`
- **RETURN_URL** (string) - Required - URL to return the customer after processing
- **TRANSACTION_DATE** (string) - Required - Current UTC timestamp, e.g. `2025-06-30 10:00`
- **SUBS_START_DATE** (string) - Required - First subscription run date, e.g. `2025-07-01`
- **SUBS_END_DATE** (string) - Required - Final run date for the subscription
- **SUBS_FREQUENCY** (string) - Required - Frequency code (see Subscription Frequency section)
- **PROCESS_NOW** (string) - Required - `YES` or `NO` — whether to process an immediate transaction
- **PROCESS_NOW_AMOUNT** (integer) - Required - Amount (in cents) for the immediate transaction if `PROCESS_NOW = YES`
- **EMAIL** (string) - Optional - Customer’s email address (optional, but recommended)
- **CHECKSUM** (string) - Required - MD5 hash of all posted fields + your encryption key
```

--------------------------------

### Example Redirect Response

Source: https://docs.paygate.co.za/paygate-by-network/reference/web-payment-redirect

An example of the redirect response received after a successful payment request. This includes the RedirectUrl and associated parameters needed to construct the Hosted Payment Page URL.

```APIDOC
## Redirect Response Example

### Description
Provides an example of the XML response containing the `RedirectUrl` and `UrlParams` required to construct the Hosted Payment Page URL.

### Response Example (XML)
```xml
<Redirect>
  <RedirectUrl>https://secure.paygate.co.za/PayHost/process.trans</RedirectUrl>
  <UrlParams>
    <key>PAYGATE_ID</key>
    <value>10011072130</value>
  </UrlParams>
  <UrlParams>
    <key>PAY_REQUEST_ID</key>
    <value>F6601047-EA36-4E86-89E9-52345A8CB201</value>
  </UrlParams>
  <UrlParams>
    <key>REFERENCE</key>
    <value>INV101</value>
  </UrlParams>
  <UrlParams>
    <key>CHECKSUM</key>
    <value>2d58fcbde138d7e6dbea9a2fcb54724e</value>
  </UrlParams>
</Redirect>
```

**Note:** Use the `RedirectUrl` and `UrlParams` key-value pairs to construct the URL for your Hosted Payment Page.
```

--------------------------------

### Shipping Details XML Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/request-message-types

Contains details about the shipping of goods. DeliveryDate, DeliveryMethod, and InstallationRequested are required.

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

--------------------------------

### Batch Line Format Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/web-services

Illustrates the CSV-like format for submitting transactions within a batch file.

```text
A,transaction_reference,Joe Soap,18566ddc-b13b-4c9f-9e88-9a2f9a9dd64a,00,1000
```

--------------------------------

### DeleteVaultRequest Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/deletevault

This example demonstrates the structure of a DeleteVaultRequest. It includes account credentials and the VaultId to be deleted. This operation is irreversible.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "PayHost",
    "version": "1.0.0",
    "description": "PayHost is PayGate’s SOAP-based enterprise payment API for direct payments, hosted payment page flows, payouts, and vault operations. For documentation clarity in ReadMe, each request type is shown as a separate logical operation below. At runtime, these requests are submitted to the same endpoint: `POST /payhost/process.trans`."
  },
  "servers": [
    {
      "url": "https://secure.paygate.co.za"
    }
  ],
  "tags": [
    {
      "name": "Vault",
      "description": "Vault management operations submitted to PayHost."
    }
  ],
  "x-readme": {
    "explorer-enabled": true
  },
  "paths": {
    "/payhost/delete-vault": {
      "post": {
        "tags": [
          "Vault"
        ],
        "summary": "DeleteVault",
        "description": "## DeleteVaultRequest\n\nThe `DeleteVaultRequest` allows a merchant to permanently delete a previously stored credit card token from PayVault. This is typically used when a customer requests the removal of their saved card, or when data retention policies require the clearing of stored payment details.\n\nOnly the `VaultId` (the token) is required — no card number or expiry date needs to be supplied.\n\nOnce deleted, the VaultId becomes invalid and cannot be used in future transactions.\n\n---\n\n### Common Use Cases\n\n- Customer removes saved card from their profile\n    \n- Merchant performs a cleanup of unused or expired VaultIds\n    \n- Compliance with data retention or privacy regulations (e.g. GDPR, POPIA)\n    \n\n---\n\n### Request Requirements\n\n- A valid PayGate `PayGateId` and `Password`\n    \n- A `VaultId` previously generated via `CardVaultRequest`\n    \n\n> ⚠️ **Irreversible Action:** Once a VaultId is deleted, it cannot be restored.\n\n**Runtime endpoint:** `POST https://secure.paygate.co.za/payhost/process.trans`",
        "operationId": "deleteVault",
        "x-paygate-runtime-path": "/payhost/process.trans",
        "parameters": [
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "text/xml"
            },
            "description": "SOAP requests in this collection use `text/xml`."
          },
          {
            "name": "SOAPAction",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "example": "SingleVaultRequest"
            },
            "description": "SOAPAction value captured from the source Postman collection."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "text/xml": {
              "schema": {
                "type": "string"
              },
              "example": "<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
    \t<SingleVaultRequest xmlns=\"http://www.paygate.co.za/PayHOST\">
\t\t\t<DeleteVaultRequest>
\t\t\t\t<Account>
\t\t\t\t\t<PayGateId>10011072130</PayGateId>
\t\t\t\t\t<Password>test</Password>
\t\t\t\t</Account>
\t\t\t\t<VaultId>56c2d6fd-e73a-4291-af79-dba7f478d591</VaultId>
\t\t\t</DeleteVaultRequest>
\t\t</SingleVaultRequest>
\t</SOAP-ENV:Body>
</SOAP-ENV:Envelope>"
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SoapSuccess"
          }
        },
        "x-soap-action": "SingleVaultRequest"
      }
    }
  },
  "components": {
    "responses": {
      "SoapSuccess": {
        "description": "SOAP response returned by PayHost.",
        "content": {
          "text/xml": {
            "schema": {
              "type": "string"
            },
            "examples": {
              "example": {
                "summary": "Example SOAP response",
                "value": "<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\">
  <SOAP-ENV:Body>
    <!-- PayHost response payload -->
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>"
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Example RiskDetails with MAC 2

Source: https://docs.paygate.co.za/paygate-by-network/reference/blocking-on-risk-mac-codes

This XML snippet shows an example of the RiskDetails element containing MerchantAdviceCode 2, indicating that the transaction should be retried later. It also includes BlockStatus information.

```xml
<ns2:RiskDetails>
  <ns2:MerchantAdviceCode>2</ns2:MerchantAdviceCode>
  <ns2:BlockStatus>
    <ns2:Permanent>false</ns2:Permanent>
    <ns2:UntilDate>2025-02-16T09:13:31.000+02:00</ns2:UntilDate>
  </ns2:BlockStatus>
</ns2:RiskDetails>
```

--------------------------------

### PayBatch Auth Request SOAP Body Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/post_paybatch-auth

An example of the SOAP request body for initiating a batch of authorization transactions. It includes batch reference, notification URL, and batch data.

```xml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <Auth>
      <BatchReference>pgtest_123</BatchReference>
      <NotificationUrl>https://example.com</NotificationUrl>
      <BatchData>
        <BatchLine>A,...</BatchLine>
      </BatchData>
    </Auth>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

```

--------------------------------

### Samsung Pay Developer Setup Flow

Source: https://docs.paygate.co.za/paygate-by-network/reference/samsung-paytm-token-payments-host-to-host-paygate-payhost

This flowchart illustrates the steps involved in setting up a Samsung Pay developer account and service.

```mermaid
flowchart LR
    A[Sign-in with Samsung Account]
    B[Agree to T&C]
    C[Select Service Location]
    D[Complete Registration Form]
    E[Submit Sign-up Request]
    F[RM Approval]

    A --> B --> C --> D --> E --> F
```

--------------------------------

### Card Payout Response Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/payout-request

This is an example of a successful response to a card payout request. A successful response indicates the request was accepted. Monitor the final status using the Query API.

```xml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Header/>
	<SOAP-ENV:Body>
		<ns2:SinglePayoutResponse xmlns:ns2="http://www.paygate.co.za/PayHOST">
			<ns2:CardPayoutResponse>
				<ns2:Status>
					<ns2:TransactionId>1036203748</ns2:TransactionId>
					<ns2:Reference>order-1234</ns2:Reference>
					<ns2:StatusName>Completed</ns2:StatusName>
					<ns2:PayRequestId>E0CAAB06-B555-41D0-8E8F-F025C83F1745</ns2:PayRequestId>
					<ns2:TransactionStatusCode>0</ns2:TransactionStatusCode>
					<ns2:TransactionStatusDescription>Not Done</ns2:TransactionStatusDescription>
					<ns2:ResultCode>990006</ns2:ResultCode>
					<ns2:ResultDescription>Request for Payout Received</ns2:ResultDescription>
					<ns2:Currency>ZAR</ns2:Currency>
					<ns2:Amount>100</ns2:Amount>
					<ns2:PaymentType>
						<ns2:Method>CC</ns2:Method>
						<ns2:Detail>Visa</ns2:Detail>
					</ns2:PaymentType>
					<ns2:DateTime>2025-06-20T08:38:49.540+02:00</ns2:DateTime>
				</ns2:Status>
			</ns2:CardPayoutResponse>
		</ns2:SinglePayoutResponse>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

--------------------------------

### Initiate Request Checksum Generation (PHP)

Source: https://docs.paygate.co.za/paygate-by-network/reference/security-and-checksum-validation

Example of generating an MD5 checksum for an initiate request using PHP. Ensure all required fields are concatenated with the encryption key before hashing.

```php
$encryptionKey = 'secret';

$data = array(
  'PAYGATE_ID'        => 10011072130,
  'REFERENCE'         => 'pgtest_123456789',
  'AMOUNT'            => 3299,
  'CURRENCY'          => 'ZAR',
  'RETURN_URL'        => 'https://my.return.url/page',
  'TRANSACTION_DATE'  => '2018-01-01 12:00:00',
  'LOCALE'            => 'en-za',
  'COUNTRY'           => 'ZAF',
  'EMAIL'             => 'customer@paygate.co.za'
);

$checksum = md5(implode('', $data) . $encryptionKey);
```

```http
10011072130pgtest_1234567893299ZARhttps://my.return.url/page2018-01-01 12:00:00en-zaZAFcustomer@paygate.co.zasecret
```

```text
59229d9c6cb336ae4bd287c87e6f0220
```

--------------------------------

### Redirect Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/response-message-types

This XML structure indicates that a redirect is required to complete the payment process. It includes the URL for redirection and necessary parameters.

```xml
<Redirect>
    <RedirectUrl>https://secure.paygate.co.za/PayHost/redirect.trans</RedirectUrl>
    <UrlParams>
        <key>PAYGATE_ID</key>
        <value>10011013800</value>
    </UrlParams>
    <UrlParams>
        <key>PAY_REQUEST_ID</key>
        <value>5FC0E808-27EB-7A69-64BF-8163B2837869</value>
    </UrlParams>
    <UrlParams>
        <key>CHECKSUM</key>
        <value>7fe36c62991df6de51b09db0c6fd6r29</value>
    </UrlParams>
</Redirect>
```

--------------------------------

### TokenPaymentRequest Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/token-payment-host-to-host

Submit a tokenised payment request to PayGate. Ensure the Token and TokenDetail fields are correctly populated based on the external provider's response.

```xml
<SinglePaymentRequest>
  <TokenPaymentRequest>
    <Account>
      <PayGateId>10011072130</PayGateId>
      <Password>test</Password>
    </Account>
    <Customer>
      <Title>Mr</Title>
      <FirstName>Joe</FirstName>
      <LastName>Soap</LastName>
      <Email>joe@soap.com</Email>
    </Customer>
    <Token>2258098676320541501</Token>
    <TokenDetail>VCO</TokenDetail>
    <Order>
      <MerchantOrderId>Reference</MerchantOrderId>
      <Currency>ZAR</Currency>
      <Amount>1000</Amount>
    </Order>
  </TokenPaymentRequest>
</SinglePaymentRequest>
```

--------------------------------

### Billing Details XML Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/request-message-types

Contains details for billing purposes, including customer and address information.

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

--------------------------------

### Initiate Request Endpoint

Source: https://docs.paygate.co.za/paygate-by-network/reference/initiate-request

Send a POST request to the initiate endpoint to start a PayWeb3 transaction. All field names in the request must be in uppercase.

```APIDOC
## POST https://secure.paygate.co.za/payweb3/initiate.trans

### Description
Initiates a PayWeb3 transaction by sending transaction details to the PayGate server.

### Method
POST

### Endpoint
https://secure.paygate.co.za/payweb3/initiate.trans

### Parameters
#### Request Body
- **PAYGATE_ID** (varchar(20)) - Required - Your PayGate ID.
- **REFERENCE** (varchar(110)) - Required - Your internal reference for the transaction.
- **AMOUNT** (varchar(20)) - Required - Amount in cents (e.g., 32.99 = 3299).
- **CURRENCY** (varchar(5)) - Required - Currency code (e.g., ZAR).
- **RETURN_URL** (varchar(255)) - Required - Where the customer should be redirected after payment.
- **TRANSACTION_DATE** (datetime) - Required - UTC-formatted timestamp of the transaction.
- **LOCALE** (varchar(5)) - Optional - Customer locale (e.g., `en-za`).
- **COUNTRY** (varchar(5)) - Optional - Country code (e.g., `ZAF`).
- **EMAIL** (varchar(255)) - Required - Customer email address for confirmation.
- **PAY_METHOD** (varchar(5)) - Not Supported - Restrict to a specific payment method.
- **PAY_METHOD_DETAIL** (varchar(45)) - Not Supported - Detail for the payment method (if applicable).
- **NOTIFY_URL** (text) - Optional - URL to receive a real-time response.
- **USER1** (varchar(255)) - Optional - Custom field 1 – must be included in CHECKSUM if used.
- **USER2** (varchar(255)) - Optional - Custom field 2.
- **USER3** (varchar(255)) - Optional - Custom field 3.
- **VAULT** (tinyint(3)) - Optional - Set to 1 to tokenise card using PayVault.
- **VAULT_ID** (varchar(40)) - Optional - Token to use a saved card (if PayVault is enabled).
- **CHECKSUM** (varchar(40)) - Required - MD5 hash of all fields + encryption key.

### Request Example
```json
{
  "PAYGATE_ID": "10011072130",
  "REFERENCE": "pgtest_123456789",
  "AMOUNT": 3299,
  "CURRENCY": "ZAR",
  "RETURN_URL": "https://my.return.url/page",
  "TRANSACTION_DATE": "2023-10-27 10:00:00",
  "LOCALE": "en-za",
  "COUNTRY": "ZAF",
  "EMAIL": "customer@paygate.co.za",
  "CHECKSUM": "a1b2c3d4e5f67890a1b2c3d4e5f67890"
}
```

### Response
#### Success Response (200)
(Response details not provided in source text)

#### Response Example
(Response example not provided in source text)
```

--------------------------------

### Example Redirect Form

Source: https://docs.paygate.co.za/paygate-by-network/reference/redirect-to-payweb

An HTML form that should be submitted by the merchant to redirect the client to PayWeb. Ensure PAY_REQUEST_ID and CHECKSUM are correctly populated and uppercase.

```html
<form action="https://secure.paygate.co.za/payweb3/process.trans" method="POST">
  <input type="hidden" name="PAY_REQUEST_ID" value="23B785AE-C96C-32AF-4879-D2C9363DB6E8">
  <input type="hidden" name="CHECKSUM" value="b41a77f83a275a849f23e30b4666e837">
  <input type="submit" value="Continue to PayWeb">
</form>

```

--------------------------------

### PayWeb3 Initiate Transaction Request Parameters

Source: https://docs.paygate.co.za/paygate-by-network/reference/post_payweb3-initiate-trans

This JSON object outlines the parameters required to initiate a PayWeb3 transaction. Each parameter is described with its purpose and an example value.

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "PayWeb3",
    "description": "**PayWeb3** is a secure, mobile-friendly payment solution that enables merchants to accept online payments through a hosted PayGate payment page. With a single integration, you gain access to multiple payment methods and benefit from streamlined checkout, PCI compliance, and enhanced fraud protection — all without handling sensitive card data directly.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://secure.paygate.co.za"
    }
  ],
  "components": {
    "securitySchemes": {
      "noauthAuth": {
        "type": "http",
        "scheme": "noauth"
      }
    }
  },
  "paths": {
    "/payweb3/initiate.trans": {
      "post": {
        "tags": [
          "default"
        ],
        "summary": "Initiate",
        "description": "Starts the PayWeb3 transaction process by submitting payment details to PayGate. Returns a `PAY_REQUEST_ID` and `CHECKSUM`, which are required for redirecting the customer to the secure PayWeb payment page.",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "properties": {
                  "PAYGATE_ID": {
                    "type": "string",
                    "description": "Your PayGateID – assigned by PayGate",
                    "example": "10011072130"
                  },
                  "REFERENCE": {
                    "type": "string",
                    "description": "This is your reference number for use by your internal systems",
                    "example": "pgtest_1234567"
                  },
                  "AMOUNT": {
                    "type": "string",
                    "description": "Transaction amount in cents. e.g. 32.99 is specified as 3299",
                    "example": "3299"
                  },
                  "CURRENCY": {
                    "type": "string",
                    "description": "Currency code of the currency the customer is paying in.  [See Currency Codes](https://developer.globalpay.com/resources/currency-codes)",
                    "example": "ZAR"
                  },
                  "RETURN_URL": {
                    "type": "string",
                    "description": "Once the transaction is completed, PayWeb will return the customer to a page on your web site. The page the customer must see is specified in this field",
                    "example": "https://my.return.url/page"
                  },
                  "TRANSACTION_DATE": {
                    "type": "string",
                    "description": "This is the date that the transaction was initiated on your website or system. The transactionCountry code of the country the customer is paying from date must be specified in 'Coordinated Universal Time' (UTC) e.g. 2016-05-30 09:30:10",
                    "example": "2025-06-06 12:45:44"
                  },
                  "LOCALE": {
                    "type": "string",
                    "description": "The locale code identifies to PayGate the customer’s language, country and any special variant preferences (such as Date/Time format) which may be applied to the user interface. Not all the locales in the [locale table][#locales] are supported by PayGate. Please confirm with Support if the locale(s) you are using is supported. If the locale passed is not supported, then PayGate will default to the “en” locale. [See Locale Codes](/reference/locale-codes/)",
                    "example": "en-za"
                  },
                  "COUNTRY": {
                    "type": "string",
                    "description": "The country code of the customer's location. [See Country Codes](/reference/country-codes/)",
                    "example": "ZAF"
                  },
                  "EMAIL": {
                    "type": "string",
                    "description": "If the transaction is approved, PayWeb will email a payment confirmation to this email address – unless this is overridden at a gateway level by using the Payment Confirmation setting. This field remains compulsory but the sending of the confirmation email can be blocked",
                    "example": "customer@paygate.co.za"
                  },
                  "NOTIFY_URL": {
                    "type": "string",
                    "description": "Your webhook endpoint.",
                    "example": "https://webhook.site/8553a288-f57d-4707-989e-c49653b08dc2"
                  },
                  "CHECKSUM": {
                    "type": "string",
                    "description": "This field contains a calculated MD5 hash based on the values of ALL the above-mentioned fields and a key. Refer to the section on Security below for more detail regarding the MD5 hash.",
                    "example": "d4a777d45d9661e773f311ab4c44ffbf"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Example Void Request

Source: https://docs.paygate.co.za/paygate-by-network/reference/payhost-follow-up-requests

Use this XML to cancel a transaction that has not yet been settled or refunded. This operation is only possible before the transaction is submitted to the acquiring bank.

```xml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <SingleFollowUpRequest xmlns="http://www.paygate.co.za/PayHOST">
            <VoidRequest>
                <Account>
                    <PayGateId>10011072130</PayGateId>
                    <Password>test</Password>
                </Account>
                <MerchantOrderId>8101213</MerchantOrderId>
                <TransactionType>Authorisation</TransactionType>
            </VoidRequest>
        </SingleFollowUpRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

--------------------------------

### Example Redirect Response

Source: https://docs.paygate.co.za/paygate-by-network/reference/web-payment-redirect

This XML structure shows the RedirectUrl and associated UrlParams returned by PayGate upon a successful request. Use these to construct the Hosted Payment Page URL.

```xml
<Redirect>
  <RedirectUrl>https://secure.paygate.co.za/PayHost/process.trans</RedirectUrl>
  <UrlParams>
    <key>PAYGATE_ID</key>
    <value>10011072130</value>
  </UrlParams>
  <UrlParams>
    <key>PAY_REQUEST_ID</key>
    <value>F6601047-EA36-4E86-89E9-52345A8CB201</value>
  </UrlParams>
  <UrlParams>
    <key>REFERENCE</key>
    <value>INV101</value>
  </UrlParams>
  <UrlParams>
    <key>CHECKSUM</key>
    <value>2d58fcbde138d7e6dbea9a2fcb54724e</value>
  </UrlParams>
</Redirect>
```

--------------------------------

### Node.js Sample: Initiate PayWeb3 Request

Source: https://docs.paygate.co.za/paygate-by-network/reference/initiate-request

Demonstrates how to initiate a PayWeb3 transaction using Node.js and Axios. Includes setting up transaction data, generating an MD5 checksum, and sending the POST request.

```javascript
const axios = require('axios');
const crypto = require('crypto');

// Encryption key set in the Merchant Access Portal
const encryptionKey = 'secret';

const data = {
  PAYGATE_ID: '10011072130',
  REFERENCE: 'pgtest_123456789',
  AMOUNT: 3299,
  CURRENCY: 'ZAR',
  RETURN_URL: 'https://my.return.url/page',
  TRANSACTION_DATE: new Date().toISOString().replace('T', ' ').substring(0, 19),
  LOCALE: 'en-za',
  COUNTRY: 'ZAF',
  EMAIL: 'customer@paygate.co.za'
};

// Generate checksum
const checksumString = Object.values(data).join('') + encryptionKey;
data.CHECKSUM = crypto.createHash('md5').update(checksumString).digest('hex');

// Send the request
axios.post('https://secure.paygate.co.za/payweb3/initiate.trans', new URLSearchParams(data).toString(), {
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Referer': 'yourdomain.com' // Replace with your actual domain
  }
})
.then(response => {
  console.log('Response:', response.data);
})
.catch(error => {
  console.error('Error:', error);
});
```

--------------------------------

### Example Batch Transaction Result

Source: https://docs.paygate.co.za/paygate-by-network/reference/web-services

An example of a successful batch transaction result retrieved using the Query operation.

```text
71737522,A,transaction_reference,123456,1,Approved,990017,Auth Done
```

--------------------------------

### PHP Sample: Initiate PayWeb3 Request

Source: https://docs.paygate.co.za/paygate-by-network/reference/initiate-request

Demonstrates how to initiate a PayWeb3 transaction using PHP and cURL. Includes setting up transaction data, generating an MD5 checksum, and sending the POST request.

```php
<?php

// Encryption key set in the Merchant Access Portal
$encryptionKey = 'secret';

$DateTime = new DateTime();

$data = array(
    'PAYGATE_ID'        => 10011072130,
    'REFERENCE'         => 'pgtest_123456789',
    'AMOUNT'            => 3299,
    'CURRENCY'          => 'ZAR',
    'RETURN_URL'        => 'https://my.return.url/page',
    'TRANSACTION_DATE'  => $DateTime->format('Y-m-d H:i:s'),
    'LOCALE'            => 'en-za',
    'COUNTRY'           => 'ZAF',
    'EMAIL'             => 'customer@paygate.co.za',
);

$checksum = md5(implode('', $data) . $encryptionKey);
$data['CHECKSUM'] = $checksum;

$fieldsString = http_build_query($data);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://secure.paygate.co.za/payweb3/initiate.trans');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_NOBODY, false);
curl_setopt($ch, CURLOPT_REFERER, $_SERVER['HTTP_HOST']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $fieldsString);
$result = curl_exec($ch);
curl_close($ch);
?>
```

--------------------------------

### Initiate Request Sample Response

Source: https://docs.paygate.co.za/paygate-by-network/reference/initiate-request

This snippet shows the structure of a successful response to an initiate request, which is returned as standard HTTP POST data.

```APIDOC
## Initiate Request Response

### Description
Provides the structure of a successful response to an initiate request.

### Method
POST

### Endpoint
/initiate

### Response Fields
#### Success Response (200)
- **PAYGATE_ID** (varchar(20)) - Same PayGate ID sent in the request
- **PAY_REQUEST_ID** (varchar(36)) - GUID generated for this transaction
- **REFERENCE** (varchar(110)) - Same reference value sent in the request
- **CHECKSUM** (varchar(32)) - MD5 hash of the response fields

### Response Example
```http
PAYGATE_ID=10011072130
&PAY_REQUEST_ID=23B785AE-C96C-32AF-4879-D2C9363DB6E8
&REFERENCE=pgtest_123456789
&CHECKSUM=b41a77f83a275a849f23e30b4666e837
```
```

--------------------------------

### Inbound Redirect Payload Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/redirect-to-paygate

This is an example of the HTTP POST payload received when a customer is redirected back to your site after a transaction. It includes transaction status and a checksum for verification.

```http
PAY_REQUEST_ID=7B44FC55-ப்புகளை&TRANSACTION_STATUS=1&CHECKSUM=d88fa44173...
```

--------------------------------

### Valid Batch File Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/merchant-access-portal-processing

This snippet shows the correct format for a batch file entry, including account number, reference, name, card number, expiry date, and amount.

```text
A,test-ref-001,Joe Soap,4000000000000002,122026,00,1000
A,test-ref-002,Jane Doe,5200000000000015,102025,00,2500
```

--------------------------------

### Initiate Request with Optional Fields (PHP)

Source: https://docs.paygate.co.za/paygate-by-network/reference/security-and-checksum-validation

Extending the initiate request checksum generation to include optional fields like NOTIFY_URL and USER1.

```php
$data['NOTIFY_URL'] = 'https://my.notify.url/page';
$data['USER1'] = 'UserField';
```

```text
...customer@paygate.co.zahttps://my.notify.url/pageUserFieldsecret
```

```text
a7e87c0c9070b79c1b163b8c3262068b
```

--------------------------------

### Card Payout Request Example

Source: https://docs.paygate.co.za/paygate-by-network/reference/cardpayout

This is an example of a CardPayoutRequest wrapped in a SinglePayoutRequest, intended for submission to the /process.trans endpoint. Ensure your merchant account and payment method support payouts.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "PayHost",
    "version": "1.0.0",
    "description": "PayHost is PayGate’s SOAP-based enterprise payment API for direct payments, hosted payment page flows, payouts, and vault operations. For documentation clarity in ReadMe, each request type is shown as a separate logical operation below. At runtime, these requests are submitted to the same endpoint: `POST /payhost/process.trans`."
  },
  "servers": [
    {
      "url": "https://secure.paygate.co.za"
    }
  ],
  "tags": [
    {
      "name": "Payouts",
      "description": "Payout request operations submitted to PayHost."
    }
  ],
  "x-readme": {
    "explorer-enabled": true
  },
  "paths": {
    "/payhost/card-payout": {
      "post": {
        "tags": [
          "Payouts"
        ],
        "summary": "CardPayout",
        "description": "Use the `CardPayoutRequest` to process card-based payouts (withdrawals) to customers. This is only available for merchants and payment methods that support payouts. The request must be wrapped in a `SinglePayoutRequest` and submitted to the `/process.trans` endpoint using the standard SOAP envelope format.\n\n**Runtime endpoint:** `POST https://secure.paygate.co.za/payhost/process.trans`",
        "operationId": "cardPayout",
        "x-paygate-runtime-path": "/payhost/process.trans",
        "parameters": [
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "text/xml"
            },
            "description": "SOAP requests in this collection use `text/xml`."
          },
          {
            "name": "SOAPAction",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "example": "SinglePayment"
            },
            "description": "SOAPAction value captured from the source Postman collection."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "text/xml": {
              "schema": {
                "type": "string"
              },
              "example": "<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <SinglePayoutRequest xmlns=\"http://www.paygate.co.za/PayHOST\">
      <CardPayoutRequest>
        <Account>
          <PayGateId>10011072130</PayGateId>
          <Password>test</Password>
        </Account>
        <Customer>
          <FirstName>Joe</FirstName>
          <LastName>Soap</LastName>
          <Email>customer@email.co.za</Email>
        </Customer>
        <CardNumber>4000000000000002</CardNumber>
        <CardExpiryDate>032029</CardExpiryDate>
        <Order>
          <MerchantOrderId>order-1234</MerchantOrderId>
          <Currency>ZAR</Currency>
          <Amount>100</Amount>
        </Order>
      </CardPayoutRequest>
    </SinglePayoutRequest>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>"
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SoapSuccess"
          }
        },
        "x-soap-action": "SinglePayment"
      }
    }
  },
  "components": {
    "responses": {
      "SoapSuccess": {
        "description": "SOAP response returned by PayHost.",
        "content": {
          "text/xml": {
            "schema": {
              "type": "string"
            },
            "examples": {
              "example": {
                "summary": "Example SOAP response",
                "value": "<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\">
  <SOAP-ENV:Body>
    <!-- PayHost response payload -->
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>"
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Create a Once-Off Payment Request

Source: https://docs.paygate.co.za/paygate-by-network/reference/sdk-quick-start-guide

A minimal example demonstrating how to create a once-off payment request using the PayGate SDK. Ensure you have your PayGate ID, encryption key, and desired payment details.

```javascript
const PayGate = require('paygate-sdk');

const paygate = new PayGate({
  payGateId: '10011072130',
  encryptionKey: 'secret',
  testMode: true,
});

const paymentData = {
  reference: 'ORDER123',
  amount: 19999, // in cents
  currency: 'ZAR',
  returnUrl: 'https://yourdomain.com/return',
};

paygate.onceOffPayment(paymentData)
  .then((response) => {
    console.log('Payment URL:', response.redirectUrl);
  })
  .catch((error) => {
    console.error('Error creating payment:', error.message);
  });
```
Tokens:
Raw