Alexander Lourier > libbusiness-webmoney-perl_0.02.orig > Business::WebMoney

Download:
libbusiness-webmoney-perl_0.02.orig.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.02   Source  

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:

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:

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:

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:

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:

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:

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:

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:

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 ^

ENVIRONMENT ^

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.

syntax highlighting: