Instant Payment Notification

Owned by Rijk Stofberg (Deactivated)
Last updated: Nov 15, 2016 by Former user (Deleted)
4 min read


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. The standard server response for a successfully posted IPN, is an 'HTTP 200 OK' status code from the specified URL's server.

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.

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 successfully 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.

 

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

  • AWAITING_PAYMENT
    Customer completed the rpp eft payment and is yet to make payment

  • SUCCESSFUL
    The customer made the exact payment. i.e., the correct bank, correct reference and the correct amount

  • EXPIRED
    Now, if the customer does not make a correct payment, the EFT will be unmatched. The merchant will need to contact our call center and match the EFT. Once the EFT is matched by the PayU team, it can go into 1 of 3 states.

  • PARTIAL_PAYMENT 
    If the customer paid less than the required amount.

  • OVER_PAYMENT 
    If the customer paid more than the required amount.

 

The following are examples of the expected IPN structures


IPN (Default)
<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>




IPN (3ds)
<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>




IPN Example (With Fraud)
<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