Payment OK Page (callback_ok)

When a payment request is processed by the gateway, the result is typically Success, Failure, or Open:

  • Success. The payment request was successfully processed. The result is posted to the OK page (callback_ok)
  • Failure. The payment request failed. The result is posted to the fail page (callback_fail)
  • Open. If a payment request cannot be completely processed immediately, the result is posted to the open page (callback_open).
    • When the request is later processed, a notification is sent to the notification page (callback_notification).

Depending on the payment state, we will provide payment information to the appropriate callback page. The content returned by these callbacks can be displayed to the customer, allowing you to display a message about his or her purchase.

The following parameters are used for the callback_ok page.

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

For more information, see Settings for the Payment OK page (callback_ok).