Payment Notification
The payment notification request is sent from Interswitch to third-party systems once payment has been completed. Payment notification is sent after a payment, not before the payment. Third-party systems would only receive payment notification once funds have been successfully collected from the customer.
The payment notification is intended to notify third-party systems of a successful payment so that value can be given to the customer.
Implementation Notes:
- A reversal payment notification is a type of payment notification used to cancel, nullify, or reverse a payment that has already been made. This means a payment notification would have been sent initially, and if the payment is cancelled on the Interswitch Bill Payment platform, a reversal request will be sent to your system to negate the effect of the initial transaction.
- Third-party systems are expected to return a status of 0. Any other status will be interpreted as the payment notification message being rejected.
- Interswitch Bill Payment Platforms would resend the payment notification for a minimum of five times.
- Third-party systems should check for duplicate payment notifications using: PaymentLogId, Amount, PaymentReference and ReceiptNo
- Third-party systems should perform an amount verification before giving value to customers. The amount returned in the payment notification should correspond to the amount expected by your system.
- Refer to Appendix 9.0 for the Payment Notification Process Flow.
Payment Notification Request Fields
This defines the expected XML tags that will be sent to third-party systems for Payment Notification. This is a generic system and new tags can be added at any time. Do not hard-code the structure of the XML requests. Your system should be able to retrieve data from the required fields and ignore others.
| Field | Mandatory/Optional | Length | Format | Description |
|---|---|---|---|---|
| ServiceUrl | Mandatory | ANY | Alphanumeric | Third-party platform service URL |
| ServiceUsername | Optional | ANY | Alphanumeric | Username to access service at merchant's end |
| ServicePassword | Optional | ANY | Alphanumeric | Password to access service at merchant's end |
| FTPUrl | Optional | ANY | Alphanumeric | Third-party platform FTP location |
| FTPUsername | Optional | ANY | Alphanumeric | Username to access FTP location at third party's end |
| FTPPassword | Optional | ANY | Alphanumeric | Password to access FTP location at third party's end |
| Payments | Mandatory | - | - | Container element for a collection of payments. |
| Payment | Mandatory | - | - | Container element for a single payment. |
| IsRepeated | Optional | Boolean | To know if the notification has been previously sent | |
| ProductGroupCode | Mandatory | ANY | Alphanumeric | Used internally by Interswitch systems |
| PaymentLogId | Mandatory | ANY | Numeric | Unique integer ID for the payment. |
| CustReference | Mandatory | ANY | Alphanumeric | Unique ID for the paying customer or specific order. Typically provided to the paying customer by the merchant. |
| AlternateCustReference | Optional | ANY | Alphanumeric | This is an alternate ID used to identify the same customer. |
| Amount | Mandatory | ANY | Numeric | Amount paid by the customer in Major Denomination. This must be verified before giving value to the customer. For reversal payment notification, the amount has a negative value. |
| IsReversal | Mandatory | - | Boolean | This specifies if the notification is a reversal payment notification. |
| PaymentDate | Mandatory | DateTime | Date ayment was made in format MM/DD/YYYY hh:mm:ss | |
| SettlementDate | Mandatory | DateTime | Date payments would be settled into Merchant account in format MM/DD/YYYY hh:mm:ss | |
| InstitutionId | Mandatory | 5 | Alphanumeric | Unique ID given to the merchant |
| InstitutionName | Mandatory | ANY | String | Merchant's configured name within the Bill Payment System |
| BranchName | Optional | ANY | String | Bank Branch where the payment was made if applicable |
| BankName | Optional | Bank where the payment was made in case of a cash payment ot bank whose card was used to pay in the card of a card based payment | ||
| FeeName | Optional | 20 | Alphanumeric | Name of Transactional Fee applied to the payment (purely informational) |
| CustomerName | Mandatory | ANY | String | Name of paying customer |
| OtherCustomerInfo | Optional | ANY | Alphanumeric | Further details on paying customer |
| RecieptNo | Mandatory | ANY | Numeric | Receipt Number issued to customer |
| CollectionsAccount | Optional | ANY | String | The account of the Collecting Bank. |
| ThirdPartyCode | Optional | 10 | String | Code for Custom Data. |
| Payments | Optional | - | - | Container element for a collection of payment items. |
| Payment | Optional | - | - | Container element for a single payment item. |
Payment Notification Request
<PaymentNotificationRequest>
<ServiceUrl>http://test.com/Payments/Interswitch/Notification_CPN.aspx</ServiceUrl>
<ServiceUsername></ServiceUsername>
<ServicePassword></ServicePassword>
<FtpUrl>http://test.com/Payments/Interswitch/Notification_CPN.aspx</FtpUrl>
<FtpUsername/>
<FtpPassword/>
<Payments>
<Payment>
<IsRepeated>False</IsRepeated>
<ProductGroupCode>HTTPGENERICv31</ProductGroupCode>
<PaymentLogId>6416218</PaymentLogId>
<CustReference>0860</CustReference>
<AlternateCustReference>[email protected]</AlternateCustReference>
<Amount>1000.00</Amount>
<PaymentStatus>0</PaymentStatus>
<PaymentMethod>Cash</PaymentMethod>
<PaymentReference>FBN|BRH|ABSA|17-03-2016|091483</PaymentReference>
<TerminalId>19</TerminalId>
<ChannelName>Bank Branc</ChannelName>
<Location>ABAJI</Location>
<IsReversal>false</IsReversal>
<PaymentDate>03/17/2016 08:55:05</</PaymentDate>
<SettlementDate>03/18/2016 00:00:01</SettlementDate>
<InstitutionId>ABSA</InstitutionId>
<InstitutionName>Abia State Autoreg</InstitutionName>
<BranchName>ABAJI</BranchName>
<BankName>First Bank of Nigeria Plc</BankName>
<FeeName>50</FeeName>
<CustomerName>Ogbonna Vitalis</CustomerName>
<OtherCustomerInfo></OtherCustomerInfo>
<ReceiptNo>14063160774946935845</ReceiptNo>
<CollectionsAccount>12232345690</CollectionsAccount>
<ThirdPartyCode>096c2ef9e7</ThirdPartyCode>
<PaymentItems>
<PaymentItem>
<ItemName>payment</ItemName>
<ItemCode>ABS001</ItemCode>
<ItemAmount>0.00</ItemAmount>
<LeadBankCode>FBN</LeadBankCode>
<LeadBankCbnCode>011</LeadBankCbnCode>
<LeadBankName>First Bank of Nigeria Plc</LeadBankName>
<CategoryCode/>
<CategoryName/>
<ItemQuantity>1</ItemQuantity>
</PaymentItem>
</PaymentItems>
<BankCode>FBN</BankCode>
<CustomerAddress/>
<CustomerPhoneNumber/>
<DepositorName>1234</DepositorName>
<DepositSlipNumber>1212343</DepositSlipNumber>
<PaymentCurrency>566</PaymentCurrency>
<OriginalPaymentLogId/>
<OriginalPaymentReference/>
<Teller>ABAJI1 ABAJI</Teller>
</Payment>
</Payments>
</PaymentNotificationRequest>Sample Payment Notification Response Message
<PaymentNotificationResponse>
<Payments>
<Payment>
<PaymentLogId>3193831</PaymentLogId>
<Status>0</Status>
</Payment>
</Payments>
</PaymentNotificationResponse>Updated about 3 hours ago
Did this page help you?