setTransaction (RPP)

Owned by Rijk Stofberg (Deactivated)
Last updated: Jul 20, 2023 by Junaid
6 min read
For the SOAP headers that have to accompany this message, see the section on RPP SOAP headers.


The setTransaction API call is used to setup/initiate transactions between the merchant and PayU using server to server requests. This has to be done before the customer can pay on the PayU payment page. Minimal detail about the transaction is passes, server-to-server, over HTTP POST or GET requests.

Please note: no special characters are allowed in any of the API call parameters as downstream systems are unable to process them.

After doing a successful setTransaction request, a PayU reference number is issued in response. When the customer's browser redirects to the PayU payment page, this reference number is used to find the correct transaction and effect payment. Append this parameter and its value to the the RPP URL and redirect the customer's browser to the resultant URL e.g.:
https://secure.payu.co.za/rpp.do?PayUReference=123456789

Transaction Types

The transaction type parameter in the setTransaction call is used to identify what type of transaction will be done.
You can read more about transaction type parameter values here,  but two are typically used - RESERVE or PAYMENT. Each of these transaction types has a different effect on the transaction's authorisation and settle components, which are explained below.

RESERVE transaction type
This transaction type is typically used when a merchant issues shippable goods or gets stock from a supplier.

Scenario:
Once a customer does a successful payment on the PayU interface, the funds are authorised. The merchant will try and source the goods from its supplier. Once the merchant has received the stock and is ready to ship, the merchant will issue a settle on the funds and ship the goods.

A typical payment sequence for the RESERVE transaction type:
1. Do a setTransaction SOAP call against PayU API on merchant's website
2. Redirect to the PayU payment interface
3. Customer submits and gets redirected back to merchant's website
4. Do a getTransaction SOAP call against PayU API on merchant's website to get transaction payment details e.g. funds successfully reserved
The following is typically done once the merchant is in possession of the shippable goods
5. Do a doTransaction SOAP call with a FINALIZE transaction type against PayU API on merchant's website
6. Do a getTransaction SOAP call against PayU API on merchant's website to get transaction payment details e.g. funds successfully reserved


PAYMENT transaction type
The PAYMENT transaction type is typically used in transactions when stock is immediately available e.g. an mp3 download or online tickets.
Scenario:
Once a customer does a successful payment on the PayU interface, the funds are authorised and settled. The merchant now gives the customer access to the goods e.g. mp3 download link

A typical payment sequence for the PAYMENT transaction type:
1. Do a setTransaction SOAP call against PayU API on merchant's website
2. Redirect to the PayU payment interface
3. Customer submits and gets redirected back to merchant's website
4. Do a getTransaction SOAP call against PayU API on merchant's website to get transaction payment details e.g. funds successfully reserved


Redirect Channel Types
The redirect channel parameter in the setTransaction call is used to identify what type of payment page should be displayed.
You can read more about redirect channel parameter values below, but two are typically used - web or responsive.

web redirect channel
Will serve a normal html page with all the support payment methods.

responsive redirect channel
Will serve a responsive page.

mobi redirect channel
Will serve a page optimised for mobile devices, but only supports credit card payments and the user does not have to log into the PayU portal.

The use of the mobi and web redirectChannel only applies to existing merchants, for backwards compatibility; and is in the process of being deprecated.

SetTransaction: Request Parameters

Parameter Name

Description

Data type

Required field for request

SetTransactionRequest

RESERVE

PAYMENT

REGISTER_LINK

Api

Version of the API. Current Version: 1.0 (SOAP: ONE_ZERO)

String

Y

Y

Y

Safekey

PayU Merchant Identifier. Provided to merchant upon integration

String

Y

Y

Y

TransactionType

The type of transaction being performed:
RESERVE
PAYMENT

String

Y

Y

Y

AdditionalInformation

MerchantReference

Unique merchant identifier for transaction.

String

Y

Y

Y

SupportedPaymentMethods

Comma separated list of payment methods to be displayed on the payment page:
CREDITCARD, DISCOVERYMILES, EBUCKS, EFT, MASTERPASS, RCS, EFT_PRO, MOBICRED, MPESA, FASTA, PAYFLEX, MORETYME, MOBICRED_VIRTUAL_CREDIT, OPEN_BANKING*(displays Capitec Pay)

String

Y

Y

N

Secure3d

This will determine if the transaction goes through 3D Secure at the issuing bank. Values: True/False.

String

Y

Y

N

DemoMode

To determine if the API request should be handled as a demo transaction. Values: True/False.

String

Y

Y

N

NotificationURL

