Authorization

You may wish not to charge a customer, but only to authorize their card. This is quite useful in various scenarios, for example:

  • getting the card number when a customer signs up for a free trial (you can charge them later automatically),
  • checking the credit card (for example whether online transactions are not blocked),
  • confirming the card when a customer creates an account in your e-store (for example if you wish to allow Card Data Storage).

Authorizing a card means blocking a specific amount for some time on the customer’s card. You can either block the whole amount (and capture the funds later) or you can block just $1 (or €1, or £1, or…) just to verify the card.

Start with preparing data required to perform the authorization. Note that the data comes in exactly the same format as when performing a regular transaction. You can choose whether to authorize for just one euro, dollar, pound (or any other currency), or for the whole amount (if you’re planning to capture the funds later).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
$card_params = array(
    'sale' => array(
        'amount'      => 1.00,
        'currency'    => 'EUR',
        'description' => 'Product #1'
    ),
    'customer' => array(
        'name'    => 'John Doe',
        'email'   => 'john@doe.com',
        'ip'      => '127.0.0.1',
        'address' => array (
             'street_house' => '1600 Pennsylvania Avenue Northwest',
            'city'          => 'Washington',
            'state'         => 'DC',
            'zip'           => '500',
            'country_code'  => 'US',
        ),
    ),
    'card' => array(
        'token' => '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4',
     ),
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
card_params = {
    'sale' => {
        'amount'      => 19.99,
        'currency'    => 'EUR',
        'description' => 'Product #1',
    },
    'customer' => {
        'name'    => 'John Doe',
        'email'   => 'john@doe.com',
        'ip'      => '127.0.0.1',
        'address' => {
            'street_house' => '1600 Pennsylvania Avenue Northwest',
            'city'         => 'Washington',
            'state'        => 'DC',
            'zip'          => '500',
            'country_code' => 'US'
        }
    },
    'card' => {
        'token' => '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4'
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
card_params = {
  'sale' : {
    'amount'      : 19.99,
    'currency'    : 'EUR',
    'description' : 'Product #1'
  },
  'customer' : {
    'name'    : 'John Doe',
    'email'   : 'john@doe.com',
    'ip'      : '127.0.0.1',
    'address' : {
      'street_house' : '1600 Pennsylvania Avenue Northwest',
      'city'         : 'Washington',
      'state'        : 'DC',
      'zip'          : '500',
      'country_code' : 'US'
    }
  },
  'card' : {
    'token' : '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4'
  }
}
1
2
3
4
Sale sale = new Sale(19.99, "EUR", "Product #1");
Address address = new Address("1600 Pennsylvania Avenue Northwest", "Washington", "DC", "500", "US");
Customer customer = new Customer("John Doe", "john@doe.com", "127.0.0.1", address);
Card card = new Card("4111111111111111", "03", "2017", "John Doe", "123");

Having the data prepared, simply call the cardAuthorizationByToken method (just like you would do with the cardSale method).

You can also easily check whether the authorization was successful and retrieve the ID number (as presented below) – you can use it later to perform resales within the recurring payments or the Card Data Storage.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
try {
    $status = $client->cardAuthorizationByToken($card_params);
} catch (Exception $e) {
    // handle exceptions here
}

// checking authorization status example (optional):
if ($client->isSuccess()) {
    echo "Success, id_authorization: {$status['id_authorization']} \n";
} else {
    die("Error ID: {$status['error']['id_error']}, \n".
        "Error number: {$status['error']['error_number']}, \n".
        "Error description: {$status['error']['error_description']}");
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
begin
    status = client.card_authorization_by_token(card_params)
rescue PayLane::ClientError => e
    # handle exceptions here
end

# checking authorization status example (optional):
if client.success?
    puts "Success, id_authorization: #{status["id_authorization"]}"
else
    puts "Error ID: #{status["error"]["id_error"]}, \n"\
         "Error number: #{status["error"]["error_number"]}, \n"\
         "Error description: #{status["error"]["error_description"]}"
    exit
end
1
2
3
4
5
6
7
8
9
10
11
12
try:
    status = client.card_authorization_by_token(card_params)
except Exception, e:
    # handle exceptions here

# checking authorization status example (optional):
if client.is_success():
    print 'Success, id_authorization: %s' % status['id_authorization']
else:
    sys.exit('Error ID: ' + str(status["error"]["id_error"]) + '\n' \
             'Error number: ' + str(status["error"]["error_number"]) + '\n' \
             'Error description: ' + str(status["error"]["error_description"]))
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
api.cardAuthorization(sale, customer, card, new Callback<AuthorizationResult>() {

    @Override
    public void onFinish(AuthorizationResult result) {
        // success
    }

    @HandleException
    public void onProtocolError(ProtocolException e) {
        // invoke if not success
        // e.getCode() - error code
        // e.getMessage() - error message
    }

    @Override
    public void onError(Exception e) {
        // connection error etc.
    }
});