/ 
Finance-BitPay-API-0.01
River stage zero No dependents
/ Finance::BitPay::API

NAME

Finance::BitPay::API - Perl extension for handling the BitPay API and IPN calls.

SYNOPSIS

use Finance::BitPay::API;

# all the standard BitPay API calls...

my $bitpay  = Finance::BitPay::API->new(key => 'abc123');
my $invoice = $bitpay->invoice_create(currency => 'EUR', price => '9.99');
my $invoice = $bitpay->invoice_get(id => $id);
my $rates   = $bitpay->rates;
my $ledger  = $bitpay->ledger(c => 'USD', startDate => '2014-01-01, endDate => '2014-01-10');

# The bitpay object contains all the request data from the last request...

my $user_agent = $bitpay->user_agent;

if ($bitpay->success) {
    print 'SUCESS';
}
else {
    print 'FAIL';
    my $error = $bitpay->error;
}


# A more useful example...

my $bitpay  = Finance::BitPay::API->new(key => 'YOUR API KEY GOES HERE');
my $invoice = $bitpay->invoice_create(currency => 'EUR', price => '9.99');

if ($invoice) {
    printf "The BitPay invoice ID is %s. You can see it here: %s\n", @{$invoice}{qw(id url)};
}
else {
    printf "An error occurred: %s\n", $bitpay->error;
}

DESCRIPTION

This API module provides a quick way to access the BitPay API from perl without worrying about the connection, authenticatino and an errors in between.

You call these on the API object created like this:

my $bitpay = Finance::BitPay::API->new(key => 'YOUR_KEY';

...Where 'YOUR_KEY' is the text key provided to you by BitPay through their merchant interface

The primary methods are:

invoice_create(), invoice_get(), rates() and ledger()

The return value is a hash representing the BitPay response.

my $response_as_a_hash = $bitpay->invoice_create(currency => $cur, price => $price);

The return value will be undefined when an error occurs...

if ($bitpay->is_success) {
    # the last primary method call worked!
}
else {
    print "There was an error: " . $bitpay->error;
    # more detail can be found in the bitpay object using...
    my $ua           = $bitpay->user_agent;
    my $raw_request  = $bitpay->http_request;
    my $raw_response = $bitpay->http_response;
    # further inspection could go here (like dumping the content of the useragent)
}

METHODS

new()

Create a new Finance::BitPay::API object.

invoice_create()

Request a new invoice from BitPay. The input is a hash with keys:

price and currency.

Additionally optional input settings:

IPN fields:

posData, notificationURL, transactionSpeed, fullNotifications, notificationEmail

Order handling:

redirectURL

Buyer information:

orderID, itemDesc, itemCode, physical, buyerName, buyerAddress1, buyerAddress2, buyerCity, buyerState, buyerZip, buyerCountry, buyerEmail, buyerPhone

The invoice is generated like this:

my $invoice = $bitpay->invoice_create(currency => 'CAD', price => '5.99', buyerName => 'Prime Minister');

invoice_get()

Get the current state of an invoice, given its invoice Id.

my $invoice = $bitpay->invoice_get(id => 'YOUR_INVOICE_ID');

rates()

Get the current rates by currency...

my $rates = $bitpay->rates;

ledger()

I cannot explain what this does...

my $ledger = $bitpay->ledger(c => $currency, startDate => $start_date, endDate => $end_date);

NOTES

This module does not do accessive error checking on the request or the response. It will only check for "required" parameters prior to sending a request to BitPay. This means that you provide a word for a 'amount' parameter, and this module will happily send that off to BitPay for you. In these cases we are allowing BitPay to decide what is and is not valid input. If the input values are invalid, we expect BitPay to provide an appropriate response and that is the message we will return to the caller (through $bitpay->error).

This module does not validate the response from BitPay. In general it will return success when any json response is provided by Bitpay without the 'error' key. The SSL certificate is verified automatically by LWP, so the response you will get is very likely from BitPay itself. If there is an 'error' key in the json response, then that error is put into the $bitpay->error attribute. If there is an 'error' parsing the response from BitPay, then the decoding error from json is in the $bitpay->error attribute. If there is a network error (not 200), then the error code and $response->error will contain the HTTP Response status_line() (a string response of what went wrong).

SEE ALSO

The BitPay API documentation: https://bitpay.com/downloads/bitpayApi.pdf

AUTHOR

Jeff Anderson, <peawormsworth@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2014 by Jeff Anderson

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.