SYNOPSIS

        use Business::AuthorizeNet::CIM;
        use Data::Dumper;
    
        my $cim = Business::AuthorizeNet::CIM->new( login => $cfg{login}, transactionKey => $cfg{password} );
    
        my @ProfileIds = $cim->getCustomerProfileIds();
        foreach my $id (@ProfileIds) {
            my $d = $cim->getCustomerProfile($id);
            print Dumper(\$d);
        }

DESCRIPTION

    Authorize.Net Customer Information Manager (CIM) Web Services API
    features are described at
    http://developer.authorize.net/api/reference/features/customer_profiles.html,
    the API reference is at
    http://developer.authorize.net/api/reference/#customer-profiles.
    Another useful (but deprecated) reference is
    http://www.authorize.net/support/CIM_XML_guide.pdf, and the reference
    XML schema is at
    https://api.authorize.net/xml/v1/schema/AnetApiSchema.xsd.

 METHODS

  new

        my $cim = Business::AuthorizeNet::CIM->new(
            login => $cfg{login},
            transactionKey => $cfg{password}
        );

      * login

      The valid API Login ID for the developer test or merchant account

      * transactionKey

      The valid Transaction Key for the developer test or merchant account

      * debug

      * test_mode

      validationMode as testMode or liveMode

      * test_host_only

      use test api host and keep default validationMode

      * ua_args

      passed to LWP::UserAgent

      * ua

      LWP::UserAgent or WWW::Mechanize instance

  createCustomerProfile

    Create a new customer profile along with any customer payment profiles
    and customer shipping addresses for the customer profile.

        $cim->createCustomerProfile(
            refId => $refId, # Optional
    
            # one of 'merchantCustomerId', 'description', 'email' is required
            merchantCustomerId => $merchantCustomerId,
            description => $description,
            email => $email,
    
            customerType => $customerType, # Optional
    
            billTo => { # Optional, all sub items are Optional
                firstName => $firstName,
                lastName  => $lastName,
                company   => $company,
                address   => $address,
                city      => $city,
                state     => $state,
                zip       => $zip,
                country   => $country,
                phoneNumber => $phoneNumber,
                faxNumber => $faxNumber
            },
    
            # or it uses shipToList address as billTo
            use_shipToList_as_billTo => 1,
    
            creditCard => { # required when the payment profile is credit card
                cardNumber => $cardNumber,
                expirationDate => $expirationDate, # YYYY-MM
                cardCode => $cardCode,  # Optional
            },
    
            bankAccount => { # required when the payment profile is bank account
                accountType => $accountType, # Optional, one of checking, savings, businessChecking
                routingNumber => $routingNumber,
                accountNumber => $accountNumber,
                nameOnAccount => $nameOnAccount,
                echeckType => $echeckType, # Optionaal, one of CCD, PPD, TEL, WEB
                bankName   => $bankName, # Optional
            },
    
            # opaqueData is required when using the Authorize.Net's Accept.js approach.
            # Note: Testing so far has indicatated that for new customer profiles using opaqueData,
            #       the "billTo" section has been required to be present or a "bank validation error"
            #       has been thrown. This same behavior has not been noticed when creating an empty
            #       customer profile and then adding a payment profile to it.
            opaqueData => {
                dataDescriptor => $dataDescriptor, # Required, for Accept.js use COMMON.ACCEPT.INAPP.PAYMENT, see documentation for others
                dataValue      => $dataValue, # Required, a one-time base64 encoded, encrypted payment data
            },
    
            shipToList => {
                firstName => $firstName,
                lastName  => $lastName,
                company   => $company,
                address   => $address,
                city      => $city,
                state     => $state,
                zip       => $zip,
                country   => $country,
                phoneNumber => $phoneNumber,
                faxNumber => $faxNumber
            },
    
            # or it uses billTo address as shipToList
            use_billTo_as_shipToList => 1,
    
        );

  createCustomerPaymentProfileRequest

    Create a new customer payment profile for an existing customer profile.
    You can create up to 10 payment profiles for each customer profile.

        $cim->createCustomerPaymentProfileRequest(
            customerProfileId => $customerProfileId, # required
    
            refId => $refId, # Optional
    
            customerType => $customerType, # Optional
            billTo => { # Optional, all sub items are Optional
                firstName => $firstName,
                lastName  => $lastName,
                company   => $company,
                address   => $address,
                city      => $city,
                state     => $state,
                zip       => $zip,
                country   => $country,
                phoneNumber => $phoneNumber,
                faxNumber => $faxNumber
            },
    
            creditCard => { # required when the payment profile is credit card
                cardNumber => $cardNumber,
                expirationDate => $expirationDate, # YYYY-MM
                cardCode => $cardCode,  # Optional
            },
            bankAccount => { # required when the payment profile is bank account
                accountType => $accountType, # Optional, one of checking, savings, businessChecking
                routingNumber => $routingNumber,
                accountNumber => $accountNumber,
                nameOnAccount => $nameOnAccount,
                echeckType => $echeckType, # Optionaal, one of CCD, PPD, TEL, WEB
                bankName   => $bankName, # Optional
            },
    
            opaqueData => { # required when using the Authorize.Net's Accept.js approach.
                dataDescriptor => $dataDescriptor, # Required, for Accept.js use COMMON.ACCEPT.INAPP.PAYMENT, see documentation for others
                dataValue      => $dataValue, # Required, a one-time base64 encoded, encrypted payment data
            },
        );

  createCustomerShippingAddressRequest

    Create a new customer shipping address for an existing customer
    profile. You can create up to 100 customer shipping addresses for each
    customer profile.

        $cim->createCustomerShippingAddressRequest(
            customerProfileId => $customerProfileId, # required
    
            refId => $refId, # Optional
    
            firstName => $firstName,
            lastName  => $lastName,
            company   => $company,
            address   => $address,
            city      => $city,
            state     => $state,
            zip       => $zip,
            country   => $country,
            phoneNumber => $phoneNumber,
            faxNumber => $faxNumber
        );

  createCustomerProfileTransaction

    Create a new payment transaction from an existing customer profile.

        $cim->createCustomerProfileTransaction(
            'profileTransAuthCapture', # or others like profileTransAuthOnly
    
            refId => $refId, # Optional, reference id
    
            amount => $amount,
            tax => { # Optional
                amount => $tax_amount,
                name   => $tax_name,
                description => $tax_description
            },
            shipping => { # Optional
                amount => $tax_amount,
                name   => $tax_name,
                description => $tax_description
            },
            duty => { # Optional
                amount => $tax_amount,
                name   => $tax_name,
                description => $tax_description
            },
    
            lineItems => [ { # Optional
                itemId => $itemId,
                name => $name,
                description => $description,
                quantity => $quantity,
                unitPrice => $unitPrice,
                taxable => $taxable,
            } ],
    
            customerProfileId => $customerProfileId,
            customerPaymentProfileId => $customerPaymentProfileId,
            customerShippingAddressId => $customerShippingAddressId,
    
            extraOptions => $extraOptions, # Optional
    
            ### Only required for profileTransPriorAuthCapture: For Prior Authorization and CaptureTransactions
            ### and profileTransRefund: For Refund Transactions
            ### and profileTransVoid: For Void Transactions
            transId => $transId,
    
            ### Only partly required for profileTransRefund: For Refund Transactions
            creditCardNumberMasked => $creditCardNumberMasked,
            bankRoutingNumberMasked => $bankRoutingNumberMasked,
            bankAccountNumberMasked => $bankAccountNumberMasked,
    
            ### rest are not for profileTransPriorAuthCapture
            order => { # Optional
                invoiceNumber => $invoiceNumber,
                description => $description,
                purchaseOrderNumber => $purchaseOrderNumber,
            },
            taxExempt => 'true', # optional
            recurringBilling => 'false', # optional
            cardCode => $cardCode, # Required only when the merchant would like to use the Card Code Verification (CCV) filter
            splitTenderId => $splitTenderId, # Required for second and subsequent transactions related to a partial authorizaqtion transaction.
    
            #### ONLY required for profileTransCaptureOnly: the Capture Only transaction type.
            approvalCode => $approvalCode,
        );

    The first argument can be one of

      * profileTransAuthOnly

      For Authorization Only Transactions

      * profileTransAuthCapture

      For Authorization and Capture Transactions

      * profileTransCaptureOnly

      For Capture Only Transactions

      * profileTransPriorAuthCapture

      For Prior Authorization and CaptureTransactions

      * profileTransRefund

      For Refund Transactions

      * profileTransVoid

      For Void Transactions

          $cim->createCustomerProfileTransaction(
              'profileTransVoid', # or others like profileTransAuthOnly
      
              refId => $refId, # Optional, reference id
      
              customerProfileId => $customerProfileId,
              customerPaymentProfileId => $customerPaymentProfileId,
              customerShippingAddressId => $customerShippingAddressId,
      
              extraOptions => $extraOptions, # Optional
      
              transId => $transId,
          );

  deleteCustomerProfile

    Delete an existing customer profile along with all associated customer
    payment profiles and customer shipping addresses.

        $cim->deleteCustomerProfile($customerProfileId);

  deleteCustomerPaymentProfileRequest

    Delete a customer payment profile from an existing customer profile.

        $cim->deleteCustomerPaymentProfileRequest($customerProfileId, $customerPaymentProfileId);

  deleteCustomerShippingAddressRequest

    Delete a customer shipping address from an existing customer profile.

        $cim->deleteCustomerShippingAddressRequest($customerProfileId, $customerAddressId);

  getCustomerProfileIds

    Retrieve all customer profile IDs you have previously created.

        my @ProfileIds = $cim->getCustomerProfileIds;

  getCustomerProfile

    Retrieve an existing customer profile along with all the associated
    customer payment profiles and customer shipping addresses.

        $cim->getCustomerProfile($customerProfileId);

  getCustomerPaymentProfileRequest

    Retrieve a customer payment profile for an existing customer profile.
    Optionally, a hash reference of additonal arguments may be passed in,
    and will be added to the request.

        $cim->getCustomerPaymentProfileRequest($customerProfileId, $customerPaymentProfileId, {
            includeIssuerInfo    => 'true',
            unmaskExpirationDate => 'true',
        });

  getCustomerShippingAddressRequest

    Retrieve a customer shipping address for an existing customer profile.

        $cim->getCustomerShippingAddressRequest($customerProfileId, $customerAddressId);

  getHostedProfilePageRequest

    Get a token for use in a CIM hosted popup.

        my $result = $cim->getHostedProfilePageRequest(
            customerProfileID,
        {
            hostedProfileReturnUrl         => 'http://example.com/foo',
            hostedProfileReturnUrlText     => 'Return home',
            hostedProfilePageBorderVisible => 'true',
            hostedProfileHeadingBgColor    => '#000',
            hostedProfileIFrameCommunicatorUrl =>
                'https://example.com/communicate',
            hostedProfileValidationMode         => 'testMode',
            hostedProfileBillingAddressRequired => 'true',
            hostedProfileCardCodeRequired       => 'true',
        }
    
        );
        print $result->{token} if $result->{messages}->{resultCode} eq 'Ok';

  updateCustomerProfile

    Update an existing customer profile

        $cim->updateCustomerProfile(
            customerProfileId => $customerProfileId,
    
            refId => $refId, # Optional
    
            merchantCustomerId => $merchantCustomerId,
            description => $description,
            email => $email
        );

  updateCustomerPaymentProfile

    Update a customer payment profile for an existing customer profile.

        $cim->updateCustomerPaymentProfile(
            customerProfileId => $customerProfileId,
            customerPaymentProfileId => $customerPaymentProfileId,
    
            refId => $refId, # Optional
    
            customerType => $customerType, # Optional
            billTo => { # Optional, all sub items are Optional
                firstName => $firstName,
                lastName  => $lastName,
                company   => $company,
                address   => $address,
                city      => $city,
                state     => $state,
                zip       => $zip,
                country   => $country,
                phoneNumber => $phoneNumber,
                faxNumber => $faxNumber
            },
    
            creditCard => { # required when the payment profile is credit card
                cardNumber => $cardNumber,
                expirationDate => $expirationDate, # YYYY-MM
                cardCode => $cardCode,  # Optional
            },
            bankAccount => { # required when the payment profile is bank account
                accountType => $accountType, # Optional, one of checking, savings, businessChecking
                routingNumber => $routingNumber,
                accountNumber => $accountNumber,
                nameOnAccount => $nameOnAccount,
                echeckType => $echeckType, # Optionaal, one of CCD, PPD, TEL, WEB
                bankName   => $bankName, # Optional
            },
            opaqueData => { # required when using the Authorize.Net's Accept.js approach.
                dataDescriptor => $dataDescriptor, # Required, for Accept.js use COMMON.ACCEPT.INAPP.PAYMENT, see documentation for others
                dataValue      => $dataValue, # Required, a one-time base64 encoded, encrypted payment data
            },
        );

  updateCustomerShippingAddress

    Update a shipping address for an existing customer profile.

        $cim->updateCustomerShippingAddress(
            customerProfileId => $customerProfileId,
            customerAddressId => $customerAddressId,
    
            refId => $refId, # Optional
    
            firstName => $firstName,
            lastName  => $lastName,
            company   => $company,
            address   => $address,
            city      => $city,
            state     => $state,
            zip       => $zip,
            country   => $country,
            phoneNumber => $phoneNumber,
            faxNumber => $faxNumber
        );

  updateSplitTenderGroupRequest

    Update the status of a split tender group (a group of transactions,
    each of which pays for part of one order).

        $cim->updateSplitTenderGroupRequest($splitTenderId, $splitTenderStatus);
        # splitTenderStatus can be voided or completed.

  validateCustomerPaymentProfile

    Verify an existing customer payment profile by generating a test
    transaction.

        $cim->validateCustomerPaymentProfile(
            customerProfileId => $customerProfileId,
            customerPaymentProfileId => $customerPaymentProfileId,
            customerShippingAddressId => $customerShippingAddressId,
    
            cardCode => $cardCode, # Optional
        );

 Transaction Reporting

    Authorize.Net has a section of the CIM API for reporting on
    transactions. This section of the API must be enabled for the merchant
    in the portal.

      http://developer.authorize.net/api/reference/features/transaction_reporting.html
      https://developer.authorize.net/api/reference/index.html#transaction-reporting

  Paging and Sorting Options

    API methods that return lists are paged, and the default page size is
    the maximum (1000 records). However, sorting and paging options can be
    provided, as described in Authorize.Net's api documentation. Sorting
    and paging can be independently provided, but each requires that both
    its key-value pairs be specified.

      sorting => { orderBy => 'id', orderDescending => 'false' },
      paging  => { limit => 100, offset => 1 },

    N.B. offsets begin at 1.

  getMerchantDetailsRequest

    returns details about the merchant (payment methods, currencies, et
    al).

      https://developer.authorize.net/api/reference/index.html#transaction-reporting-get-merchant-details
    
        my $resp = $cim->getMerchantDetailsRequest;

  getTransactionDetailsRequest

    Return details about a specific transaction: status, payment method,
    auth and settled amounts, settle date, profile ids, et al. transId is
    required.

      https://developer.authorize.net/api/reference/index.html#transaction-reporting-get-transaction-details
    
        my $resp = $cim->getTransactionDetailsRequest(
            transId => $transId,
            refId   => $refId,    # Optional
        );

  getTransactionListForCustomerRequest

    Get transactions for a specific customer profile or customer payment
    profile. customerProfileId is required. If the payment profile id is
    omitted, transactions for all payment profiles belonging to that
    customer are returned. Paging and sorting options can be specified.

        my $resp = $cim->getTransactionListForCustomerRequest(
            customerProfileId        => $customerProfileId,
            customerPaymentProfileId => $customerPaymentProfileId,  # Optional
    
            refId   => $refId,    # Optional
        );

  getUnsettledTransactionListRequest

    Get data for unsettled transactions. No parameters are required. Paging
    and sorting options can be specified.

        my $resp = $cim->getUnsettledTransactionListRequest(
            refId   => $refId,    # Optional
        );

  getSettledBatchListRequest

    returns Batch ID, Settlement Time, & Settlement State for all settled
    batches with a range of dates. If you specify includeStatistics, you
    also receive batch statistics by payment type and batch totals. All
    inputs are optional.

        my $resp = $cim->getSettledBatchListRequest(
            includeStatistics => 'true',                   # Optional
            firstSettlementDate => '2010-09-21T16:00:00',  # Optional
            lastSettlementDate  => '2010-10-01T00:00:00',  # Optional
        );

  getTransactionListRequest

    Returns data for transactions in a specified batch. batchId is required
    input. Paging and sorting options can be specified.

        my $resp = $cim->getTransactionListRequest(
            batchId => $batchId,
            refId   => $refId,    # Optional
        );