URL where the merchant would like to be notified of transaction result via IPN (Instant Payment Notification). (max length is 255 characters)

String

N

N

N

ReturnUrl

URL to return browser to after a customer has completed transaction. (max length is 255 characters) NB: Please note that the ReturnURL is not only for successful payments, it is the page that customers will be returned to post payment regardless of success or failure. Please ensure a GET transaction call is used to confirm the payment status.

String

Y

Y

Y

CancelUrl

URL to return browser to if a customer cancels a transaction. (max length is 255 characters)

String

Y

Y

Y

ShowBudget

Determined whether user should be given option to select budget for credit card. Values: True/False

String

N

N

N

redirectChannel

Valid values:

web

responsive

mobi

StringNNN

Customer

FirstName

Customer first name

String

N

N

N

LastName

Customer last name

String

N

N

N

RegionalId

Regional identifier for customer such as RSA ID

String

N

N

N

Mobile

Customer Mobile Number in international format without +( eg 27827891248)

String

N

N

N

Email

Customer Email Address

String

N

N

N

MerchUserId

Unique Customer ID in merchant system

String

N

N

Y

Basket

Description

Basket description that will show on PayU (min length:3)

String

Y

Y

N

AmountInCents

Total amount of the basket in cents. Format as 1000 for R10.00

String

Y

Y

N

CurrencyCode

International Currency code. Example: ZAR

String

Y

Y

N

CustomFields

Key

Identification for custom field.

String

N

N

N

Value

Value for custom field

String

N

N

N

Y - Mandatory

N - Optional

NA - Not Allowed

setTransaction: Response Parameters

Response Parameters

Parameter Name

Description

Values

MerchantReference

Merchant identifier for transaction.

String

Successful

Boolean value to determine if the transaction was successful or not.

String

PointOfFailure

Indicated on failed transactions where the point of failure was

String

ResultCode

Result code returned by PayU for transaction

String

ResultMessage

Result message relating to result code for transaction

String

DisplayMessage

Display friendly message for the customer

String

PayUReference

PayU unique reference number for transaction

String

setTransaction: SOAP request example
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://soap.api.controller.web.payjar.com/" xmlns:ns2="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <SOAP-ENV:Header>
        <wsse:Security SOAP-ENV:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:UsernameToken wsu:Id="UsernameToken-9" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
                <wsse:Username>Staging Enterprise With Fraud Integration Store 1</wsse:Username>
                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">xoV3PFor</wsse:Password>
            </wsse:UsernameToken>
        </wsse:Security>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns1:setTransaction>
            <Api>ONE_ZERO</Api>
            <Safekey>{CF86C6D5-016C-4E98-9E4F-0F4FE3A0C1BA}</Safekey>
            <TransactionType>PAYMENT</TransactionType>
            <AdditionalInformation>
                <cancelUrl>http://qa.payu.co.za/integration-qa/internal-tools/demos/developer/payu-redirect-payment-page/cancel-page.php</cancelUrl>
                <demoMode>false</demoMode>
                <merchantReference>mercRef_1395758213</merchantReference>
                <notificationUrl>http://qa.payu.co.za/integration-qa/internal-tools/demos/developer/payu-redirect-payment-page/notification-page.php</notificationUrl>
                <redirectChannel>web</redirectChannel>
                <returnUrl>http://qa.payu.co.za/integration-qa/internal-tools/demos/developer/payu-redirect-payment-page/send-getTransaction-via-soap.php</returnUrl>
                <secure3d>true</secure3d>
                <supportedPaymentMethods>CREDITCARD</supportedPaymentMethods>
            </AdditionalInformation>
            <Customer>
                <email>killer@bean.com</email>
                <firstName>firstName_1395758213</firstName>
                <ip>196.28.165.93</ip>
                <lastName>lastName_1395758213</lastName>
                <merchantUserId>merchantUserId_1395758213</merchantUserId>
                <mobile>27827777777</mobile>
                <regionalId>regionalId_1395758213</regionalId>
            </Customer>
            <Basket>
                <amountInCents>6707</amountInCents>
                <currencyCode>ZAR</currencyCode>
                <description>basketDesc_1395758213</description>
            </Basket>
        </ns1:setTransaction>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
setTransaction: SOAP response example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

    <soap:Body>
        <ns2:setTransactionResponse xmlns:ns2="http://soap.api.controller.web.payjar.com/">
            <return>
                <merchantReference>mercRef_1395758213</merchantReference>
                <payUReference>150238913484</payUReference>
                <successful>true</successful>
            </return>
        </ns2:setTransactionResponse>
    </soap:Body>
</soap:Envelope>