NAME

Business::CyberSource - Perl interface to the CyberSource Simple Order SOAP API

VERSION

version 0.010008

DESCRIPTION

This library is a Perl interface to the CyberSource Simple Order SOAP API built on Moose and XML::Compile::SOAP technologies. This library aims to eventually provide a full interface the SOAPI.

You may wish to read the Official CyberSource Documentation on Credit Card Services for the Simpler Order API as it will provide further information on why what some things are and the general workflow.

To get started you will want to read the documentation in Business::CyberSource::Client and Business::CyberSource::Request. If you find any documentation unclear or outright missing, please file a bug.

If there are features that are part of CyberSource's API but are not documented, or are missing here, please file a bug. I'll be happy to add them, but due to the size of the upstream API, I have not had time to cover all the features and some are currently undocumented.

ENVIRONMENT

Debugging

Supports MooseY::RemoteHelper::Role::Clients REMOTE_CLIENT_DEBUG variable. This can be set to either 0, 1, 2, for varying levels of verbosity.

Testing

all environment variables are prefixed with PERL_BUSINESS_CYBERSOURCE_

Credentials

USERNAME

PASSWORD

set's the username and password in the client for running tests.

Direct Currency Conversion

DCC_CC_YYYY

sets the test credit card expiration year for both Visa and MasterCard

DCC_CC_MM

sets the test credit card expiration month for both Visa and MasterCard

DCC_MASTERCARD

A test credit card number provided by your your credit card processor

DCC_VISA

A test credit card number provided by your your credit card processor

EXAMPLE

In the example, carp means you should log something Dumper means you should log it with lots of detail. Safe::Isa is used because you should either use it or check for blessed it is always possible that somewhere in the stack someone is using die on a string.

        use 5.010;
        use Carp;
        use Try::Tiny;
        use Safe::Isa;
        use Data::Printer alias => 'Dumper';

        use Business::CyberSource::Client;
        use Business::CyberSource::Request::Authorization;
        use Business::CyberSource::Request::Capture;
        # exception namepsace
        my $e_ns = 'Business::CyberSource::Exception';

        my $client = Business::CyberSource::Client->new({
                user  => 'Merchant ID',
                pass  => 'API Key',
                test  => 1,
                debug => 1, # do not set in production as it prints sensative
                         # information
        });

        my $auth_request;
        try {
                $auth_request
                        = Business::CyberSource::Request::Authorization->new({
                                reference_code => '42',
                                bill_to => {
                                        first_name  => 'Caleb',
                                        last_name   => 'Cushing',
                                        street1     => '100 somewhere st',
                                        city        => 'Houston',
                                        state       => 'TX',
                                        postal_code => '77064',
                                        country     => 'US',
                                        email       => 'xenoterracide@gmail.com',
                                },
                                purchase_totals => {
                                        currency => 'USD',
                                        total    => 5.00,
                                        discount => 0.03, # optional and may depend on processor
                                        duty     => 0.01, # optional and may depend on processor
                                },
                                card => {
                                        account_number => '4111111111111111',
                                        expiration => {
                                                month => 9,
                                                year  => 2025,
                                        },
                                },
                        });
        }
        catch {
                my $e = $_;
                if ( $e->$_does('Business::CyberSource::Response::Role::Base')) {
                        carp $e->reason_code . $e->reason_text;
                }
                elsif ( $e->$_isa( $e_ns . '::SOAPFault'  ) ) {
                        carp $e->faultcode . $e->faultstring;
                }
                elsif ( $e->$_isa( $e_ns ) || $e->$_isa( 'Moose::Exception' ) ) {
                        Dumper( $e );
                        ## probably your payload was bad, check type more
                        ## specifically and feed good error messages to your
                        ## customer
                }
                else { # probably a coding error
                        Dumper( $e );
                }
        };
        return unless $auth_request;

        my $auth_response;
        try {
                $auth_response = $client->submit( $auth_request );
        }
        catch {
                carp $_;
        };
        return unless $auth_response;

        unless( $auth_response->is_accept ) {
                carp $auth_response->reason_text;
        }
        else {
                my $capture_request
                        = Business::CyberSource::Request::Capture->new({
                                reference_code => $auth_response->reference_code,
                                service => {
                                        request_id => $auth_response->request_id,
                                },
                                purchase_totals => {
                                        total    => $auth_response->auth->amount,
                                        discount => '0.05', # optional and may depend on processor
                                        duty     => '0.01', # optional and may depend on processor
                                        currency => $auth_response->purchase_totals->currency,
                                },
                        });

                my $capture_response;
                try {
                        $capture_response = $client->submit( $capture_request );
                }
                catch {
                        my $e = $_;
                        if ( $e->$_does('Business::CyberSource::Response::Role::Base') )
                                carp $e->reason_code . $e->reason_text;
                        }
                        elsif ( $e->$_isa( $e_ns . '::SOAPFault'  ) ) {
                                carp $e->faultcode . $e->faultstring;
                        }
                        elsif ( $e->$_isa( $e_ns ) || $e->$_isa( 'Moose::Exception' ) ) {
                                Dumper( $e );
                                ## probably your payload was bad, check type more
                                ## specifically and feed good error messages to your
                                ## customer
                        }
                        else { # probably a coding error
                                Dumper( $e );
                        }
                };
                return unless $capture_response;

                if ( $capture_response->is_accept ) {
                        # you probably want to record this
                        say $capture_response->capture->reconciliation_id;
                }
        }

This code is not meant to be DRY, but more of a top to bottom example. Also note that if you really want to do Authorization and Capture at one time use a Sale. Most common Reasons for Exceptions would be bad input into the request object (which validates things) or CyberSource just randomly throwing an ERROR, in which case you can usually just retry later. You don't have to print the response on error during development, you can easily just use the REMOTE_CLIENT_DEBUG Environment variable.

ACKNOWLEDGMENTS

SEE ALSO

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/hostgator/business-cybersource/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

CONTRIBUTORS

  • bvoskr <boris.voskresenskiy@endurance.com>

  • Carl Carstenson <ccarstenson@hostgator.com>

  • Carl Lantz <carl.lantz@endurance.com>

  • dmaestro <dmaestro@users.noreply.github.com>

  • irinatodeva <irinatodeva@users.noreply.github.com>

  • Jonathan William Taylor <elderling@gmail.com>

  • Jonathan William Taylor <jonathan.taylor@endurance.com>

  • Robert Stone <robertstone@hostgator.com>

  • Rummy <cerealbh@gmail.com>

AUTHOR

Caleb Cushing <xenoterracide@gmail.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by Caleb Cushing <xenoterracide@gmail.com>.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)