Payment Notification (callback_notification)

The notification callback is utilised when we need to notify your system, but without the customer being present.

Unlike the OK, Fail and Open callbacks, any output returned by the notification callback is discarded, as this happens without the customer being a part of the payment flow.

This callback allows you to update your own system and perform lightweight processing, e.g. email the user.

Notification Callback Triggers

  • A payment cannot be completed immediately. In such cases, the result is posted to the open page (callback_open), and when the request is later processed, a notification is sent to the notification page (callback_notification). An example of this is PayPal doing a fraud check, or Klarna performing an asynchronous credit check.
  • A customer leaves the payment flow, and the OK page or open pages are never called. An example of this iDEAL payments, where the customer may not return from the bank, whereby us not being able to trigger the Callback OK.
    • For some payment methods we will always trigger the notification callback, also if the Callback OK is triggered. An example of this is MobilePay.
  • A chargeback occurs. These will have a status of "ChargebackEvent". This is mainly used if you want to automate the handling of chargebacks.
  • The status parameter is missing "ChargebackEvent" (only relevant for notification callbacks).

Integration Best Practice

  • Due to the asynchronous nature of the notification, it can't be guaranteed to be sent in a specific order regarding any other type of callback.
  • You should always rely on both OK/Fail and Notification callbacks to keep your system up to date.
  • The notification has a timeout of 5 seconds. Do not perform any heavy processing as part of the notification call that might delay your response.
  • Do not perform payment operations during a notification. This could cause payment deadlocks.

Notification Details

The parameters for the notification page are identical to those for the callback_ok or callback_fail pages, depending on whether the payment request was successful, or failed.

All of the POST/GET parameters (except checksum) are available as XML in the xml parameter, and you are recommended to rely on the xml parameter for processing business logic.

Parameter Description Type
status

The status of the transactions: 

Status Description
error An error occurred.
failed The payment was declined.
succeeded The payment was authenticated
cancelled The payment was canceled
open The payment is pending an update from the payment provider
incomplete The payment flow has not yet been completed
PartialSuccess The payment request was partially completed successfully, that is, only part of the requested amount was authorized/captured.For more information, see initiateGiftCardPayment.
String
error_message A fallback error message that is safe to display to your customers. You are recommended to always display your own, custom error message, providing your customer with more details about the error, and only use this error message as a fallback mechanism. You must include the message for Klarna payments , or if the cardholder_message_must_be_shown return parameter is true. String
merchant_error_message An error message for the merchant's eyes only, but provides more detail as to what went wrong (This is only sent to the FAIL-callback page). String
cardholder_message_must_be_shown An indicator on whether the card holder error message must be shown to your customer. boolean
shop_orderid

This is the internal ID of the order in your webshop.

In most integrations, you can use the same order ID for up to four orders. For PayPal and MobilePay payments, you can only use it for a singe successful transaction. The shop_orderid value is posted back to you, so you know the order to which the payment refers.

 [a-zA-Z0-9-]{1,100}
transaction_id

The ID of the transaction. This should be stored if you are going to capture/cancel the order directly from your system, for example, for capturing reservations using the captureReservation method.

[0-9a-f]{1-32}
type

The authorisation type of the payment, for example, "payment"/"paymentAndCapture"/"subscription"

 String
payment_status

The status of the transaction, depending on the payment method, for example, preauth,recurring_confirmed, captured, etc.

String
masked_credit_card

The masked primary account number of the credit card, which contains the maximum number of digits allowed to share with a non-PCI compliant merchant.

String
blacklist_token

A unique token you can use for blacklisting a credit card. This token can be used to build up a black list of credit cards. The token is only returned if this is a credit card payment.

 [0-9a-f]{41}
credit_card_token

This is the unique credit card token value that identifies a credit card within the AltaPay Payment Gateway. This token can be used later with the Merchant API or with creditcard token ordering so that the customer does not need to enter credit card details in their next order. The token is only returned for credit card payments.

 [0-9a-f]{41}
nature

The payment method:

  • Wallet
  • EPayment
  • CreditCard
  • BankPayment
  • IdealPayment
  • Invoice
  • CreditCardWallet
  • GiftCard
  • Mobile
 String
require_capture

Indicates whether a transaction was just reserved, and subsequently needs to be captured. For example, if a credit card payment has the authorisation type "payment", this value is true, but if the authorisation type is paymentAndCapture, this value is false, because the transaction has already been captured.

boolean
xml

Contains the XML response of the API call. This is the parameter from which to design the business logic. For detailed information about the XML response from API calls, see API Response structure (XML).

 String
checksum

If the Customer Information Shared Secret field is set under Home > Terminal Settings in the Merchant Information Interface, the checksum can be used to authenticate the origin of a request, to counter "man in the middle" attacks.

The checksum is calculated based on these parameters:

  • amount
  • currency
  • orderid
  • secret

For more information, see Checksum Calculation.

 String

 

If fraud detection is available for the payment we also post back the following parameters.

Parameter Description Type
fraud_risk_score

This is the probability that the transaction is a fraud attempt, and should be read in context of the FraudExplanation and the FraudRecommendation. For example a fraud risk score of 13.37 means there is a 13.37% chance of this order being fraud. Only MaxMind utilizes the fraud score. For ReD, the value is always -1.

 float
fraud_explanation Contains a detailed explanation of the fraud risk evaluation. Only relevant for MaxMind. For ReD it contains the value of the recommendation. string
fraud_recommendation

The recommendation from the fraud detection service provider. For example:

  • Accept: The order does not appear to be fraudulent, and you should deliver the goods or services.
  • Deny: The order appears to be fraudulent, and you should not deliver the goods or services.
  • Challenge: Something about the order is questionable. You should review the order manually before making a decision. For ReD, Challenge is only supported for bespoke setups. If you are using the ReD Sector model, Challenge is not available.
  • Unknown: There is no recommendation available, either because of insufficient information, or an underlying service was unavailable, for example, there was no response from ReD.
    • Unknown is also returned for declined transaction.
String

 

If address verification is enabled for the payment, the following parameters are also posted to the callback page: 

Parameter Description Type
avs_code The address verification result code. For more information, see Address verification parameters. A-Z
avs_text The description of the address verification result code. For more information, see Address verification parameters. String