Ext WMKeeper

The article is out of dateThe article is out of date

The Keeper Embedded service is a set of web methods enabling financial interaction between the members of a social network.

The service allows members of a social network to create virtual purses in different currencies, associate existing WebMoney purses with their accounts, transfer funds and generate invoices to other members of the social network, recharge their mobile phone accounts and do a lot more.

Each social network supporting Keeper Embedded has its own number (SNID) that must be passed as a parameter to all methods of the service. Each network also has a unique secret key that is used for generating a (hash) signature that is also passed as a parameter to all methods of the service. The system uses the SHA1 algorithm for signature generation.

The methods sendFunds, issueInvoice, issueInvoiceToWMID, payInvoice, rejectInvoice, topUpByCard, topUpPhoneall accept the RequestN parameter. This is a 64-bit integer that must be unique for each social network - that is, for each SNID

The following methods are currently available in Keeper Embedded:

1. Creation of a member's purse.

int createPurse(int SNID, string USID, char Purse, string hash, out string errordesc)

• Passed parameters: SNID - social network ID, Purse - type of the purse being created, USID - member's ID, hash - hash (SHA1) value of a string in the following form: SNID+USID+Purse+SecretKey.
• Returned parameters: errordesc - error description.
• Returned value: error code or 0 if there is no error.

2. A member can connect a purse by clicking the following link

https://ext.wmkeeper.com/WMAPI/AddPurse.aspx?SNID={0}&USID={1}&ReturnUrl={2}&hash={3},

