Operations

From Complete Cyclos documentation wiki
Jump to: navigation, search

Introduction

Clients can perform operations by sending (and receiving) SMS messages using their cell phone. The client cell phone number (callerID) is used for identification. The clients will send the operation messages to a general phone number that belongs to the organization. This can be a normal phone number or a 'short code' (number with less digits than a conventional number). Normally organisations will have two numbers: an 'inbound' number that receives the operation (client) messages (e.g. make payment), and an 'outbound' number that is used to send messages to clients (e.g. mailings, payment confirmations etc)
All SMS operations are described below with the following information:

  • Description
  • Command & parameters
  • Message example
  • Operational flow
  • Images explaining sequences and flows


Note:It is possible to add an additional security step by requiring an temporary session password. This step, called the 'Security confirmation' is not included in the operation descriptions below but described separately in the section security confirmation.

Direct payment

Actor sequence
Comnunication sequence
Operations flow

Description

A member can make a payment to another member by sending just one SMS to the organization number/short code. If the payment has been processed successfully the payer and receiver will receive a confirmation notification by SMS.

Note: the direct payment operation is described without the (optional) security confirmation step.

Command & parameters

The message send by the payer (see message flow diagram) will include the following parameters:

  • Direct payment command or alias (e.g. 'payment' or 'pay')
  • Credential: (e.g. PIN, login password, transaction password, card security code). What credential is used depends on the configuration. In case security confirmation is used the direct payment message does not need to include an credential (because it will be required at a later stage)
  • Receiver: The user that will receive the payment. Depending on the Cyclos and controller configuration this can be the username or any custom field (e.g. mobile phone number)
  • Amount: The amount to pay.
  • Currency: If mobile payments are allowed with more than one currency the user have to put an alias for the currency. This would be quite rare and is not enabled by default. (see also the element currencies in cyclos instances)

Messages example

  1. User (payer) sends message: pay 1234 748596 105 units
  2. Payer receives a message: You have made a payment of 105 units to member Pedro Fernandez (748596). Transaction ID: CY-745236981-1. Your new account balance is 1586.34 units
  3. Receiver receives a message: A payment of 105 units has been received from 748596. Your balance is now 205 units

Operational flow

See diagram Sequence direct payment

  • User (payer) sends a direct payment message to the organization number
  • The mobile phone operator delivers the message to the Cyclos SMS controler (the message might go via a SMS gateway provider but this is transparent)
  • The SMS controller connects to Cyclos and instructs the payment to be done and passes the parameters
  • If the payment is done (no errors) the controller sends a payment confirmation to the Payer
  • The receiver will receive a notification based on his personal notification settings in Cyclos

Payment request (two-way payment)

Actor sequence
Comnunication sequence
Payment request, Operations flow
Payment request confirm, Operations flow
Cyclos payment request, Operations flow

Description

A user can send a payment request to another user by sending an SMS to the organization number indication the user (payer) and the amount. The payer will receive a message that he/she can confirm, after which the payment will be processed. As with a direct payment both payer and receiver will receive a confirmation notification by SMS. Two-way offers higher security, for the receiver because he/she defines the amount to pay (the payer cannot alter the amount), and for the operation as a whole because both payer and receiver are directly involved in the payment process.
An interesting feature of Cyclos is that it is possible to combine payment channels. This means for example that a payment request can be sent from the Cyclos web access page. The requester (business) can send multiple payment requests in a convenient way to clients, who can confirm by SMS. The requester can follow up the requests and payment status in Cyclos.
Note: the payment request operation is described without the (optional) security confirmation step.

Commands & parameters

Message

The user (reciever) sends a message with the following

  • Request payment command alias (e.g. 'rq' or 'request')
  • Payer (either account or phone number)
  • Amount
  • Currency (only if more than one enabled). See also the element currencies in cyclos instances

When the system receives the message it will authenticate the requesting user and send a message the user that has been request to pay. (explained in next section)

Possible errors

  • Authentication failure
  • Transaction canceled (no destination user, user did not confirm within max period/timeout)

Confirmation by payer

The payer will receive a message from the system informing that there is a payment request. The message will contain the requesting user, amount and a session password (this can be generated number or word from a dictionary). In order to confirm (pay) the user has to send a message within a maximum time frame containing the following parameters:

  • Session password
  • Credential

Possible errors

  • Authentication failure
  • Not enough balance
  • Transaction canceled (no destination user, user did not confirm within max period/timeout)

Message example

