setTransaction (RPP)

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	String	N	N	N
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>

Developers Section

setTransaction (RPP)

SetTransaction: Request Parameters

setTransaction: Response Parameters

Related pages