/ 
Business-WebMoney-0.03
River stage zero No dependents
/ Business::WebMoney

NAME

Business::WebMoney - Perl API to WebMoney

SYNOPSIS

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;

DESCRIPTION

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)

INTERFACE

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.

An example:

  <?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:

[                                       
  {
    '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.

All dates are specified in YYYYMMDD HH:MM:SS format.

On failure functions return undef. Error code and description are available via $wm->errcode and $wm->errstr accordingly.

METHODS

Constructor

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)
);

get_operations - history of transactions for the given purse (Interface X3)

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

  • ts - a service number of an transaction in the WebMoney system

  • 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)

  • pursesrc - Sender's purse number

  • pursedest - Recipient's purse number

  • amount - money amount

  • comiss - Fee charged

  • opertype - 0 - simple (completed), 4 - protected (not completed), 12 - protected (refunded)

  • period - Protection period in days (0 means no protection)

  • wminvid - Invoice number (in the WebMoney system) of the transaction (0 means without invoice)

  • orderid - Serial invoice number set by the store (0 means without invoice)

  • desc - Description of product or service

  • datecrt - Date and time of transaction

  • dateupd - Date and time of transaction status change

  • corrwm - Correspondent WMID

  • rest - Rest after transaction

invoice - create outgoing invoice (Interface X1)

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.

get_out_invoices - check invoices status (Interface X4)

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

  • storepurse - Number of the purse where funds will be sent to

  • amount - Amount that the customer is to pay

  • desc - Description of product or service

  • address - Delivery address

  • period - Maximum period of protection in days

  • expiration - Maximum valid period in days

  • state - 0 - unpaid, 1 - paid with protection, 2 - paid, 3 - rejected

  • 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

  • customerpurse - Payer purse, if the invoice was paid

transfer - transfer money (Interface X2)

$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)

  • pursesrc - Sender's purse number

  • pursedesc - Recipient's purse number

  • amount - Amount

  • comiss - Fee charged

  • 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

  • desc - Description of product or service

  • datecrt - Date and time of transaction

  • dateupd - Date and time of transaction status change

finish_protect - complete code-protected transaction (Interface X5)

$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;

On error returns undef. On success returns reference to confirmation hash:

  • id - a unique number of transfer in the WebMoney system

  • td - a service number of transfer in the WebMoney system

  • opertype - 0 - simple (completed), 12 - protected (funds were refunded)

  • dateupd - Date and time of transaction status change

reject_protect - reject code-protected transaction (Interface X13)

$wm->reject_protect(
  reqn => 13,
  wmtranid => '123123123',		# Transfer number in the WebMoney system (mandatory)
) or die $wm->errstr;

On error returns undef. On success returns reference to confirmation hash:

  • id - a unique number of transfer in the WebMoney system

  • td - a service number of transfer in the WebMoney system

  • opertype - 0 - simple (completed), 4 - protected (incomplete), 12 - protected (funds were refunded)

  • dateupd - Date and time of transaction status change

message - send message to arbitrary WMID (Interface X6)

$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;

On error returns undef. On success returns reference to confirmation hash.

balance - check purses balance (Interface X9)

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

  • amount - Purse balance

get_in_invoices - get incoming invoices list (Interface X10)

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;

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

  • storewmid - Seller's WMID

  • storepurse - Number of the purse where funds will be sent to

  • amount - Amount that the customer is to pay

  • desc - Description of product or service

  • address - Delivery address

  • period - Maximum period of protection in days

  • expiration - Maximum valid period in days

  • state - 0 - unpaid, 1 - paid with protection, 2 - paid, 3 - rejected

  • 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

money_back - return money without commission (Interface X14)

$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;

On error returns undef. On success returns reference to confirmation hash.

SECURITY

  • 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/

ENVIRONMENT

  • HTTPS_PROXY - proxy support, http://host_or_ip:port

  • HTTPS_PROXY_USERNAME and HTTPS_PROXY_PASSWORD - proxy basic auth

BUGS

The module is not thread-safe.

SEE ALSO

WebMoney::WMSigner - signer module that signs any data using specified WebMoney key file

http://www.webmoney.ru/eng/developers/interfaces/xml/index.shtml - WebMoney API specification

AUTHOR

Alexander Lourier, <aml@rulezz.ru>

COPYRIGHT AND LICENSE

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.