Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The Instant Payment Notification (IPN) is an asynchronous notification mechanism where PayU sends transaction results/information to a specified URL without any dependency on a customer's browser. The merchant's system can consume the IPN and validate the outcome of the transaction.

Instant Payment Notifications (IPN)’s will be fired in the following cases when the merchant has provided a NotificationURL in their SetTransaction or DoTransaction API call:

  1. When a payment on the PayU redirect either fails or is successful
  2. When a user session times out on the PayU redirect with no chance for the user to finish payment
  3. When transaction pending review for fraud is either approved or rejected by case managers. In the case of approval the IPN will fire after the payment has been attempted and will return that result.
  4. EFT transactions

The NotificationURL can be set to an HTTP or HTTPS endpoint.

Warning

If unable to deliver an IPN on the first attempt, PayU will retry a further 2 times (3 attempts in total). If however on the 3rd attempt it could still not be succesfully delivered, the IPN data will automatically be sent to the store's configured merchant email address.

Warning:

The receiving system might take longer to process the IPN than PayU can wait for the response.  Once PayU reaches its timeout it will mark the message as unsuccessful and it will be sent again.  This can lead to a situation where the receiver processes the same IPN multiple times.  To stop this from happening the receiver MUST pay close attention to the ResponseHash.  Each discrete IPN has a unique ResponseHash.  When an IPN is resent, it will be exactly the same message.  This includes the ResponseHash.  Thus if the receiving system is cognisant of the fact that it is receiving the same IPN again based on ResponseHash, it can effectively stop duplicate transactions.

Example:

  • Merchant sends payment instruction to PayU.
  • PayU processes and sends IPN response informing merchant that transaction was successful.
  • Merchant decides to credit customer and instructs PayU to credit the previous transaction.
  • PayU does the credit and sends an IPN notifying the merchant that it was successful.
  • Merchant receives the IPN and starts to credit the customer, but does not respond in time.
  • PayU marks the IPN as not successful and resends.
  • Merchant receives same IPN again.
  • At this point the merchant checks the ResponseHash and figures out that it has already processed this IPN and ignores it, but returns a success to PayU in order to stop further resending.

 

 

Info

 PayU has an IPN simulation tool which can be used to simulate IPNs back to a merchant. More information on this can be found here.

IPN transaction result validation

Interpretation of IPN responses to validate the result of a transaction should ideally be done on (but not limited to) a combination of the following fields:

  • resultCode
  • successful
  • transactionState
  • transactionType

Please refer to the transaction states and types pages which sets out all of the variations found for possible values. Please refer to the error message page for all possible PayU errors that can be recieved in the IPNs.

Smart EFT specific IPN transaction result validation

SmartEFT solution relies heavily on the on the IPN solution as this information is only available on the IPN sent to the merchant. As such a few extra transaction states are introduced specific to SmartEFT

The following IPNs are applicable to the SmartEFT

...

 

The following are examples of the expected IPN structures

...

Code Block
languagexml
titleIPN (Default)
linenumberstrue
<PaymentNotification>
    <MerchantReference>MREF026</MerchantReference>
    <TransactionType>PAYMENT</TransactionType>
    <TransactionState>SUCCESSFUL</TransactionState>
    <ResultCode>00</ResultCode>
    <ResultMessage>Successful</ResultMessage>
    <PayUReference>80a0c8eb-fa63-40d3-94f0-8bdabc324932</PayUReference>
    <Basket>
        <Description>ADS026</Description>
        <AmountInCents>2100</AmountInCents>
        <CurrencyCode>ZAR</CurrencyCode>
    </Basket>
    <PaymentMethodsUsed>
        <CreditCard Information="Visa" NameOnCard="Mr Soap" CardNumber="522112xxxxxx1234" AmountInCents="10000" />
    </PaymentMethodsUsed>
    <IpnExtraInfo>
        <ResponseHash>7a06fe382948e97ad9207b8528d8c1f6847ac10d6230118ff9b3fb90eeaa4743</ResponseHash>
    </IpnExtraInfo>
</PaymentNotification>

...

Code Block
languagexml
titleIPN (3ds)
linenumberstrue
<PaymentNotification>
    <MerchantReference>MREF026</MerchantReference>
    <TransactionType>PAYMENT</TransactionType>
    <TransactionState>SUCCESSFUL</TransactionState>
    <ResultCode>00</ResultCode>
    <ResultMessage>Successful</ResultMessage>
    <PayUReference>80a0c8eb-fa63-40d3-94f0-8bdabc324932</PayUReference>
    <Basket>
        <Description>ADS026</Description>
        <AmountInCents>2100</AmountInCents>
        <CurrencyCode>ZAR</CurrencyCode>
    </Basket>
    <PaymentMethodsUsed>
        <CreditCard Information="Visa" NameOnCard="Mr Soap" CardNumber="522112xxxxxx1234" AmountInCents="10000" />
    </PaymentMethodsUsed>
    <Secure3D>
       <lkpTransactionId>card enrolement lookup ID</lkpTransactionId>
       <lkpErrorNo>0</lkpErrorNo>
       <lkpErrorDescription></lkpErrorDescription>
       <lkpEnrolled>Y</lkpEnrolled>
       <lkpEciFlag></lkpEciFlag>
       <authSend>Y</authSend>
       <authErrorNo>0</authErrorNo>
       <authErrorDescription>Auth Success</authErrorDescription>
       <authCavv>CAVV value goes here</authCavv>
       <authXid>3DS Authentication ID</authXid>
       <authEciFlag>5</authEciFlag>
       <authPAResStatus>Y</authPAResStatus>
    </Secure3D>
    <IpnExtraInfo>
        <ResponseHash>7a06fe382948e97ad9207b8528d8c1f6847ac10d6230118ff9b3fb90eeaa4743</ResponseHash>
    </IpnExtraInfo>
</PaymentNotification>

...

Code Block
languagexml
titleIPN Example (With Fraud)
linenumberstrue
<PaymentNotification>
    <MerchantReference>MREF026</MerchantReference>
    <TransactionType>PAYMENT</TransactionType>
    <TransactionState>SUCCESSFUL</TransactionState>
    <ResultCode>00</ResultCode>
    <ResultMessage>Successful</ResultMessage>
    <PayUReference>80a0c8eb-fa63-40d3-94f0-8bdabc324932</PayUReference>
    <Basket>
        <Description>ADS026</Description>
        <AmountInCents>2100</AmountInCents>
        <CurrencyCode>ZAR</CurrencyCode>
    </Basket>
    <PaymentMethodsUsed>
        <CreditCard Information="Visa" NameOnCard="Mr Soap" CardNumber="522112xxxxxx1234" AmountInCents="10000" />
    </PaymentMethodsUsed>
    <IpnExtraInfo>
        <ResponseHash>7a06fe382948e97ad9207b8528d8c1f6847ac10d6230118ff9b3fb90eeaa4743</ResponseHash>
    </IpnExtraInfo>
    <Fraud>
        <ResultCode>V032</ResultCode>
        <ResultMessage>Case manager approved transaction</ResultMessage>
        <CaseManagerNote>I got hold of the user and verified</CaseManagerNote>
    </Fraud>
</PaymentNotification>

Top

...

Reason Code

Definitions / Master card international

01  Requested transaction data Not received
02     Requested/Required item illegible or missing
07      Warning Bulletin file
08      Requested/Required authorization  Not  obtained
12    Account number Not on file
31      Transaction amount differs
34    Duplicate processing
35      Card not valid or Expired
37    No cardholder authorization
40     Fraudulent processing of transactions
41      Cancelled recurring transaction
42     Late presentment
46      Correct transaction Currency code not provided
47    Exceeds floor limit- Not  authorized  and fraudulent transaction
49      Questionable merchant activity
50 Credit Posted as a Purchase
53      Cardholder dispute – Defective/ Not as described
55     Non-receipt of  Merchandise
57     Card-activated Telephone transaction
59     Services Not rendered
60     Credit not processed
62    Counterfeit transaction magnetic stripe POS fraud
63     Cardholder does not recognize – Potential fraud
4870 Chip Liability Shift
Reason CodesDefinitions / Visa international and local banks
60  Illegible fulfilment
75Requested transaction data Not received
79 Requested transaction data Not received
57    Fraudulent multiple transactions
62     Chip liability Shift / Counterfeit transaction
81    Fraud – card Present environment ( Will request edc voucher)
83   Fraud – card Absent environment ( manual transactions, will request zip –zap voucher )
93     Risk identification service
70   Card recovery bulletin
71    Declined authorization
72    No authorization
73    Expired card
78  Service code violation
74     Late Presentment
76      Incorrect currency or Transaction code or Domestic transaction processing violation
77     None –matching account number
80    Incorrect transaction amount or account number
82    Duplicate Processing
84   Unsigned slip
86      Paid by other means
88     Split sales
89    Unauthorised signature/ card not signed
96     Transaction exceeds limited amount
41    Cancelled recurring transaction
53   Not as described or Defective merchandise
85    Credit Not processed
30    Service not provided or merchandise not received
90  Non-receipt of cash ( ATM transaction )