Handling Payment Form Errors

This page describes the possible errors you may receive after submitting the payment form.

The 'gatewayFormResponse' field will contain an overall indication of success or failure of the submitted form. It is strongly recommended that this field is checked first as this indicates whether individual fields contain errors or if a more general error has occurred.

Overall Form Response

The overall form response will be returned in the 'gatewayFormResponse' field.

It will contain one of the following values:

Value Description Responsive Action
0~OK Indicates the form is valid — returned when no form errors are found indicating that the card details have been collected successfully and are available for use in a transaction. No error handling required — proceed to performing a transaction.
2~Session identifier invalid or closed for updates Indicates invalid session — returned when session has expired, closed for updates, or invalid. Create a new session and redisplay the payment form to the payer to supply card details.
3~Field Errors Indicates one or more fields are in error — returned if any form field fails validation. The fields in error will contain the specific error code. See Field Errors section below for details. Parse individual fields for specific errors. See below for more details.
4~System Error Indicates system error — returned if a Payment Gateway error or other irrecoverable failure occurs. Irrecoverable — contact Commonwealth Bank of Australia to have issue rectified.

Field Errors

Field errors will only be present if the 'gatewayFormResponse' field contains the value '3~Field Errors'.

The value returned for an erroneous field will have the following format:

  • E~V where E is the error code and V is the submitted value.

Where E will be one of the following values:

Value Description Responsive action
1~ Indicates mandatory field not present — returned when the field value is blank/empty. This will also occur if the field is not included in the submitted form. Redisplay the payment form with an error against the erroneous field to allow the payer to rectify and resubmit.
2~submittedFieldValue Indicates field value invalid — returned when the field value is considered invalid as per Hosted Payment Session field validation rules. Redisplay the payment form with an error against the erroneous field to allow the payer to rectify and resubmit.
Valid fields will not contain an error code, only the value (or its masked variant) will be returned.

Copyright © 2020 Commonwealth Bank of Australia