User Mary Brown with account number 854796 wants user Tim Robinson (748596) to pay 24 units.

  1. Requester (Mary Brown) sends message: rq 748596 24
    (rq is the alias for payment request, 748596 is the account number of the payer, and 24 is the requested amount)
  2. Payer (Tim Robinson) receives message: Mary Brown has send you a payment request of 24 units. Please confirm and pay by sending a message: cf sunset <pin>
    ('cf' is the confirmation command, 'sunset' the temporary (generated) password and 'pin' the credential)
  3. Payer (Tim Robinson) sends message: cf sunset 8546
    (8546 is the credential)
  4. Payer (Tim Robinson) receives confirmation message: You have made a payment of 24 units to Mary Brown (854796) :: transaction ID CY-756321543-1 :: New balance 1.562,25
    (the transaction number and the new current balance are optional).
  5. Requester (Mary Brown) receives confirmation message: You have received a payment of 24 units from member Tom Robinson (748596) :: transaction ID CY-756321543-1 :: New balance 100.00
    (the transaction number and the new current balance are optional).

Operational flows

See diagram Sequence payment request

Message

  • User (requester) sends a payment request message to the organization number
  • The mobile phone operator delivers the message to the Cyclos SMS controler (the message might go via a SMS gateway provider but this is transparent)
  • The SMS controller instructs Cyclos to create a ticket ID and passes the payment request information
  • Cyclos requests the controller to send a confirmation request to the payer, the request is temporarily stored with the ticket ID
  • The controller sends a message to the payer with a generated session password.

Confirmation by payer

  • User (payer) receives message as described above
  • User (payer) now sends a payment confirmation message to the organization number with the requested information
  • The mobile phone operator delivers the message to the Cyclos SMS controller (the message might go via a SMS gateway provider but this is transparent)
  • The controller checks the session password and passes the confirmation data and the ticket ID to Cyclos
  • Cyclos checkes the confirmation data and peforms the payment if everything ok (pin ok, enough balance etc)
  • If the payment is done (no errors) the controller sends a payment confirmation to both the Payer and the Receiver. If the payment request was generated via another channel that SMS the receiver is not notified.

Account information

Actor sequence
Comnunication sequence
Operations flow

Description

A user can send a command to retrieve account information (the current balance and three last payments)

Commands & parameters

  • Aliases: (e.g 'acinfo' and 'detail')
  • Credential: (e.g. PIN)
  • Currency (optional): (this is only needed when the user has accounts with more than one currency, if a user does not specify the currency the default currency will be used). See also the element currencies in cyclos instances
  • Page (Optional): If a user want to see more than the last three payments he/she can specify a number ('2' would return transactions 4,5 and 6)

Messages examples

  1. Member sends message: acinfo 1234 units
  2. Member receive message: Available balance 785,50 UI's :: Transactions 17/05 25,00 :: 20/05 -50,00 :: 25/05 100,00.

It is possible to show the user names with the payments. This is an option in the configuration of the controller
The result message could be as follows: Available balance U$S 785,50. Transactions: 17/05 Daniel Mol. 25,00 :: 20/05 Jane Carso. -50,00 :: 25/05 Andre Car. 100,00.

Operational flow

See diagram Account detail sequence

  • The user sends a message to the organisation number requesting the account information (as described above)
  • The mobile phone operator delivers the message to the Cyclos SMS controler (the message might go via a SMS gateway provider but this is transparent)
  • The controller connects to Cyclos and passes the parameters
  • Cyclos passes the return message to the controller, how will deliver it to the operator.

Note: the account info operation is described without the (optional) security confirmation step.

Info texts

Actor sequence
Comnunication sequence
Operations flow

An administrator can register 'info texts' in Cyclos. Info texts can consist of a word, or a combination of words and they contain a 'respond text'. When users send an SMS to the organization number with an info text Cyclos will return a message with the corresponding respond text.

Commands & parameters

  • Info text: (e.g. 'info', 'info address', 'promo', 'promotion', 'price tomatos')

Messages examples

  1. Member sends message: promo daily
  2. Members receives message: TrendClothing - 30% off in dresses sales

Operational flow

See diagram Info text sequence

  • The user sends a message to the organisation number with the info text in the message (as described above)
  • The mobile phone operator delivers the message to the Cyclos SMS controler (the message might go via a SMS gateway provider but this is transparent)
  • The controller connects to Cyclos and passes the parameters
  • Cyclos passes the return message to the controller, who will deliver it to the operator.


Register new user

Actor sequence
Comnunication sequence
Operation flow