where SNID - social network ID, USID - member's ID, ReturnUrl - the URL the member should be forwarded to after the purse is connected (this is also the page where the following parameters will be passed to: USID (matching the original value), err (containing a request processing error code), hash (containing a hash value of a string in the following form: USID+err+SecretKey)), hash - a hash (SHA1) value of a string in the following form: SNID+USID+ReturnUrl+SecretKey. All URL's containing parameters must be unencoded.
Once the purse has been connected, the member must activate their account using the activation code sent to their WM Keeper. Activation is performed using the activatePurse method (see #21) or by following the link sent to the member's WM Keeper.

3. Removing a purse (removal of an existing (not connected) purse is only possible if the current purse balance is zero).

int removePurse(int SNID, string USID, char purse, string hash, out string RedirectURL, out string errordesc)

• Passed parameters: SNID - social network ID, USID - member's ID, Purse - type of the purse being removed, hash - hash (SHA1) value of a string in the following form: SNID+USID+Purse+SecretKey.
• Returned parameters: RedirectURL - URL of the page where the member can cancel trust (if a connected purse is being removed) or an empty sting, errordesc - description of a request execution error
• Returned value: error code or 0 if there is no error.

4. Obtaining the list of member's purses.

int getUserPurses(int SNID, string USID, string hash, out char[] purses, out string errordesc)

• Passed parameters: SNID - social network ID, USID - member's ID, hash (SHA1) value of a string in the following form: SNID+USID+SecretKey.
• Returned parameters: Purses - an array of characters corresponding to purse types, errordesc - error description.
• Returned value: error code or 0 if there is no error.

5. Getting a member's account balance and determining whether the member is allowed to create new purses and connect existing purses to their account

int getUserPursesBalance(int SNID, string USID, string hash, out bool AllowPurseCreation, out bool AllowPurseAddition, out PurseBalanceEntry[] PursesBalances, out string errordesc)

• Passed parameters: SNID - social network ID, USID - member's ID, hash - hash (SHA1) value of a string in the following form: SNID+USID+SecretKey.
• Returned parameters: AllowPurseCreation - determines whether the member can create purses, AllowPurseAddition - determines whether the member can connect existing purses to their account, Purses - an array of structures of the following form:
   struct PurseBalanceEntry
   {
     public char Purse; //purse type
     public double Balance; //purse balance
     public bool Activated; //purse activation status
   },
  errordesc - error description.
• Returned value: error code or 0 if there is no error.

6. Transferring funds between members.

int sendFunds(int SNID, long RequestN, string srcUSID, string destUSID, char purse, double amount, string description, string hash, out string errordesc)

• Passed parameters: SNID - social network ID, RequestN - unique request number, srcUSID - sender's ID, destUSID - recipient's ID, Purse - purse type, Amount - amount to be transferred in the specified currency, Description - transaction description, hash - hash (SHA1) value of a string in the following form: SNID+RequestN+srcUSID+destUSID+Purse+Amount+Description+SecretKey, where Amount is specified in the '#0.00' format.
• Returned parameters: errordesc - description of a request execution error.
• Returned value: error code or 0 if there is no error.

7. Getting the value of the maximum transferable amount.

int getMaxTransactionAmount(int SNID, char purse,string srcUSID, string destUSID, string hash, out double MaxAmount, out string errordesc)

• Passed parameters: SNID - social network ID, srcUSID - sender's ID, destUSID - recipient's ID, Purse - purse type, hash - hash (SHA1) value of a string in the following form: SNID+srcUSID+destUSID+Purse+SecretKey.
• Returned parameters: errordesc - description of a request execution error
• Returned value: error code or 0 if there is no error.

8. Creating an invoice for another member.

int issueInvoice(int SNID, long RequestN, string srcUSID, string destUSID, char purse, double amount, int days, string description, string hash, out long InvID, out string errordesc)

• Passed parameters: SNID - social network ID, RequestN - unique request number, srcUSID - sender's ID, destUSID - recipient's ID, Purse - purse type, Amount - amount to be transferred in the specified currency, Description - transaction description, hash - hash (SHA1) value of a string in the following form: SNID+RequestN+srcUSID+destUSID+Purse+Amount+Days+Description+SecretKey, where Amount is specified in the '#0.00' format.
• Returned parameters: InvID - ID of the issued invoice, errordesc - description of a request execution error
• Returned value: error code or 0 if there is no error.

9. Sending an invoice to a WebMoney user.
int issueInvoiceToWMID(int SNID, long RequestN, string srcUSID, string destWMID, char purse, double amount, int days, string description, string hash, out long InvID, out string errordesc)

• Passed parameters: SNID - social network ID, RequestN - unique request number, srcUSID - sender's ID, destWMID - WebMoney WMID of the recipient, Purse - purse type, Amount - amount to be transferred in the specified currency, Days - invoice validity period, Description - invoice description, hash - hash (SHA1) value of a string in the following form: SNID+RequestN+srcUSID+destUSID+Purse+Amount+Days+Description+SecretKey, where Amount is specified in the '#0.00' format.
• Returned parameters: InvID - ID of the issued invoice, errordesc - description of a request execution error
• Returned value: error code or 0 if there is no error.

10. Paying an invoice.
int payInvoice(int SNID, long RequestN, string USID, long InvID, string hash, out string errordesc)

• Passed parameters: SNID - social network ID, RequestN - unique request number, USID - member's ID, InvID - invoice number, hash - hash (SHA1) value of a string in the following form: SNID+USID+InvID+SecretKey.
• Returned parameters: errordesc - description of a request execution error
• Returned value: error code or 0 if there is no error.

11. Rejecting an invoice
int rejectInvoice(int SNID, long RequestN, string USID, long InvID, string hash, out string errordesc)

• Passed parameters: SNID - social network ID, RequestN - unique request number, USID - member's ID, InvID - invoice number, hash - hash (SHA1) value of a string in the following form: SNID+USID+InvID+SecretKey.
• Returned parameters: errordesc - description of a request execution error
• Returned value: error code or 0 if there is no error.

12. Adding funds to a purse via a Paymer prepaid card (check).

int topUpByCard(int SNID, long RequestN, string USID, char purse, string CardNumber, string CardCode, string hash, out double Amount, out string errordesc)

• Passed parameters: SNID - social network ID, RequestN - unique request number, USID - member's ID, Purse - type of the purse the funds will be transferred to, CardNumber - the number of the prepaid card (check), CardCode - the PIN code of the prepaid card (check), hash - hash (SHA1) value of a string in the following form: SNID+RequestN+USID+Purse+CardNumber+CardCode+SecretKey.
• Returned parameters: Amount - payment amount, errordesc - description of a request execution error
• Returned value: error code or 0 if there is no error.

13. Recharging a phone account from a member's purse.

int topUpPhone(int SNID, long RequestN, string USID, string PhoneNumber, double Amount, char Purse, string hash, out int TranID, out string errordesc)

• Passed parameters: SNID - social network ID, RequestN - request number (must be unique), USID - member's ID, PhoneNumber - phone number in the 9161231212 format, Amount - amount to be transferred, Purse - the type of the purse the funds will be withdrawn from, hash - hash (SHA1) value of a string in the following form: SNID+RequestN+USID+PhoneNumber+Amount+Purse+SecretKey, where Amount is written in the '#0.00' format.
• Returned parameters: errordesc - error description.
• Returned value: error code or 0 if there is no error.

14. Getting the history of a member's transactions for a period of time

int getHistory(int SNID, string USID, DateTime start, DateTime finish, string hash, out HistoryEntry[] History, out string errordesc)

• Passed parameters: SNID - social network ID, USID - member's ID, dateStart - start of the period, dateFinish - end of the period, hash - hash (SHA1) value of a string in the following form: SNID+USID+dateStart+dateFinish+SecretKey, where dateStart and dateFinish are specified in the 'yyyy/MM/dd HH:mm:ss' format
• Returned parameters: History - an array of structures of the following types:
   struct HistoryEntry
   {
    DateTime Date; //date of operation
    char Purse; //purse type
    string SourceUSID; //sender's ID or WMID (see SourceIsWMID)
    string DestinationUSID; //recipient's ID
    double Amount; //amount
    double Fee; //transaction fee
    double PurseRest; //remaining balance of the member's account
    bool InvoicePaid; //indicates whether the transaction was a payment against an invoice
    bool SourceIsWMID; //indicates whether SourceUSID is the sender's WMID
    string Description; //comment
   },
  errordesc - error description.
• Returned value: error code or 0 if there is no error.

15. Getting a list of incoming invoices for a period of time

int getIncomingInvoices(int SNID, string destUSID, DateTime dateStart, DateTime dateFinish, string hash, out InvoiceEntry[] Invoices, out string errordesc)

• Passed parameters: SNID - social network ID, USID - member's ID, dateStart - start of the period, dateFinish - end of the period, hash - hash (SHA1) value of a string in the following form: SNID+USID+dateStart+dateFinish+SecretKey, where dateStart and dateFinish are specified in the 'yyyy/MM/dd HH:mm:ss' format
• Returned parameters: Invoices - an array of structures of the following types:
   struct InvoiceEntry
   {
    DateTime Date; //Date of invoicing
    long InvID; //Invoice ID
    string USID; //Invoice sender's ID
    char Purse; //Purse type
    double Amount; //Amount due
    bool DestIsWMID; //Specifies whether the invoice was sent to a WebMoney member
    int ExpirationDays; //Invoice expiry period
    int State; //Invoice state (0 - paid, 1 - not paid, -1 - declined)
    string Description; //Invoice comment
   },

errordesc - error description.

• Returned value: error code or 0 if there is no error.

16. Getting a list of outgoing invoices for a period of time

int getOutgoingInvoices(int SNID, string USID, DateTime dateStart, DateTime dateFinish, string hash, out InvoiceEntry[] Invoices, out string errordesc)

• Passed parameters: SNID - social network ID, destUSID - member's ID, dateStart - start of the period, dateFinish - end of the period, hash - hash (SHA1) value of a string in the following form: SNID+USID+dateStart+dateFinish+SecretKey, where dateStart and dateFinish are specified in the 'yyyy/MM/dd HH:mm:ss' format
• Returned parameters: Invoices - an array of structures of the following types:
   struct InvoiceEntry
   {
    DateTime Date; //Date of invoicing
    long InvID; //Invoice number
    string USID; //ID or WMID of the recipient (see the DestIsWMID parameter)
    char Purse; //Purse type
    double Amount; //Amount due
    bool DestIsWMID; //Indicates whether this invoice was sent to a WebMoney member
    int ExpirationDays; //Invoice expiration period
    int State; //Invoice state(0 - paid, 1 - not paid, -1 - declined)
    string Description; //Invoice comment
   },

errordesc - error description.

• Returned value: error code or 0 if there is no error.

17. Getting the history of a member's account recharges using prepaid cards (checks) for a period of time.

int getCardTopUpHistory(int SNID, string USID, DateTime dateFrom, DateTime dateTo, string hash, out CardTopUpHistoryEntry[] History, out string errordesc)

• Passed parameters: SNID - social network ID, USID - member's ID, dateStart - start of the period , dateFinish - end of the period, hash - hash (SHA1) value of a string in the following form: SNID+USID+dateStart+dateFinish+SecretKey, where dateStart and dateFinish are specified in the 'yyyy/MM/dd HH:mm:ss' format.
• Returned parameters: History - an array of structures of the following types:
   struct CardTopUpHistoryEntry
   {
     dateTime Date; //date of operation
     string USID; //member's ID
     string CardNumber; //card (check) number
     string CardCode; //card (check) PIN code
     double Amount; //amount
     char Purse; //type of destination purse
   },
  errordesc - description of a request execution error
• Returned value: error code or 0 if there is no error.

18. Getting the history of a member's phone account recharges for a period of time.

int getPhoneTopUpHistory(int SNID, string USID, DateTime dateFrom, DateTime dateTo, string hash, out PhoneTopUpHistoryEntry[] PhoneTopUpHistory, out string errordesc)

• Passed parameters: SNID - social network ID, USID - member's ID, dateStart - start of the period , dateFinish - end of the period, hash - hash (SHA1) value of a string in the following form: SNID+USID+dateStart+dateFinish+SecretKey, where dateStart and dateFinish are specified in the 'yyyy/MM/dd HH:mm:ss' format.
• Returned parameters: PhoneTopUpHistory - an array of structures of the following types:
   struct PhoneTopUpHistoryEntry
   {
    dateTime Date; //date of operation
    string USID; //member's ID
    char Purse; //type of purse (payment currency)
    double Amount; //amount transferred in the specified currency
    string PhoneNumber; //phone number
    int State; //operation state code
    string Provider; //provider's name
    string Description; //comment
   },
  errordesc - description of a request execution error
• Returned value: error code or 0 if there is no error.

19. Getting the result of a phone account recharge

int getPhoneTopUpState(int SNID, string USID, int TranID, string hash, out int State, out string errordesc)

• Passed parameters: SNID - social network ID, USID - member's ID, TranID - unique transaction number, hash - hash (SHA1) value of a string in the following form: SNID+USID+TranID+SecretKey.
• Returned parameters: State - operation completion state (0 - successful, 1 - pending, -1 - recharge failed), errordesc - description of a request execution error
• Returned value: error code or 0 if there is no error.

20. Activation of a member's connected purse.

int activatePurse(int SNID, string USID, char purse, string ActivationCode, string hash, out string errordesc)

• Passed parameters: SNID - social network ID, USID - member's ID, Purse - purse type, ActivationCode - activation code, hash (SHA1) value of a string in the following form: SNID+USID+Purse+ActivationCode+SecretKey.
• Returned parameters: errordesc - error description.
• Returned value: error code or 0 if there is no error.

The activation code is sent to the member's WebMoney Keeper immediately after the purse is connected.

21. Getting information about a member.
int getUserInfo(int SNID, string USID, string hash, out UserInfo userInfo, out string errordesc)

• Passed parameters: SNID - social network ID, USID - member's ID, hash - hash (SHA1) value of a string in the following form: SNID+USID+SecretKey.
• Returned parameters: userInfo - a structure of the following type:
   struct UserInfo
   {
    string FirstName; //member's name
    string MiddleName; //member's middle name
    string LastName; // member's last name
    string EMail; //member's еmail
    string Phone; //member's phone
    string Address; //member's address
    string URL; //home page
    string PassportType; //type of the member's certificate (110 - Formal passport, 120 - Initial passport, 130 - Personal passport, 135 - Merchant passport).
   },
  errordesc - error description.
• Returned value: error code or 0 if there is no error.

Error codes:

• 0 - Operation successful;
• 1 - Signature validation error;
• 2 - This purse already exists;
• 3 - This purse (purses) does not exist;
• 4 - Cannot add a purse;
• 5 - Invalid parameters;
• 6 - Invalid recipient purse;
• 7 - WebMoney error;
• 8 - No operations in the specified period of time;
• 9 - An operation with this RequestN has already been performed;
• 10 - Incorrect amount;
• 11 - No invoices in the specified period of time;
• 12 - Unknown member;
• 13 - Invalid activation code;
• 14 - Invalid WMID;
• 15 - Purse is not empty;
• 16 - Insufficient funds in the purse;
• 17 - This member doesn't exist;
• 18 - Invalid currency;
• 19 - Invalid account (phone, invoice, agreement number);
• 20 - Unauthorized operation;
• 21 - Incorrect time period;
• 400 - TimeOut;
• 500 - Server error.