User Manager/User payments

Supported payment methods

Authorize.Net (since version 2.9.40 or 3.0beta5) and PayPal (since version 2.9.41 or 3.0beta6) payments are supported.

Authorize.Net

Authorize.Net requirements

To allow Authorize.Net payments for users the following requirements must be met:

• User Manager v3.0 (or v2.9.x, >= 2.9.40) package installed on the router. See: Getting started;
• User Manager subscriber created (See: Getting started);
• Subscriber must have merchant account in Authorize.Net gateway;
• Web server on the router must be configured to support secure SSL connections (See HTTPS connection enabling);
• HotSpot router should contain entries in 'walled-garden to User Manager router and Authorize.net webpage,

/ ip hotspot walled-garden ip add dst-address=x.x.x.x action=accept 

where x.x.x.x is address of User-Manager server,

/ ip hotspot walled-garden add dst-host=:^secure\\.authorize\\.net dst-port=443 action=allow

These entry is used to allow access to Authorize.net

Authorize.Net setup

Authorize.Net merchant account configuration

Relay URL

Relay URL list must either be empty or contain URL to the User Manager router. For example, if you are using userman.mt.lv as User Manager router, then Relay URL list must contain URL https://userman.mt.lv/ (works with and without trailing slash). Relay URL list can be configured in Authorize.Net merchant gateway under Account > Settings > Response/Receipt URLs

API Login ID

API Login ID is shown in Authorize.Net merchant gateway under Account > Settings > API Login ID and Transaction Key.

Transaction Key

Transaction Key can be obtained in Authorize.Net merchant gateway under Account > Settings > Obtain Transaction Key.

MD5-Hash value

MD5-Hash value can be set in Authorize.Net merchant gateway under Account > Settings > MD5-Hash.

WARNING!: Standard MD5 hash values are 32 characters long, however, the Authorize.net MD5-Hash input fields only allow 20 characters. Best chance of success if you paste your md5sum into the Authorize.net input field, then copy it back out to paste into User Manager configuration. By re-copying from the Authorize.net input field, you are selecting only the 20 characters that the field length allows.

Payment Form

Payment Form configuration can be found in Authorize.Net merchant gateway under Account > Settings > Payment Form. The look of this form is customizable here. While the only required fields for processing transaction are credit card number and expiration date, another fields are allowed to be shown in the form. Form customization is up to merchant.

Authorize.Net subscriber configuration

Subscriber attribute values can be edited using customer detail form in customer page.

Subscriber Authorize.Net attributes

Subscribers have a set of specific Authorize.Net attributes which must be configured properly to allow Authorize.Net payments:

• Only subscribers have Authorize.Net attributes, other customers don't;
• Attribute values can be changed only in customer web page, not in console. There is only possibility to change values, not to see them. As these attributes contain sensitive data, their values are encrypted on the router;
• Customer web page must be opened using secure SSL connection (https) to change attribute values;

All the attributes can be found in Authorize.Net attribute group: Authorize.Net attribute group

1. "Allow Payments" must be checked to allow this payment method;
2. Login ID, Transaction Key and MD5 Value must have same values as set in Authorize.Net merchant gateway.
3. Title is optional. It specifies the text shown to users as the name of this payment method. Default title is "Authorize.Net", but it can be changed to something more used to users, for example "Credit Card". The value of this field does not affect the payment process it is only user interface element.

Other subscriber requirements

• Subscriber must have at least one credit with price other than zero. Credit price will be used as transaction amount for the payment;
• Correct currency must be specified for subscriber. If USD is accepted by Authorize.Net merchant, currency attribute can be left unchanged for subscriber:

Subscriber's currency

