PaymentStateChangedNotification

The handlePaymentStateChangedNotification method of the Payment Service Listener API is called by PaymentService whenever a change in a payment state occurs (for configured payment states only). This is usually the case when:

• a payment is initiated (see Initiate New Payment (Redirect) or Initiate New Payment (Backend2Backend))
• an action is performed in the Payment Service Admin Tool
• an action is performed on a payment using the API - see Execute Payment Action
• or an automated backoffice process in PaymentService changes a payment's state.

Example handlePaymentStateChangedNotificationRequest for notifying a Visa Deposit in AuthorisedByProvider state:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest 
    xmlns="http://www.cqrpayments.com/PaymentProcessing" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>KalixaAcceptDEMO</merchantID>
		<shopID>KalixaAcceptDEMO</shopID>
		<paymentMethod>
			<key>2</key>
			<value>VISA Deposit</value>
		</paymentMethod>
		<merchantTransactionID>35e50c3-d5db-e74d-e6f9-d00b019fb3</merchantTransactionID>
		<paymentID>1011d6fe-80ab-4aed-bbed-3f35d4ba901e</paymentID>
		<userID>KalixaTestUser_3</userID>
		<paymentProvider>
			<key>92</key>
			<value>CQRUK</value>
		</paymentProvider>
		<amount currencyCode="EUR">15.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>10.80.12.38</userIP>
		<state>
			<id>97965dd7-90546-4b83-aea2-769b7cfghh2df</id>
			<definition>
				<key>13</key>
				<value>AuthorisedByProvider</value>
			</definition>
			<createdOn>2009-05-25T12:30:12.167</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>0</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ApprovalCode</key>
					<value>452237</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">15.0000</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>206969</value>
			</detail>
			<detail xsi:type="keyIntValuePair">
				<key>PaymentScoring</key>
				<value>711201</value>
			</detail>      
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>520000069</paymentAccountID>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationResponse to the notification of a Visa Deposit in AuthorisedByProvider state:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationResponse                                               xmlns="http://www.cqrpayments.com/PaymentProcessing"                                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"                                   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <resultCode>
    <key>0</key>
    <value>ProcessedSuccessfully</value>
  </resultCode>
  <resultMessage />
</handlePaymentStateChangedNotificationResponse>

📘

Handling of Notifications triggered after payment initiation

Only after processing the handlePaymentStateChangedNotificationRequest should the merchant proceed with further actions e.g. deliver a product or crediting money to a customer balance.

📘

Notification retries

The notification may be sent several times (e.g. 3 times), depending on the handlePaymentStateChangedNotificationResponse returned by the merchant.

The Merchant System must be able to find out whether it already processed the Payment State Notification; e.g.:

• If the merchantTransactionID is not recognized, and the payment method is Bank Transfer Deposit, then the merchant should accept the Payment State Notification (respond with resultCode = 0) and process the payment transaction
• If the merchantTransactionID is not recognized, then the merchant should reject the Payment State Notification (respond with resultCode = 3):
  • If the Payment State Notification was already received with the same merchantTransactionID, the same paymentID and the same state.id, then this means that a duplicate notification has been received; the merchant should accept the Payment State Notification (respond with resultCode = 0) to stop further notifications but not perform any processing
  • If the Payment State Notification was already received with a different paymentID, it means that more than one payment was processed for that merchantTransactionID; the merchant should accept the Payment State Notification (respond with resultCode = 0) and process the payment accordingly.

For further details see handlePaymentStateChangedNotification.

🚧

Waiting for the Notification (Redirect Integration) to arrive

Because of its asynchronous nature, the Payment State Notification (handlePaymentStateChangedNotificationRequest) can be sent in case of payment initiation with Redirect Integration also after the customer has been redirected to the merchant website; the Merchant System should refresh the page several times until the Payment State Notification has been received and the payment status can be confirmed.

The following diagram illustrates the necessary processing steps for PaymentStateChangedNotification:

Refer to Payment Methods for a list of payment methods and their corresponding states indicating credit/debit or reversal.

The following properties of the handlePaymentStateChangedNotificationRequest.payment element must be considered:

The relationship between merchant transactions and payments is one-to-many, which means that there can be several paymentIDs associated with the same merchantTransactionID in PaymentService, e.g.

Cases when this can happen:

• A customer enters wrong credit card data in the Payment Method Detail Page hosted by PXP Financial. After receiving an error he corrects the data and retriggers the payment, without going back to the merchant website in between (which means that the same merchantTransactionID is used). In this case there will be 2 payments in PaymentService – one in state Refused, and one in state AuthorisedByProvider
• All recurring payments will have the same merchantTransactionID and different paymentIDs
• Refunds have the same merchantTransactionID as the original payment (that one the refund was created for) and different paymentIDs. This has to be especially considered for partial refunds where it is possible to have more transactions with the same merchantTransactionID
• A user manipulates the HTTP POST parameters and duplicates the transaction (with a certain merchantTransactionID).

📘

Amount and currency check

In case the merchant has already defined the amount before redirecting the user to the PXP Financial Hosted Payment Pages, the pre-logged amount + currency (stored in merchant's database before making the request to PXP Financial) must be compared with the amount + currency coming in handlePaymentStateChangedNotificationRequest.

📘

Idempotent handling of duplicate notifications

Duplicate payment notifications (same merchantTransactionID, same paymentID, same payment.state.definition) should be handled in an idempotent way, which means that the same response should be returned as for the original notification.

📘

Notifications in invalid order

In case notifications for payment states arrive in invalid order, these should be reported back as an error (e.g. Cancelled before AuthorisedByProvider for card deposits).

📘

Result codes

ResultCode = 0 indicates that the notification was successfully processed by the merchant. All other codes indicate that the merchant cannot process a message. Choose the appropriate resultCode in case of an error.