Business::BalancedPayments - Balanced Payments API bindings
version 1.0500
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);
This module provides bindings for the Balanced API.
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:
get_*
$id
$bp->get_card('CC6J123'); $bp->get_card('/cards/CC6J123');
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:
Required. The Balanced Payments secret key for your account.
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.
'1.1'
'1.0'
See WebService::Client for other supported parameters such as logger, retries, and timeout.
logger
retries
timeout
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($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($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.
my $customer = $bp->create_customer; my $card = $bp->get_card($card_id); $bp->add_card($card, customer => $customer);
get_customer($id)
Returns the customer for the given id.
{ '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($customer)
Creates a customer. A customer hashref is optional. Returns the customer.
$bp->create_customer({ name => 'Bob', email => 'bob@foo.com' });
update_customer($customer)
Updates a customer. Returns the updated customer.
my $customer = $bp->get_customer($customer_id); $customer->{email} = 'sue@foo.com'; $bp->update_customer($customer);
get_hold($id)
Returns the card hold for the given id.
{ '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($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.
$hold_data
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.
$debit
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($hold)
Cancels the hold. Once voided, the hold can no longer be captured. Returns the voided hold.
my $hold = $bp->get_hold($hold_id); my $voided_hold = $bp->void_hold($hold);
get_debit($id)
Returns the debit for the given id.
{ '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($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.
my $card = $bp->get_card($card_id); my $debit = $bp->create_debit({ amount => 123 }, card => $card);
refund_debit($debit)
Refunds a debit. Returnds the refund.
my $debit = $bp->get_debit($debit_id); my $refund = $bp->refund_debit($debit);
{ '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($id)
Returns the bank account for the given id.
{ '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($bank)
Creates a bank account. Returns the bank account that was created.
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($bank, customer => $customer)
Associates a bank account to the given customer. Returns the bank account.
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($id)
Returns the credit for the given id.
{ '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($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.
$credit
my $bank = $bp->get_bank_account($bank_account_id); my $credit = $bp->create_credit({ amount => 123 }, bank_account => $bank);
get_bank_verification($id)
Gets a bank account verification.
{ '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(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.
my $bank = $bp->get_bank_account($bank_account_id); my $verification = $bp->create_bank_verification(bank_account => $bank);
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.
my $ver = $bp->get_bank_account($bank_account_id); $verification = $bp->confirm_bank_verification($ver, amount_1 => 1, amount_2 => 2);
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 and must be passed inside of a HashRef. 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.
$start_date
$end_date
$limit
$offset
{ disputes => [ { 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' } ], links => { disputes.events => '/disputes/{disputes.id}/events', disputes.transaction => '/resources/{disputes.transaction}', }, meta { first => '/disputes?limit=10&offset=0', href => '/disputes?limit=10&offset=0', last => '/disputes?limit=10&offset=300', limit => 10, next => '/disputes?limit=10&offset=10', offset => 0, previous => undef, total => 100 } }
get_dispute('DT1234567890')
Fetches a dispute (chargeback). The $id of the dispute is a required parameter.
{ 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' }
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>
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.