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 withresultCode = 0
) and process the payment transaction - If the
merchantTransactionID
is not recognized, then the merchant should reject the Payment State Notification (respond withresultCode = 3
):- If the Payment State Notification was already received with the same
merchantTransactionID
, the samepaymentID
and the samestate.id
, then this means that a duplicate notification has been received; the merchant should accept the Payment State Notification (respond withresultCode = 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 thatmerchantTransactionID
; the merchant should accept the Payment State Notification (respond withresultCode = 0
) and process the payment accordingly.
- If the Payment State Notification was already received with the same
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:
Property | Remark |
---|---|
merchantTransactionID | Generated by the merchant and passed to PaymentService |
paymentID | Generated by PaymentService and returned to the merchant |
amount (including the currencyCode) | The amount processed by PaymentService |
state.definition | The state reached by the payment |
creationType | Describes how the payment was created (see Creation Types). |
The relationship between merchant transactions and payments is one-to-many, which means that there can be several paymentID
s associated with the same merchantTransactionID
in PaymentService, e.g.
merchantTransactionID | paymentID |
---|---|
OID_123456 | de780f34-343c-4898-a1e4-3482c1495092 |
OID_123456 | fb7840f6-9fcc-4602-8a48-559624fbe99b |
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 stateAuthorisedByProvider
- All recurring payments will have the same
merchantTransactionID
and differentpaymentID
s - Refunds have the same
merchantTransactionID
as the original payment (that one the refund was created for) and differentpaymentID
s. This has to be especially considered for partial refunds where it is possible to have more transactions with the samemerchantTransactionID
- 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
, samepaymentID
, samepayment.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
beforeAuthorisedByProvider
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.
Updated over 3 years ago