Business::BalancedPayments - BalancedPayments API bindings
version 0.0700
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.
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($account) create_account($account, card => $card)
Creates an account. An account hashref is required. The account hashref 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", }, }
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. The amount must be an integer value >= 200.
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.