NAME

Business::BalancedPayments::V10

VERSION

version 1.0301

METHODS

These methods for version 1.0 of the Balanced API https://docs.balancedpayments.com/1.0/api. Note that version 1.0 was officially deprecated March 2014.

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('CC92QRQcwUCp5zpzKS');
$bp->get_card('/v1/marketplaces/MK98f1/cards/CC92QRQcwUCp5zpzKS');

get_transactions

get_transactions()

Returns the transactions for this marketplace.

get_card

get_card($id)

Returns the credit card for the given id.

Example response:

{
    account          => { ... },
    brand            => "MasterCard",
    card_type        => "mastercard",
    created_at       => "2012-06-07T11:00:40.003671Z",
    expiration_month => 12,
    expiration_year  => 2020,
    id               => "CC92QRQcwUCp5zpzEz7lXKS",
    is_valid         => 1,
    last_four        => 5100,
    name             => undef,
    uri              => "/v1/marketplaces/MK98f1/cards/CC92QRQcwUCp5zpzKS",
}

create_card

create_card({
    card_number      => '5105105105105100',
    expiration_month => 12,
    expiration_year  => 2020,
    security_code    => 123,
})

Creates a credit card. Returns the card object.

get_customer

get_customer($id)

Returns the customer for the given id.

Example response:

{
  address              => {},
  bank_accounts_uri    => "/v1/customers/CU4I/bank_accounts",
  business_name        => undef,
  cards_uri            => "/v1/customers/CU4I/cards",
  created_at           => "2014-09-21T06:14:54.996408Z",
  credits_uri          => "/v1/customers/CU4I/credits",
  debits_uri           => "/v1/customers/CU4I/debits",
  destination          => undef,
  dob                  => undef,
  ein                  => undef,
  email                => 'bob@foo.com',
  facebook             => undef,
  holds_uri            => "/v1/customers/CU4I/holds",
  id                   => "CU4I",
  is_identity_verified => 0,
  meta                 => {},
  name                 => "Bob",
  phone                => undef,
  refunds_uri          => "/v1/customers/CU4I/refunds",
  reversals_uri        => "/v1/customers/CU4I/reversals",
  source               => undef,
  ssn_last4            => undef,
  transactions_uri     => "/v1/customers/CU4I/transactions",
  twitter              => undef,
  uri                  => "/v1/customers/CU4I",
}

create_customer

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

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

get_account

get_account($id)

Returns the account for the given id.

Example response:

{
    id                => "AC7A",
    uri               => "/v1/marketplaces/MK98/accounts/AC7A",
    email_address     => "naveed\@crowdtilt.com",
    meta              => {},
    name              => undef,
    roles             => [],
    created_at        => "2012-06-07T21:01:38.801460Z",
    bank_accounts_uri => "/v1/marketplaces/MK98/accounts/AC7A/bank_accounts",
    cards_uri         => "/v1/marketplaces/MK98/accounts/AC7A/cards",
    credits_uri       => "/v1/marketplaces/MK98/accounts/AC7A/credits",
    debits_uri        => "/v1/marketplaces/MK98/accounts/AC7A/debits",
    holds_uri         => "/v1/marketplaces/MK98/accounts/AC7A/holds",
    refunds_uri       => "/v1/marketplaces/MK98/accounts/AC7A/refunds",
    transactions_uri  => "/v1/marketplaces/MK98/accounts/AC7A/transactions",
}

get_account_by_email

get_account_by_email($email)

Returns the account for the given email address. See "get_account" for an example response.

create_account

create_account()
create_account($account)
create_account($account, card => $card)

Creates an account. An account hashref is optional. The account hashref, if passed in, must have an email_address field:

$bp->create_account({ email_address => 'bob@crowdtilt.com' });

It is possible to create an account and associate it with a credit card at the same time. You can do this in 2 ways. You can provide a card such as one returned by calling "get_card":

my $card = $bp->get_card($card_id);
$bp->create_account({ email_address => 'bob@crowdtilt.com' }, card => $card)

Alternatively, you can provide a card_uri inside the account hashref:

my $card = $bp->get_card($card_id);
$bp->create_account({
    email_address => 'bob@crowdtilt.com',
    card_uri      => $card->{uri},
});