A user with a mobile phone can register him/her self by sending an SMS to the organization number. The user will receive a message informing that his account was created and instructions about the possible operations.

Commands & parameters

  • Aliases: (e.g 'rg' and 'register')
  • Group (optional, if configured the user can specify in which group it will be, in this case the group will need to have a dot . in front of the group name)
  • Login name (optional, can be required by configuration, login name can also be genereated by the system, or the mobile phone number can be used)
  • Credential (e.g. PIN)
  • User name (could be optional, if you are using Login name)

Messages examples

  • Registration with default group
    • Member send message: rg dcorman 8526 Daniel Corman
    • Member receive a message: You have been registered as Daniel Corman with the username dcorman. For information about the possible operations you can send a message with the format "<PIN> info"
  • Registration with group
    • Member send message: rg .sellers dcorman 8526 Daniel Corman
    • Member receive a message: You have been registered as Daniel Corman with the username dcorman. For information about the possible operations you can send a message with the format "<PIN> info"

Operational flow

See Register sequence diagram

  • The user sends a message to the organisation number with the register in the message (as described above)
  • The mobile phone operator delivers the message to the Cyclos SMS controler (the message might go via a SMS gateway provider but this is transparent)
  • The controller connects to Cyclos and passes the parameters
  • If the operation was successfully in Cyclos, the controller generate a confirmation message and pass it to the Driver, which will deliver it to the operator.

Important considerations

  • All returned message about registration command cannot be charged to the member. It will always be charged to the system/configuration
  • The registration will fail if a user with the same phone number exists in the system.
  • The registration will fail if a user with the same login name exists in the system. (in the case a login name is not generated by the system).
  • The groups defined as defaultInitialGroup or aliasGroup (see Operation settings) will need to have the group setting set (in Cyclos) as follows initial group: Yes

Personal notifications & Mailings

Allthough personal notifications and mailings are not operations that can be initiated by sending an SMS they still make use of the SMS channel and are described shortly to give a complete picture of the SMS module.

Personal notifications

A user can activate automatic notifications on events such as balance change, reminders of outstanding loan repayments and newly granted credit, etc. Notifications can also be enabled for the e-commerce module. That means that clients can receive a notification upon received referrals, or when there is a match with an 'offer' or a 'want' in the market place. Depending on the client configuration the alerts and notifications will be sent as internal Cyclos message, e-mail, SMS, or a combination of them. In the case users have no web access the notifications can be defined as default (group) setting upon user creation. An administrator or broker, or the user him self can change these settings at a later stage via the web interface.

Mailings

Administrators and loan agents can send messages to individual clients or mailings to groups of clients. Group mailings are typically news messages and general notices. The SMS mailings are sent via the Web interface. (This is another example of the internal routing facility of Cyclos. Mailings, in the same way as payment requests described above, can be initiated via web). The SMS module has various option for charging. There can be "free" and "charged" mailings. A user can register and unregister SMS group mailings.


Security confirmation

The security confirmation is not a 'stand-alone' operation but an additional step that can be required within an other operation in order to provide more security. What it does is that between the initial request (e.g. direct payment message send by a user) and the operation to be performed (e.g. payment done) an intermediate step is required. In case of a direct payment it would be as follows:

  1. User (payer) sends message: For example pmt 748596 105 units (note, credential is not included)
  2. * User receives message: Please confirm the payment: pmt 748596 105 units by sending: cf <SessionId> <your pin>
  3. * User sends: cf <SessionId> <your pin>
  4. Payer receives a message: You have made a payment of 105 units to member Pedro Fernandez (748596). Transaction ID: CY-745236981-1. Your new account balance is 1586.34 units
  5. Receiver receives a message: A payment of 105 units has been received from 748596. Your balance is now 205 units

One Time Password (OTP)

When a security confirmation password is used, or when a payment request is issued, the responsible is prompted to confirm an action using a unique session key and her PIN (the pin may not be required, see the parameters usePin and usePinInConfirm in Operation settings). The unique session key is termed One Time Password (OTP).

The OTP can be a word generated dynamically by the system or can be extracted from a dictionary in the database. The definitive behavior is determined by the parameters config.xml->controller->sessionSettings (see Operation settings)

OTP from a dictionary

Using OTP with a dictionary should be simpler for the user as it will be easier for her to remember the session key word with which to confirm her actions (even being different every time).

The dictionary of words to be used by the system must be loaded in the session_key table of the Controller database (see Database settings->url)


Custom operations

It is possible to create new customized commands to the ones predefined by the system, for more details please see the section Custom Operations