Business::BalancedPayments - BalancedPayments API bindings
version 0.1200
use Business::BalancedPayments; my $secret = 'abc123'; my $bp = Business::BalancedPayments->new(secret => $secret); my $card = $bp->create_card({ card_number => "5105105105105100", expiration_month => 12, expiration_year => 2020, security_code => 123, }); $bp->get_card($card->{id});
This module provides bindings for the BalancedPayments API.
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:
get_*
$id
$bp->get_account('AC7A'); $bp->get_account('/v1/marketplaces/MK98/accounts/AC7A');
my $bp = Business::BalancedPayments->new( secret => $secret, logger => $logger, # optional retries => 3, # optional );
Instantiates a new `Business::BalancedPayments` client object. Parameters:
Required. The Balanced Payments secret key for your account.
Optional. A logger-like object. It just needs to have a method named DEBUG that takes a single argument, the message to be logged. A Log::Tiny object would be a good choice.
DEBUG
Optional. The number of times to retry requests in cases when Balanced returns a 5xx response. Defaults to 0.
get_transactions()
Returns the transactions for this marketplace.
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({ card_number => "5105105105105100", expiration_month => 12, expiration_year => 2020, security_code => 123, })
Creates a credit card. See "get_card" for an example response.
get_account($id)
Returns the account for the given id.
{ 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($email)
Returns the account for the given email address. See "get_account" for an example response.
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($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($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".
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($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($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($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($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.
hold
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($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($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($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);
{ 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($id)
Returns the bank account for the given id.
{ 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 => { ... }, }
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.
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_accounti( { name => "WHC III Checking", account_number => "12341234", bank_code => "321174851", }, account => $account );
This operation implicitly adds the "merchant" role to the 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' }, });
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 });
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($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", }, }
Khaled Hussein <khaled.hussein@gmail.com>
Naveed Massjouni <naveedm9@gmail.com>
Will Wolf<throughnothing@gmail.com>
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.
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.