Returns an account hashref. See "get_account" for an example response.

update_account

update_account($account)

Updates an account. It expects an account hashref, such as one returned by "get_account". The account hashref must contain a uri or id field.

add_card

add_card($card, account => $account)

Adds a card to an account. It expects a card hashref, such as one returned by "get_card", and an account hashref, such as one returned by "get_account".

Returns an account hashref. See "get_account" for an example response.

get_debit

get_debit($debit_id)

Returns the debit with the given id. Example response:

{
  id                       =>  "WD1xtdUeixQIfJEsg4RwwHjQ",
  transaction_number       =>  "W553-201-5667",
  amount                   =>  50,
  fee                      =>  1,
  description              =>  undef,
  appears_on_statement_as  =>  "example.com",
  available_at             =>  "2012-10-25T04:48:19.337522Z",
  created_at               =>  "2012-10-25T04:48:19.443904Z",
  uri                      =>  "/v1/marketplaces/MK98/debits/WD2L",
  refunds_uri              => "/v1/marketplaces/MK98/debits/WD2L/refunds",
  account                  =>  { ...  },
  hold                     =>  { ...  },
  meta                     =>  { ...  },
  source => {
    brand            => "MasterCard",
    card_type        => "mastercard",
    created_at       => "2012-06-07T11:00:40.003671Z",
    expiration_month => 12,
    expiration_year  => 2020,
    id               => "CC92QRQcwUCp5zpzEz7lXKS",
    is_valid         => 1,
    last_four        => 5100,
    name             => undef,
    uri => "/v1/marketplaces/MK98/accounts/AC7A/cards/CC92QRQcwUCp5zpzEz7lXKS",
  },
}

create_debit

create_debit($debit, account => $account)
create_debit($debit, card => $card)

Creates a debit. It expects a debit hashref which at least contains an amount field. An account or card must be provided.

my $account = $bp->get_account($account_id);
$bp->create_debit ({ account => 250 }, account => $account);

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

Successful creation of a debit will return an associated hold as part of the response. This hold was created and captured behind the scenes automatically. See "get_debit" for an example response.

get_hold

get_hold($hold_id)

Returns the hold with the given id. Example response:

{
  id          => "HL5byxIzSvf0entZuO9eEsWJ",
  uri         => "/v1/marketplaces/MK98/holds/HL5byxIzSvf0entZuO9eEsWJ",
  amount      => 200,
  description => undef,
  created_at  => "2012-06-08T09:23:53.745746Z",
  expires_at  => "2012-06-15T09:23:53.705009Z",
  fee         => 35,
  is_void     => 0,
  account     => { ... },
  debit       => { ... },
  meta        => { ... },
  source      => { ... },
}

create_hold

create_hold($hold, account => $account)
create_hold($hold, card => $card)

Creates a hold for the given account. It expects a hold hashref which at least contains an amount field.

An account or card must be provided. If an account is provided, Balanced defaults to charging the most recently added card for the account.

my $account = $bp->get_account($account_id);
$bp->create_hold ({ account => 250 }, account => $account);

You can pass in a card if you want to charge a specific card:

my $card = bp->get_card($card_id);
$bp->create_hold({ amount => 250 }, card => $card);

See "get_hold" for an example response.

capture_hold

capture_hold($hold)
capture_hold($hold, {
    amount                  => ...,
    appears_on_statement_as => ...,
    meta                    => ...,
    description             => ...,
    on_behalf_of_uri        => ...,
    source_uri              => ...,
    bank_account_uri        => ...,
})

Capturing a hold will create a debit representing the flow of funds from the buyer's account to your marketplace. The hold param is required and may be a hold object or a hold uri. A an optional hashref of extra parameters may be provided. They will be passed on to Balanced.

my $hold = $bp->get_hold($hold_id);
my $merchant_account = $bp->get_account($merchant_id);
$bp->capture_hold($hold, { on_behalf_of_uri => $merchant_account->{uri} });

Returns a debit hashref. Example response:

