Business::WebMoney - Perl API to WebMoney
use Business::WebMoney; my $wm = Business::WebMoney->new( p12_file => '/path/to/key.p12', p12_pass => 'secret', ); my $inv = $wm->invoice( reqn => 10, orderid => 1, customerwmid => '000000000000', storepurse => 'Z000000000000', amount => 100, desc => 'Camel', address => 'Delivery address', expiration => 3, ) or die $wm->errstr; my $invs = $wm->get_out_invoices( reqn => 11, purse => 'Z000000000000', datestart => '20080101 00:00:00', datefinish => '20090101 00:00:00', ) or die $wm->errstr; my $ops = $wm->get_operations( reqn => 12, purse => 'Z000000000000', datestart => '20080101 00:00:00', datefinish => '20090101 00:00:00', ) or die $wm->errstr; $wm->reject_protect( reqn => 13, wmtranid => '123123123', ) or die $wm->errstr; $wm->finish_protect( reqn => 14, wmtranid => '123123123', pcode => 'secret', ) or die $wm->errstr; my $invs = $wm->get_in_invoices( reqn => 15, wmid => '000000000000', datestart => '20080101 00:00:00', datefinish => '20090101 00:00:00', ) or die $wm->errstr; my $purses = $wm->get_balance( reqn => 16, wmid => '000000000000', ) or die $wm->errstr; $wm->transfer( reqn => 17, tranid => 2, pursesrc => 'Z000000000000', pursedest => 'Z000000000000', amount => 100, desc => 'Camel', ) or die $wm->errstr; $wm->message( reqn => 18, receiverwmid => '000000000000', msgsubj => 'Foo', msgtext => 'Bar', ) or die $wm->errstr; $wm->money_back( reqn => 19, inwmtranid => '123123123', amount => 100, ) or die $wm->errstr;
Business::WebMoney provides simple API to the WebMoney transfer system. It requires the SSL private key and certificate from your WM Keeper Light account (PKCS12 file). WM Keeper Classic keys are not supported yet.
The main features of the library are:
Create outgoing invoice (X1)
Transfer money (X2)
Get the list of operations (X3)
Check invoice status (X4)
Enter protection code (X5)
Send a message via WM mail (X6)
Check purses balance (X9)
Get incoming invoices list (X10)
Reject protected payment (X13)
Return money without commission (X14)
Every function in the library corresponds to the single WebMoney interface. Function arguments are translated to corresponding request fields.
An example:
$wm->get_operations( reqn => 1, purse => 'R000000000000', datestart => '20081001 00:00:00', datefinish => '20090101 00:00:00', );
This call is translated to the XML request:
<w3s.request> <reqn>1</reqn> <getoperations> <purse>R000000000000</purse> <datestart>20081001 00:00:00</datestart> <datefinish>20090101 00:00:00</datefinish> </getoperations> </w3s.request>
Interfaces returning single XML element correspond to functions returning reference to hash. Interfaces returning list of XML elements correspond to functions returning reference to array of hashes. Attributes and subelements of XML response are translated into hash fields.
<?xml version="1.0"?> <w3s.response> <reqn>1</reqn> <operations cnt="8" cntA="8"> <operation id="150977211" ts="150977211"> <pursesrc>R000000000000</pursesrc> <pursedest>R000000000000</pursedest> <amount>18000.00</amount> <comiss>0.00</comiss> <opertype>0</opertype> <wminvid>0</wminvid> <orderid>0</orderid> <tranid>0</tranid> <period>0</period> <desc>Camel</desc> <datecrt>20081103 08:26:20</datecrt> <dateupd>20081103 08:26:20</dateupd> <corrwm>000000000000</corrwm> <rest>18000.00</rest> </operation> <operation id="150977212" ts="150977212"> <pursesrc>R000000000000</pursesrc> <pursedest>R000000000000</pursedest> <amount>18000.00</amount> <comiss>0.00</comiss> <opertype>0</opertype> <wminvid>0</wminvid> <orderid>0</orderid> <tranid>0</tranid> <period>0</period> <desc>Camel 2</desc> <datecrt>20081103 08:26:25</datecrt> <dateupd>20081103 08:26:25</dateupd> <corrwm>000000000000</corrwm> <rest>36000.00</rest> </operation> </operations> </w3s.response>
This is a response to Operations request. Method get_operations will convert it to the following structure:
get_operations
[ { 'id' => '150977211', 'ts' => '150977211', 'pursesrc' => 'R000000000000', 'pursedest' => 'R000000000000', 'amount' => '18000.00', 'comiss' => '0.00', 'opertype' => '0', 'wminvid' => '0' 'orderid' => '0', 'tranid' => '0', 'period' => '0', 'desc' => 'Camel', 'datecrt' => '20081103 08:26:20', 'dateupd' => '20081103 08:26:20', 'corrwm' => '000000000000', 'rest' => '18000.00', }, { 'id' => '150977212', 'ts' => '150977212', 'pursesrc' => 'R000000000000', 'pursedest' => 'R000000000000', 'amount' => '18000.00', 'comiss' => '0.00', 'opertype' => '0', 'wminvid' => '0' 'orderid' => '0', 'tranid' => '0', 'period' => '0', 'desc' => 'Camel 2', 'datecrt' => '20081103 08:26:25', 'dateupd' => '20081103 08:26:25', 'corrwm' => '000000000000', 'rest' => '36000.00', } ];
Every request has a reqn - request number. It must be greater than the previous money transfer reqn.
reqn
All dates are specified in YYYYMMDD HH:MM:SS format.
YYYYMMDD HH:MM:SS
On failure functions return undef. Error code and description are available via $wm->errcode and $wm->errstr accordingly.
undef
$wm->errcode
$wm->errstr
my $wm = Business::WebMoney->new( p12_file => '/path/to/key.p12', # Path to PKCS12 WebMoney file (mandatory) p12_pass => 'secret', # Encryption password for p12_file (mandatory if encrypted) ca_file => '/path/to/CA.crt', # WebMoney certification authority file (optional) timeout => 30, # Request timeout in seconds (optional, default 20) );
my $ops = $wm->get_operations( reqn => 1, purse => 'Z000000000000', # Purse to query (mandatory) datestart => '20080101 00:00:00', # Interval beginning (mandatory) datefinish => '20080201 00:00:00', # Interval end (mandatory) wmtranid => 123123123, # Transaction ID (in the WebMoney system, optional) tranid => 123, # Transaction ID (in your system, optional) wminvid => 345345345, # Invoice ID (in the WebMoney system, optional) orderid => 345, # Order ID (invoice in your system, optional) );
On error returns undef. On success returns reference to array of transactions. Each transaction is a hash:
id - a unique number of an transaction in the WebMoney system
id
ts - a service number of an transaction in the WebMoney system
ts
tranid - Transfer number set by the sender; an integer; it should be unique for each trasaction (the same tranid should not be used for two transactions)
tranid
pursesrc - Sender's purse number
pursesrc
pursedest - Recipient's purse number
pursedest
amount - money amount
amount
comiss - Fee charged
comiss
opertype - 0 - simple (completed), 4 - protected (not completed), 12 - protected (refunded)
opertype
period - Protection period in days (0 means no protection)
period
wminvid - Invoice number (in the WebMoney system) of the transaction (0 means without invoice)
wminvid
orderid - Serial invoice number set by the store (0 means without invoice)
orderid
desc - Description of product or service
desc
datecrt - Date and time of transaction
datecrt
dateupd - Date and time of transaction status change
dateupd
corrwm - Correspondent WMID
corrwm
rest - Rest after transaction
rest
my $inv = $wm->invoice( reqn => 1, orderid => 1, # Invoice serial number. Should be set by the store. An integer (mandatory) customerwmid => '000000000000', # Customer's WMID (mandatory) storepurse => 'Z000000000000', # Number of the purse where funds will be sent to (mandatory) amount => 100, # Amount that the customer has to pay (mandatory) desc => 'Camel', # Description of product or service (max 255 characters; without spaces in the beginning and in the end, mandatory) address => 'Delivery address', # Delivery address (max 255 characters; without spaces in the beginning and in the end, optional) period => 3, # Maximum period of protection in days (An integer in the range: 0 - 255; zero means that no protection should be used, optional) expiration => 3, # Maximum valid period in days (An integer in the range: 0 - 255; zero means that the valid period is not defined, optional) );
On error returns undef. On success returns reference to confirmation hash.
my $invs = $wm->get_out_invoices( reqn => 11, purse => 'Z000000000000', # Number of the purse where the invoice should be paid to (mandatory) datestart => '20080101 00:00:00', # Minimum time and date of invoice creation (mandatory) datefinish => '20090101 00:00:00', # Maximum time and date of invoice creation (mandatory) wminvid => 123123123, # Invoice number (in the WebMoney system, optional) orderid => 123, # Serial invoice number set by the store (optional) ) or die $wm->errstr;
On error returns undef. On success returns reference to array of invoices. Each invoice is a hash:
id - a unique number of a invoice in the WebMoney system
ts - a service number of a invoice in the WebMoney system
orderid - Invoice number set by the sender
customerwmid - Customer's WMID
customerwmid
storepurse - Number of the purse where funds will be sent to
storepurse
amount - Amount that the customer is to pay
address - Delivery address
address
period - Maximum period of protection in days
expiration - Maximum valid period in days
expiration
state - 0 - unpaid, 1 - paid with protection, 2 - paid, 3 - rejected
state
datecrt - Date and time of the invoice creation
dateupd - Date and time of the invoice status change
wmtranid - Transaction number in the WebMoney system, if the invoice was paid
wmtranid
customerpurse - Payer purse, if the invoice was paid
customerpurse
$wm->transfer( reqn => 1, tranid => 2, # Transaction number set by the sender; an integer; it should be unique for each trasaction (the same tranid should not be used for two transactions, mandatory) pursesrc => 'Z000000000000', # Sender's purse number (mandatory) pursedest => 'Z000000000000', # Recipient's purse number (mandatory) amount => 100, # Amount. A floating-point number, for example, 10.5; 9; 7.36 (mandatory) period => 3, # Protection period in days (An integer in the range: 0 - 255; zero means that no protection should be used, optional) pcode => 'secret', # Protection code (In the range 0 - 255 characters; without spaces in the beginning and in the end, optional) desc => 'Camel', # Description of product or service (In the range 0 - 255 characters; without spaces in the beginning and in the end, mandatory) wminvid => 123123123, # Invoice number (in the WebMoney system). 0 means that transfer is made without invoice (optional) ) or die $wm->errstr;
On error returns undef. On success returns reference to confirmation hash:
id - a unique number of a transaction in the WebMoney System
ts - a service number of a transaction in the WebMoney System
tranid - Serial transaction number set by the sender; an integer; it should be unique for each trasaction (the same tranid should not be used for two transactions)
pursedesc - Recipient's purse number
pursedesc
amount - Amount
opertype - Transfer type: 0 - simple (completed), 4 - protected (incomplete)
period - Protection period in days
wminvid - Invoice number (in the WebMoney system). 0 means that transfer is made without invoice
orderid - Serial invoice number set by the store. 0 means that transfer is made without invoice
$wm->finish_protect( reqn => 14, wmtranid => '123123123', # Transfer number in the WebMoney system (mandatory) pcode => 'secret', # Protection code. In the range 0 - 255 characters; without spaces in the beginning and in the end (mandatory) ) or die $wm->errstr;
id - a unique number of transfer in the WebMoney system
td - a service number of transfer in the WebMoney system
td
opertype - 0 - simple (completed), 12 - protected (funds were refunded)
$wm->reject_protect( reqn => 13, wmtranid => '123123123', # Transfer number in the WebMoney system (mandatory) ) or die $wm->errstr;
opertype - 0 - simple (completed), 4 - protected (incomplete), 12 - protected (funds were refunded)
$wm->message( reqn => 18, receiverwmid => '000000000000', # Recipient's WMID, 12 digits (mandatory) msgsubj => 'Foo', # Subject, 0 - 255 characters without spaces in the beginning and in the end (mandatory) msgtext => 'Bar', # Message body, 0 - 1024 characters without spaces in the beginning and in the end (mandatory) ) or die $wm->errstr;
my $purses = $wm->get_balance( reqn => 16, wmid => '000000000000', # WMID, 12 digits (mandatory) ) or die $wm->errstr;
On error returns undef. On success returns reference to array of purses. Each purse is a hash:
id - a unique internal number of the purse
pursename - Purse number, A letter prefix + 12 digits
pursename
amount - Purse balance
my $invs = $wm->get_in_invoices( reqn => 15, wmid => '000000000000', # WMID (mandatory) wminvid => 456456456, # Invoice number (in the WebMoney system), An integer >= 0 (optional) datestart => '20080101 00:00:00', # Minimum time and date of invoice creation (mandatory) datefinish => '20090101 00:00:00', # Maximum time and date of invoice creation (mandatory) ) or die $wm->errstr;
storewmid - Seller's WMID
storewmid
$wm->money_back( reqn => 19, inwmtranid => '123123123', # Transaction ID (mandatory amount => 100, # Amount of transaction (self-check). Must match the transaction being returned (mandatory) ) or die $wm->errstr;
The module is bundled with WebMoney CA certificate to validate identity of the WebMoney server.
Be especially careful when using certificate with money transfer permission on the production servers. Stolen cerficate can be easily reimported to the browser and used to steal your money. To prevent such threats register separate WMID and give it permission to access purses of the main WMID in read-only mode. This can be set up using https://security.wmtransfer.com/
HTTPS_PROXY - proxy support, http://host_or_ip:port
HTTPS_PROXY
HTTPS_PROXY_USERNAME and HTTPS_PROXY_PASSWORD - proxy basic auth
HTTPS_PROXY_USERNAME
HTTPS_PROXY_PASSWORD
The module is not thread-safe.
WebMoney::WMSigner - signer module that signs any data using specified WebMoney key file
WebMoney::WMSigner
http://www.webmoney.ru/eng/developers/interfaces/xml/index.shtml - WebMoney API specification
Alexander Lourier, <aml@rulezz.ru>
Copyright (C) 2008 by Alexander Lourier
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.
To install Business::WebMoney, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Business::WebMoney
CPAN shell
perl -MCPAN -e shell install Business::WebMoney
For more information on module installation, please visit the detailed CPAN module installation guide.