• If users access User Manager page through a local IP address, public host attribute must be specified. It must contain a public address of User Manager router which is acceptable as Relay URL for Authorize.Net gateway (See: Authorize.Net Merchant account configuration). Domain name or IP address can be used. Only the address must be specified, not URL (for example, userman.mt.lv, not https://userman.mt.lv/ and not https://userman.mt.lv/userman):

Subscriber's public host

Authorize.Net usage

• User can buy credits in User Manager page. First he/she has to log on the page. See: User page.

• Secure connection must be used for web page, so user has to use https://router_IP/user instead of http://router_IP/user (https instead of http).

• Payment section is available on main menu only if subscriber has allowed any payment method.

• To buy credit user chooses "Buy credit" from "Payments" section:

Buy credit

• If https connection is not used for web session, a message with error and link to https site will be opened:

Warning about https

• In this form user chooses credit he/she wishes to buy;

User chooses credit

• Current balance is also shown:

Current balance

• User chooses Authorize.Net as payment method:

Payment method

• When the credit is chosen, "Buy" button must be pressed to start payment transaction:

Buy button

• User is redirected to Authorize.Net gateway payment form, which should look similar to following:

Authorize.Net Payment form

• The actual look of this form can be configured in Authorize.Net merchant gateway

• User fills in credit card number and expiry date. Other fields are optional:

Authorize.Net Payment form filled

• User submits the form::

Authorize.Net Payment form submit

• The data is transmitted directly to Authorize.Net gateway via secure connection. Neither credit card number nor expiry date is submitted to User Manager router.

• Authorize.Net gateway processes the data and sends response to specified User Manager router. This response contains only data required to identify payment in User Manager and detect result status of transaction - was it successful or not. It does not contain any information about the user - credit card number, expiry date or other sensitive data.

• User Manager processes the response and updates payment record status;

• If the transaction was successful requested credit is added to user's account;

• A message describing payment result is shown to user:

Payment successful

• Click on the button redirects the user back to User Manager page:

Payment finished, return button

• User is returned to payment section displaying table with payment history:

Payment history table

PayPal

PayPal requirements

To allow PayPal payments for users the following requirements must be met:

• User Manager v3.0 (>= 3.0beta6) or v2.9.x (>= 2.9.41) package installed on the router. See: Getting started;
• User Manager subscriber created (See: Getting started);
• Subscriber must have merchant PayPal account;
• Web server on the router must be configured to support secure SSL connections (See HTTPS connection enabling);
• HotSpot router should contain entries in 'walled-garden to User Manager router and Paypal webpage,

/ ip hotspot walled-garden ip add dst-address=x.x.x.x action=accept 

where x.x.x.x is address of User-Manager server;

• version 2.9

/ ip hotspot walled-garden add dst-host=:^www\\.paypal\\.com\$ dst-port=443 action=allow 
/ ip hotspot walled-garden add dst-host=:^content\\.paypalobjects\\.com\$ dst-port=443 action=allow 

These two entries are used to allow access to Paypal system.

PayPal setup

PayPal merchant account configuration

Basically there is no specific PayPal account configuration that must be done. The only requirement is to have PayPal account which is allowed to receive money.

Warning! User Manager accepts payment as successful only when it receives status "Completed" from PayPal gateway. If the status is "Pending" and some manual operations must be done by merchant (or the merchant has not verified the account) to accept payment, the credit will be transfered to User Manager user account only when the payment will be accepted.

Note: Since version 2.9.45 and 3.0beta11 it is possible to also accept payments with "Pending" status, except for those with pending reason "unilateral".

PayPal subscriber configuration

Subscriber attribute values can be edited using customer detail form in customer page.

Subscriber PayPal attributes

The only PayPal attribute subscribers have is business login. It is the login (usually an email address) merchants use to log on their account. Only subscribers have this business login, other customers don't;

Since versions 2.9.45 and 3.0beta11 there are also options that refer to PayPal payment processing: "Secure Response" and "Accept Pending".

All the attributes can be found in PayPal attribute group:

PayPal attribute group

1. "Allow Payments" must be checked to allow this payment method;
2. Login (email) must be the PayPal merchant account login.
3. Secure response. When checked, PayPal will send response via HTTPS. Otherwise response will be send via HTTP;
4. Accept pending. When checked, User Manager will also add credit to user if the payment status is "Pending", except for payments with pending reason "unilateral".

Other subscriber requirements

• Subscriber must have at least one credit with price other than zero. Credit price will be used as transaction amount for the payment;
• Correct currency must be specified for subscriber. If USD is accepted by PayPal merchant, currency attribute can be left unchanged for subscriber:

Subscriber's currency

• If users access User Manager page through a local IP address, public host attribute must be specified. It must contain a public address of User Manager router which is acceptable as response URL for PayPal gateway (PayPal will send payment result to this address). Domain name or IP address can be used. Only the address must be specified, not complete URL (for example, userman.mt.lv, not https://userman.mt.lv/ and not https://userman.mt.lv/userman):

Subscriber's public host

PayPal usage

• User can buy credits in User Manager page. First he/she has to log on the page. See: User page.

• Secure connection must be used for web page, so user has to use https://router_IP/user instead of http://router_IP/user (https instead of http).

• Payment section is available on main menu only if subscriber has allowed any payment method.

• To buy credit user chooses "Buy credit" from "Payments" section:

Buy credit

• If https connection is not used for web session, a message with error and link to https site will be opened:

Warning about https

• In this form user chooses credit he/she wishes to buy;

User chooses credit

• Current balance is also shown:

Current balance

• User chooses PayPal as payment method:

Payment method

• When the credit is chosen, "Buy" button must be pressed to start payment transaction:

Buy button

• User is redirected to PayPal gateway payment form, which should look similar to following (PayPal web site can change, these screen shots may differ from actual page):

PayPal Payment form

• User logs on to the account. Payment is now displayed with the Pay button:

PayPal Payment form, user logged in

• When user presses Pay button, PayPal starts to process data. On successful payment result page is displayed:

PayPal success page

• This page contains button "Return to merchant" pressing which returns user to User Manager payment history page:

Payment history table

• User Manager receives data from PayPal indicating Payment status.

• On a successful payment the appropriate credit is added to user.

PayPal chargeback

When a payment changes status from "Approved" to "Aborted" (For example, "Reversed") User Manager tries to remove credit bought for this money. This is however possible only if the two following requirements are met:

• The credit is not started yet;
• The credit is last for current user, i.e., no other credit is bought after this one.

PayPal payment process description

• The payment data is transmitted directly to PayPal gateway. All operation with money and accounts is processed by PayPal. User Manager knows nothing about it.

• PayPal gateway processes the data and after that sends response to specified User Manager router. It may take time, usually not more than one minute. That means that payment may have status "Started" for a few seconds, the status is updated only when PayPal sends response to User Manager;

• If the option "Secure response" is enabled, secure connection (https) is established between PayPal and User Manager;

• When experiencing problems with HTTPS response from PayPal, "Secure response" may be disabled. Then no certificate will be needed on User Manager router to receive PayPal response;

• Again - PayPal response contains only data required to identify payment in User Manager and detect result status of transaction - was it successful or not. It does not contain any information about the user - credit card number, expiry date or other sensitive data;

• User Manager sends request to PayPal to verify that this payment response comes from PayPal and not from a hacker. Because of this verification it is not necessary to receive response from PayPal via https - if a Man-In-The-Middle catches data and sends wrong response to User Manager, the verification fails;

• Response verification requires SSL certificate of root certification authority who has signed PayPal certificate. This root CA certificate is imported automatically and can bee seen in certificate section on the router (console or Winbox);

• User Manager processes the response and updates payment record status;

• If the transaction was successful requested credit is added to user's account;

The payment processing is shown in the following picture:

PayPal payment process description

Related activities

HTTPS connection enabling

Creating certificate

Trusted SSL Certificate can be bought from trusted authorities, for example, VeriSign. An unsigned certificate can be generated by hand, using OpenSSL on a Linux box. To do it issue following commands in the shell:

openssl genrsa -des3 -out server.key 1024
openssl req -new -key server.key -out server.csr
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

Two important things:

1. Enter the same pass phrase always when asked for "Enter pass phrase for server.key" (Should be 4 times);
2. Enter your server's domain name, when asked for "Common Name (eg, YOUR name) []". This is important, because otherwise some browsers may refuse your certificate. For example, if the User Manager server's address is http://userman.mt.lv/userman, then "userman.mt.lv" must be specified as Common Name for the certificate.

After doing this three files will be created:

1. server.crt - Certificate, must be uploaded to router;
2. server.key - Private key, must be uploaded to router;
3. server.csr - Signature request, can/should be deleted;

Upload server.crt and server.key to the router and import them, using the same pass phrase again when asked. server.crt must be imported before server.key.

Importing certificate

Certificate file can be then uploaded to the router and imported with command

/certificate import file-name=...

The command should return

    certificates-imported: 1
    private-keys-imported: 1
           files-imported: 1
      decryption-failures: 0
 keys-with-no-certificate: 0

If it doesn't, could happen that the file contains private key and certificate sections in incorrect order. In this situation the output should be

    certificates-imported: 1
    private-keys-imported: 0
           files-imported: 1
      decryption-failures: 0
 keys-with-no-certificate: 1

Just repeat the same command

/certificate import file-name=...

once again and the output should be this time

    certificates-imported: 0
    private-keys-imported: 1
           files-imported: 1
      decryption-failures: 0
 keys-with-no-certificate: 0

Now certificate is imported correctly and ready for use;

Enabling WWW SSL

SSL connections for WWW server can be enabled with command

/ip service set www-ssl disabled=no certificate=cert1

where cert1 must be replaced by a correct certificate name (from /certificate section)