{
  id                      => "WD2Lpzyz8Okbhx2Nbw7YuTP3",
  transaction_number      => "W476-365-3767",
  uri                     => "/v1/marketplaces/MK98/debits/WD2L",
  amount                  => 50,
  appears_on_statement_as => "example.com",
  available_at            => "2012-06-08T09:57:27.686977Z",
  created_at              => "2012-06-08T09:57:27.750828Z",
  description             => undef,
  fee                     => 1,
  meta                    => { ... },
  hold                    => { ... },
  account                 => { ... },
  source                  => { ... },
  refunds_uri             => "/v1/marketplaces/MK98/debits/WD2L/refunds",
}

=head2 get_refund

    get_refund($id)

Gets a refund by id.

    $bp->get_refund($id);

Returns a refund hashref.
Example response.
  {
    id                       =>  'RF74',
    transaction_number       =>  'RF966-744-5492',
    amount                   =>  323,
    fee                      =>  -10,
    description              =>  '',
    appears_on_statement_as  =>  'example.com',
    created_at               =>  '2012-08-27T16:54:46.595330Z',
    debit                    =>  { ... },
    meta                     =>  { ... },
    account                  =>  { ... },
    uri                      =>  '/v1/marketplaces/MP35/refunds/RF74',
  }

get_refunds

get_refunds($debit)

Gets the refunds associated with a specific debit.

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

Returns a refunds hashref. Example response. { items => [ { id => 'RF74', transaction_number => 'RF966-744-5492', amount => 323, fee => -10, description => '', appears_on_statement_as => 'example.com', created_at => '2012-08-27T16:54:46.595330Z', debit => { ... }, meta => { ... }, account => { ... }, uri => '/v1/marketplaces/MP35/refunds/RF74', } ], offset => 0, limit => 10, next_uri => undef, total => 1, uri => '/v1/marketplaces/MP35/debits/WD2L/refunds?limit=10&offset=0', first_uri => '/v1/marketplaces/MP35/debits/WD2L/refunds?limit=10&offset=0', last_uri => '/v1/marketplaces/MP35/debits/WD2L/refunds?limit=10&offset=0', previous_uri => undef, }

void_hold

void_hold($hold)

Voids a hold.

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

Returns a hold hashref. See "get_hold" for an example response.

refund_debit

refund_debit($debit)

Refunds a debit. If no amount is found in the debit hashref, then Balanced refunds the entire amount.

my $account = $bp->get_account($account_id);
my $debit = $bp->capture_hold(
    $bp->create_hold({ amount => 305 }, account => $account)
);
$bp->refund_debit($debit);

Example response:

{
    id                      => "RFrFB30adjtze8HSIoghLPr",
    uri                     => "/v1/marketplaces/MK98/refunds/RFrFB30adLPr",
    amount                  => 305,
    created_at              => "2012-06-11T11:31:59.414827Z",
    description             => undef,
    fee                     => -10,
    meta                    => {},
    transaction_number      => "RF536-609-0270",
    appears_on_statement_as => "example.com",
    account                 => { ... },
    debit                   => { ... },
}

get_bank_account

get_bank_account($id)

Returns the bank account for the given id.

Example response:

{
    id          =>  "BA3gES",
    uri         =>  "/v1/marketplaces/MK98/bank_accounts/BA3gES",
    name        =>  "WHC III Checking",
    bank_name   =>  "SAN MATEO CREDIT UNION",
    bank_code   =>  321174851,
    last_four   =>  1234,
    created_at  =>  "2012-06-12T15:00:59.248638Z",
    is_valid    =>  1,
    account     =>  { ... },
}

confirm_bank_verification

confirm_bank_verification($bank_id, verification_id => $verification_id,
    amount_1 => $x, amount_2 => $y)

Returns the bank account verification status for the given ids.

Example response:

{
    _type              => "bank_account_authentication",
    _uris              => {},
    attempts           => 0,
    created_at         => "2014-01-09T03:11:11.080804Z",
    id                 => "BZ5nDyPcUn2QNkgQn4o62gjM",
    remaining_attempts => 3,
    state              => "deposit_succeeded",
    updated_at         => "2014-01-09T03:11:11.490600Z",
    uri                => "/v1/bank_accounts/BA5lj/verifications/BZ5nD"
}

create_bank_account

create_bank_account($bank_account)

