NAME

    Business::BalancedPayments - Balanced Payments API bindings

VERSION

    version 1.0400

SYNOPSIS

        use Business::BalancedPayments;
    
        my $bp = Business::BalancedPayments->client(secret => 'abc123');
    
        my $customer = $bp->create_customer;
    
        my $card = $bp->create_card({
            card_number      => '5105105105105100',
            expiration_month => 12,
            expiration_year  => 2020,
            security_code    => 123,
        });
    
        $bp->add_card($card, customer => $customer);

DESCRIPTION

    This module provides bindings for the Balanced
    <https://www.balancedpayments.com> API.

METHODS

    The client methods documented here are for v1.1 of the Balanced API
    https://docs.balancedpayments.com/1.1/api. See
    Business::BalancedPayments::V10 for the v1.0 methods.

    For the get_* methods, the $id param can be the id of the resource or a
    uri. For example, the following two lines are equivalent:

        $bp->get_card('CC6J123');
        $bp->get_card('/cards/CC6J123');

 client

        my $bp = Business::BalancedPayments->client(
            secret  => $secret,
            version => 1.1,     # optional, defaults to 1.1
            logger  => $logger, # optional
            retries => 3,       # optional
        );

    Returns a new Balanced client object. Parameters:

    secret

      Required. The Balanced Payments secret key for your account.

    version

      Optional. Defaults to '1.1'. The only supported versions currently
      are '1.0' and '1.1'. Note that version '1.0' was officially
      deprecated March 2014.

    See WebService::Client for other supported parameters such as logger,
    retries, and timeout.

 get_card

        get_card($id)

    Returns the card for the given id.

    Example response:

        {
          'id' => 'CC6J',
          'href' => '/cards/CC6J',
          'address' => {
            'city' => undef,
            'country_code' => undef,
            'line1' => undef,
            'line2' => undef,
            'postal_code' => undef,
            'state' => undef
          },
          'avs_postal_match' => undef,
          'avs_result' => undef,
          'avs_street_match' => undef,
          'bank_name' => 'BANK OF HAWAII',
          'brand' => 'MasterCard',
          'can_credit' => 0,
          'can_debit' => 1,
          'category' => 'other',
          'created_at' => '2014-09-21T05:55:17.564617Z',
          'cvv' => undef,
          'cvv_match' => undef,
          'cvv_result' => undef,
          'expiration_month' => 12,
          'expiration_year' => 2020,
          'fingerprint' => 'fc4c',
          'is_verified' => $VAR1->{'cards'}[0]{'can_debit'},
          'links' => { 'customer' => undef },
          'meta' => {},
          'name' => undef,
          'number' => 'xxxxxxxxxxxx5100',
          'type' => 'credit',
          'updated_at' => '2014-09-21T05:55:17.564619Z'
        }

 create_card

        create_card($card)

    Creates a card. Returns the card card that was created.

    Example:

        my $card = $bp->create_card({
            number           => '5105105105105100',
            expiration_month => 12,
            expiration_year  => 2020,
        });

 add_card

        add_card($card, customer => $customer);

    Associates a card with a customer. It expects a card hashref, such as
    one returned by "get_card", and a customer hashref, such as one
    returned by "get_customer". Returns the card.

    Example:

        my $customer = $bp->create_customer;
        my $card = $bp->get_card($card_id);
        $bp->add_card($card, customer => $customer);

 get_customer

        get_customer($id)

    Returns the customer for the given id.

    Example response:

        {
          'address' => {
            'city' => undef,
            'country_code' => undef,
            'line1' => undef,
            'line2' => undef,
            'postal_code' => undef,
            'state' => undef
          },
          'business_name' => undef,
          'created_at' => '2014-10-02T07:59:26.311760Z',
          'dob_month' => undef,
          'dob_year' => undef,
          'ein' => undef,
          'email' => 'foo@bar.com',
          'href' => '/customers/CUe3pf7nX93sMvrd9qcC29W',
          'id' => 'CUe3pf7nX93sMvrd9qcC29W',
          'links' => {
            'destination' => undef,
            'source' => undef
          },
          'merchant_status' => 'no-match',
          'meta' => {},
          'name' => undef,
          'phone' => undef,
          'ssn_last4' => undef,
          'updated_at' => '2014-10-02T07:59:26.405946Z'
        }

 create_customer

        create_customer($customer)

    Creates a customer. A customer hashref is optional. Returns the
    customer.

    Example:

        $bp->create_customer({ name => 'Bob', email => 'bob@foo.com' });

 update_customer

        update_customer($customer)

    Updates a customer. Returns the updated customer.

    Example:

        my $customer = $bp->get_customer($customer_id);
        $customer->{email} = 'sue@foo.com';
        $bp->update_customer($customer);

 get_hold

        get_hold($id)

    Returns the card hold for the given id.

    Example response:

        {
          'amount' => 123,
          'created_at' => '2014-10-03T03:39:46.933465Z',
          'currency' => 'USD',
          'description' => undef,
          'expires_at' => '2014-10-10T03:39:47.051257Z',
          'failure_reason' => undef,
          'failure_reason_code' => undef,
          'href' => '/card_holds/HL7b0bw2Ooe6G3yad7dR1rRr',
          'id' => 'HL7b0bw2Ooe6G3yad7dR1rRr',
          'links' => {
            'card' => 'CC7af3NesZk2bYR5GxqLLmfe',
            'debit' => undef,
            'order' => undef
          },
          'meta' => {},
          'status' => 'succeeded',
          'transaction_number' => 'HL7JT-EWF-5CQ6',
          'updated_at' => '2014-10-03T03:39:47.094448Z',
          'voided_at' => undef
        }

 create_hold

        create_hold($hold_data, card => $card)

    Creates a card hold. The $hold_data hashref must contain an amount. The
    card param is a hashref such as one returned from "get_card". Returns
    the created hold.

 capture_hold

        capture_hold($hold, debit => $debit)

    Captures a previously created card hold. This creates a debit. The
    $debit hashref is optional and can contain an amount. Any amount up to
    the amount of the hold may be captured. Returns the created debit.

    Example:

        my $hold = $bp->get_hold($hold_id);
        my $debit = $bp->capture_hold(
            $hold,
            debit => {
                amount                  => 1000,
                description             => 'money for stuffs',
                appears_on_statement_as => 'ACME 123',
            }
        );

 void_hold

        void_hold($hold)

    Cancels the hold. Once voided, the hold can no longer be captured.
    Returns the voided hold.

    Example:

        my $hold = $bp->get_hold($hold_id);
        my $voided_hold = $bp->void_hold($hold);

 get_debit

        get_debit($id)

    Returns the debit for the given id.

    Example response:

        {
          'amount' => 123,
          'appears_on_statement_as' => 'BAL*Tilt.com',
          'created_at' => '2014-10-06T05:01:39.045336Z',
          'currency' => 'USD',
          'description' => undef,
          'failure_reason' => undef,
          'failure_reason_code' => undef,
          'href' => '/debits/WD6F5x4VpYx4hfB02tGIqNU1',
          'id' => 'WD6F5x4VpYx4hfB02tGIqNU1',
          'links' => {
            'card_hold' => 'HL6F4q5kJGxt1ftH8vgZZJkh',
            'customer' => undef,
            'dispute' => undef,
            'order' => undef,
            'source' => 'CC6DFWepK7eeL03cZ06Sb9Xf'
          },
          'meta' => {},
          'status' => 'succeeded',
          'transaction_number' => 'WAVD-B0K-R7TX',
          'updated_at' => '2014-10-06T05:01:39.542306Z'
        }

 create_debit

        create_debit($debit, card => $card)

    Debits a card. The $debit hashref must contain an amount. The card
    param is a hashref such as one returned from "get_card". Returns the
    created debit.

    Example:

        my $card = $bp->get_card($card_id);
        my $debit = $bp->create_debit({ amount => 123 }, card => $card);

 refund_debit

        refund_debit($debit)

    Refunds a debit. Returnds the refund.

    Example:

        my $debit = $bp->get_debit($debit_id);
        my $refund = $bp->refund_debit($debit);

    Example response:

        {
          'amount' => 123,
          'created_at' => '2014-10-06T04:57:44.959806Z',
          'currency' => 'USD',
          'description' => undef,
          'href' => '/refunds/RF2pO6Fz8breGs2TAIpfE2nr',
          'id' => 'RF2pO6Fz8breGs2TAIpfE2nr',
          'links' => {
            'debit' => 'WD2hQV9COFX0aPMSIzyeAuAg',
            'dispute' => undef,
            'order' => undef
          },
          'meta' => {},
          'status' => 'succeeded',
          'transaction_number' => 'RFRGL-EU1-A39B',
          'updated_at' => '2014-10-06T04:57:48.161218Z'
        }

 get_bank_account

        get_bank_account($id)

    Returns the bank account for the given id.

    Example response:

        {
          'account_number' => 'xxxxxxxx6789',
          'account_type' => 'checking',
          'address' => {
            'city' => undef,
            'country_code' => 'USA',
            'line1' => '123 Abc St',
            'line2' => undef,
            'postal_code' => '94103',
            'state' => undef
          },
          'bank_name' => '',
          'can_credit' => bless( do{\(my $o = 1)}, 'JSON::XS::Boolean' ),
          'can_debit' => bless( do{\(my $o = 0)}, 'JSON::XS::Boolean' ),
          'created_at' => '2014-10-06T06:40:14.649386Z',
          'fingerprint' => 'cc552495fc90556293db500b985bacc918d9fb4d37b42052adf64',
          'href' => '/bank_accounts/BA4TAWvO3d3J14i6BdjJUZsp',
          'id' => 'BA4TAWvO3d3J14i6BdjJUZsp',
          'links' => {
            'bank_account_verification' => undef,
            'customer' => undef
          },
          'meta' => {},
          'name' => 'Bob Smith',
          'routing_number' => '110000000',
          'updated_at' => '2014-10-06T06:40:14.649388Z'
        }

 create_bank_account

        create_bank_account($bank)

    Creates a bank account. Returns the bank account that was created.

    Example:

        my $bank = $bp->create_bank_account({
            account_number => '000123456789',
            acount_type    => 'checking',
            name           => 'Bob Smith',
            routing_number => '110000000',
            address => {
                line1       => '123 Abc St',
                postal_code => '94103',
            },
        });

 add_bank_account

        add_bank_account($bank, customer => $customer)

    Associates a bank account to the given customer. Returns the bank
    account.

    Example:

        my $bank = $bp->add_bank_account($bank_id);
        my $customer = $bp->get_customer($customer_id);
        $bank = $bp->add_bank_account($bank, customer => $customer);

 get_credit

        get_credit($id)

    Returns the credit for the given id.

    Example response:

        {
          'amount' => 123,
          'appears_on_statement_as' => 'Tilt.com',
          'created_at' => '2014-10-06T06:52:00.522212Z',
          'currency' => 'USD',
          'description' => undef,
          'failure_reason' => undef,
          'failure_reason_code' => undef,
          'href' => '/credits/CR27ns5sg1FFgHsGy5VEhowd',
          'id' => 'CR27ns5sg1FFgHsGy5VEhowd',
          'links' => {
            'customer' => undef,
            'destination' => 'BA26JfFfg1vqrCoXPzSSxtKg',
            'order' => undef
          },
          'meta' => {},
          'status' => 'succeeded',
          'transaction_number' => 'CR4F7-4XQ-JLDG',
          'updated_at' => '2014-10-06T06:52:03.558485Z'
        }

 create_credit

        create_credit($credit, bank_account => $bank)
        create_credit($credit, card => $card)

    Sends money to a bank account or a credit card. The $credit hashref
    must contain an amount. A bank_account or card param is required.
    Returns the created credit.

    Example:

        my $bank = $bp->get_bank_account($bank_account_id);
        my $credit = $bp->create_credit({ amount => 123 }, bank_account => $bank);

 get_bank_verification

        get_bank_verification($id)

    Gets a bank account verification.

    Example response:

        {
          'attempts' => 0,
          'attempts_remaining' => 3,
          'created_at' => '2014-10-06T08:01:59.972034Z',
          'deposit_status' => 'succeeded',
          'href' => '/verifications/BZnWun9Itq7FVtj1nludGjC',
          'id' => 'BZnWun9Itq7FVtj1nludGjC',
          'links' => {
            'bank_account' => 'BAdFCPv3GkIlXEWQrdTyIW9'
          },
          'meta' => {},
          'updated_at' => '2014-10-06T08:02:00.268756Z',
          'verification_status' => 'pending'
        }

 create_bank_verification

        create_bank_verification(bank_account => $bank)

    Create a new bank account verification. This initiates the process of
    sending micro deposits to the bank account which will be used to verify
    bank account ownership. A bank_account param is required. Returns the
    created bank account verification.

    Example:

        my $bank = $bp->get_bank_account($bank_account_id);
        my $verification = $bp->create_bank_verification(bank_account => $bank);

 confirm_bank_verification

        confirm_bank_verification($verification,
            amount_1 => $amount_1, amount_2 => $amount_2);

    Confirm the trial deposit amounts that were sent to the bank account.
    Returns the bank account verification.

    Example:

        my $ver = $bp->get_bank_account($bank_account_id);
        $verification =
            $bp->confirm_bank_verification($ver, amount_1 => 1, amount_2 => 2);

 get_disputes

        get_disputes(
            $start_date => '2014-01-01T12:00:00',
            $end_date   => DateTime->now,
            $limit      => 10,
            $offset     => 0,
        )

    Lists all disputes (chargebacks). All of the parameters are optional.
    The $start_date and $end_date parameters can either be DateTime
    objects, or ISO8601 formatted strings. The $limit and $offset
    parameters must be valid integers.

    Example response:

        [
            {
                amount          => 6150,
                created_at      => '2013-12-06T02:05:13.656744Z',
                currency        => 'USD',
                href            => '/disputes/DT1234567890',
                id              => 'DT1234567890',
                initiated_at    => '2013-09-11T00:00:00Z',
                links           => {
                    transaction => 'WD1234567890'
                },
                meta       => {},
                reason     => 'clerical',
                respond_by => '2013-10-15T00:00:00Z',
                status     => 'lost',
                updated_at => '2013-12-06T20:59:33.884181Z'
            },
            {
                amount          => 10250,
                created_at      => '2013-12-06T01:55:28.882064Z',
                currency        => 'USD',
                href            => '/disputes/DT0987654321',
                id              => 'DT0987654321',
                initiated_at    => '2013-08-28T00:00:00Z',
                links           => {
                    transaction => 'WD0987654321'
                },
                meta       => {},
                reason     => 'clerical',
                respond_by => '2013-10-02T00:00:00Z',
                status     => 'lost',
                updated_at => '2013-12-06T21:04:11.158050Z'
            }
        ]

 get_dispute

        get_dispute('DT1234567890')

    Fetches a dispute (chargeback). The $id of the dispute is a required
    parameter.

    Example response:

        {
            amount          => 6150,
            created_at      => '2013-12-06T02:05:13.656744Z',
            currency        => 'USD',
            href            => '/disputes/DT1234567890',
            id              => 'DT1234567890',
            initiated_at    => '2013-09-11T00:00:00Z',
            links           => {
                transaction => 'WD1234567890'
            },
            meta       => {},
            reason     => 'clerical',
            respond_by => '2013-10-15T00:00:00Z',
            status     => 'lost',
            updated_at => '2013-12-06T20:59:33.884181Z'
        }

AUTHORS

      * Ali Anari <ali@tilt.com>

      * Khaled Hussein <khaled@tilt.com>

      * Naveed Massjouni <naveed@tilt.com>

      * Al Newkirk <al@tilt.com>

      * Will Wolf <will@tilt.com>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2012 by Crowdtilt, Inc..

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.