Validation Errors

Overview

Validation errors will be returned on error result objects when we can't process the API call because parameters are invalid. Validation errors contain the following:

code - for programmatic consumption
message - for human consumption
attribute - the parameter that caused an error

Hierarchy

Errors are returned in a hierarchy that matches the parameter hierarchy. For example, when creating a customer with a credit card and billing address, the credit card is nested under customer, and the billing address under credit card.

PHP

$result = $gateway->customer()->create([
    'email' => 'invalid',
    'creditCard' => [
        'number' => 'invalid',
        'billingAddress' => [
            'countryName' => 'not_a_valid_country'
        ]
    ]
]);

You can get errors at all levels, errors at a specific level, or errors at a specific level on a specific attribute.

All errors on all levels

To get errors on _all levels_, call each on `$result->errors`. You can also check `sizeof($result->errors)` for the number of total errors.

PHP

foreach($result->errors->deepAll() AS $error) {
    print_r($error->code . ": " . $error->message . "\n");
}

Errors at specific levels

To get errors at a _specific level_, use the `forKey` method. The `attribute` will indicate which attribute is invalid.

PHP

foreach($result->errors->forKey('customer')->shallowAll() AS $error) {
    print_r($error->attribute . ": " . $error->code . " " . $error->message . "\n");
}

foreach($result->errors->forKey('customer')->forKey('creditCard')->shallowAll() AS $error) {
    print_r($error->attribute . ": " . $error->code . " " . $error->message . "\n");
}

foreach($result->errors->forKey('customer')->forKey('creditCard')->forKey('billingAddress')->shallowAll() AS $error) {
    print_r($error->attribute . ": " . $error->code . " " . $error->message . "\n");
}

From a _specific level_, you can also get the number of errors at that level using the `sizeof` method.

PHP

sizeof($result->errors->forKey('customer')->shallowAll()); // Number of errors only on customer
sizeof($result->errors->forKey('customer')->forKey('creditCard')->shallowAll()); // Number of errors only on credit card
sizeof($result->errors->forKey('customer')->forKey('creditCard')->forKey('billingAddress')->shallowAll()); // Number of errors only on billing address

Errors on specific attribute

You can also get errors at a specific level on a specific attribute. This is useful if you want to display error messages inline in your forms.

PHP

$result->errors->forKey('customer')->onAttribute('email');
$result->errors->forKey('customer')->forKey('creditCard')->onAttribute('number');
$result->errors->forKey('customer')->forKey('creditCard')->forKey('billingAddress')->onAttribute('countryName');

Base errors

Sometimes validation errors aren't caused by a specific input parameter. For example, canceled subscriptions can't be updated. For these validation errors, we use an attribute named "base" for the validation error.

PHP

$result = $gateway->subscription()->update('the_subscription_id', ['price' => '1.00']);
$baseErrors = $result->errors->forKey('subscription')->onAttribute('base');

Errors on add-ons/discounts

It is possible to add, update and remove many add-ons and discounts at once. If any of the add-ons or discounts contain errors, these errors will be indexed based on the order of the add-on or discount in the request (beginning at 0).

PHP

$result = $gateway->subscription()->create([
    'paymentMethodToken' => 'the_payment_method_token',
    'planId' => 'the_plan_id',
    'addOns' => [
        'update' => [
            [
                'existingId' => 'increase_10',
                'amount' => 'invalid',
            ],
            [
                'existingId' => 'increase_20',
                'quantity' => -10,
            ]
        ]
    ]
]);

$amountErrors = $result->errors->forKey('subscription')->forKey('addOns')->forKey('update')->forIndex(0)->onAttribute('amount');
foreach($amountErrors AS $error) {
    print_r($error->code . ": " . $error->message . "\n");
}

$quantityErrors = $result->errors->forKey('subscription')->forKey('addOns')->forKey('update')->forIndex(1)->onAttribute('quantity');
foreach($quantityErrors AS $error) {
    print_r($error->code . ": " . $error->message . "\n");
}