Creates a bank account. A bank account hashref is required:

$bp->create_bank_account({
    name           => "WHC III Checking",
    account_number => "12341234",
    bank_code      => "321174851",
});

Returns a bank account hashref. See "get_bank_account" for an example response.

create_bank_verification

create_bank_verification($bank_id)

Returns the bank account verification receipt for the request.

Example response:

{
    _type              => "bank_account_authentication",
    _uris              => {},
    attempts           => 1,
    created_at         => "2014-01-09T03:11:20.160110Z",
    id                 => "BZ5xQsMUtax4itwPTPM2Ducu",
    remaining_attempts => 2,
    state              => "verified",
    updated_at         => "2014-01-09T03:11:21.482255Z",
    uri                => "/v1/bank_accounts/BA5vJy/verifications/BZ5xQs"
}

add_bank_account

add_bank_account($bank_account, account => $account)

Adds a bank account to an account. It expects a bank account hashref and an account hashref:

my $account = $bp->get_account($account_id);
$bp->add_bank_account(
    {
        name           => "WHC III Checking",
        account_number => "12341234",
        bank_code      => "321174851",
    },
    account => $account
);

This operation implicitly adds the "merchant" role to the account.

Returns a bank account hashref. See "get_bank_account" for an example response.

update_bank_account

update_bank_account($bank_account)

Updates a bank account. A bank account hashref must be provided which must contain an id or uri for the bank account. Balanced only allows you to update the is_valid and meta fields. You may invalidate a bank account by passing is_valid with a false value. Once a bank account has been invalidated it cannot be re-activated.

$bp->update_bank_account({
    id       => 'BA3gES',
    is_valid => 0,
    meta     => { foo => 'bar' },
});

Returns a bank account hashref. See "get_bank_account" for an example response.

invalidate_bank_account

invalidate_bank_account($bank_account_id);

Invalidates a bank account. A bank account id is required. This is a convenience method that does the equivalent of:

update_bank_account({ id => $bank_id, is_valid => 0 });

Returns a bank account hashref. See "get_bank_account" for an example response.

get_credit

get_credit($credit_id);

Gets a credit. This is a way to get information about a specific credit, which can be useful to check its status or get fee information about it.

create_credit

create_credit($credit, account => $account);
create_credit($credit, bank_account => $bank_account);

Creates a credit. This is a way of sending money to merchant accounts. The credit hashref should at least contain an amount field. An account or bank account hashref is required. You may pass in a bank account if you would like to specify a specific bank account to send money to.

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

If an account is provided, Balanced will default to crediting the most recently added bank account. The account should have the merchant role.

my $account = $bp->get_account($account_id);
$bp->create_credit({ amount => 50 }, account => $account);

Returnds a credit hashref. Example response:

{
    id                  => "CR4GkfkOzYNBjFXW5Mxtpn1I",
    uri                 => "/v1/marketplaces/MK98/credits/CR4Gkf",
    amount              => 50,
    created_at          => "2012-06-12T18:51:21.097085Z",
    description         => undef,
    meta                => {},
    transaction_number  => "CR382-740-3389",
    account             => { ... },
    destination         => {
        bank_code  => 321174851,
        bank_name  => "SAN MATEO CREDIT UNION",
        created_at => "2012-06-12T15:00:59.248638Z",
        id         => "BA3gESxjg9yO61fj3CVUhGQm",
        is_valid   => 1,
        last_four  => 1234,
        name       => "WHC III Checking",
        uri => "/v1/marketplaces/MK98/accounts/AC78/bank_accounts/BA3g",
    },
}

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 is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install Business::BalancedPayments, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Business::BalancedPayments

CPAN shell

perl -MCPAN -e shell
install Business::BalancedPayments

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

METHODS

get_transactions

get_card

create_card

get_customer

create_customer

get_account

get_account_by_email

create_account

update_account

add_card

get_debit

create_debit

get_hold

create_hold

capture_hold

get_refunds

void_hold

refund_debit

get_bank_account

confirm_bank_verification

create_bank_account

create_bank_verification

add_bank_account

update_bank_account

invalidate_bank_account

get_credit

create_credit

AUTHORS

COPYRIGHT AND LICENSE

Module Install Instructions