Web services

This page is for Cyclos 3.7. Interfaces have changed slightly since 3.6.1


Cyclos offers several web services, targeted for integration with external applications, using Apache CXF.

Contents

Configuring Web service clients

In order to use web services, there are some concepts which should be understood in Cyclos and some configurations to be done. It is always needed to register a web service client through the Settings > Service clients menu. The client contains the following configuration:

Writing client applications

Here are some general guidelines on how to write client applications to access web services in Cyclos. Take a look at the code samples section for some examples.

Java client

It is very easy to create Java clients for web services, since Apache CXF allows creating transparent proxies using Java interfaces, similar to RMI.
In order to create the client, there are several required library files (jars). The first one is located at <cyclos download dir>/ws/cyclos_xxx_ws_client.jar, and is available on the main distribution package. Others dependencies are also required on runtime. They are available in <cyclos download dir>/web/WEB-INF/lib. They are:

The client application should use the CyclosWebServicesClientFactory class, which may be instantiated with the cyclos root url as constructor argument or it may be set through setter method. Also, when the Service Client registered in Cyclos uses an username / password, they can be set either as constructor arguments or setter methods. Then, it provides two ways to retrieve service interface proxies:

The CyclosWebServicesClientFactory should be instantiated only once and reused between calls. It is thread safe.

Clients in other languages

Many web sites are written in other languages, such as PHP, Ruby, Python, .NET... Those languages often provide a SOAP library. The problem is that some of them don't generate compatible XML with the specification, and some interoperability problems may arise. However PHP, which is the most widely used language for dynamic sites, have a native SOAP client since version 5, which plays well with Cyclos. All WSDLs use the document style for calls, and all methods results have a single element named 'return'.

Code samples

Here are some code samples for web service clients:

Perform payment (java)
Random advertisements (php)
Complete advertisements search form / result (php)
WebShop payment (php)


Available web services

There are several web services in cyclos. A list can be seen at the address: <cyclos root url>/services.

Every method may raise specific fault codes. However, the following codes may be raised by several methods:


Payment

Payment web service allows external applications to generate payments under Cyclos. A typical use case would be a POS (Point-Of-Sale) application installed in a member's office or a website from the organization itself that uses Cyclos as a backend and generates the payments directly.

To perform payments through this web service, a channel should be registered in Cyclos, granted to member groups and members should choose to participate in this channel. It's possible to set by group the default selected channels for new members also.

The most generally used method is doPayment(PaymentParameters), which performs a single payment directly. When the client is restricted to a member, the payment is either from an arbitrary member (with his credentials) to the restricted member, or from the restricted member to other members. The former is the common case for integrating with existing payment systems. When the client is not restricted, then both from and to member should be passed, and no credential is used. A variation of this method is doBulkPayment(List<PaymentParameters>). This method perform several payments in the given sequence, under the same transaction (they are all guaranteed to succeed or fail atomically).

Another possible operation is a payment request. To do this, the registered channel in Cyclos needs to set the URL for a payment request web service, which is a web service implementing the PaymentRequestWebService interface provided in <cyclos mail download dir>/ws/cyclos_xxx_external_ws.jar. Then. a request may be sent using requestPaymentConfirmation(RequestPaymentParameters). A member may then confirm in another channel, which should then invoke confirmPayment(ConfirmPaymentParameters). This is a more advanced feature, and requires other web services to be implemented apart from Cyclos.

Available operations:

doPayment: Performs a single payment, returning the payment status. For clients restricted to a member, one of fromMember or toMember (or setting the toSystem flag) should be passed, with the other one assumed as the restricted member. In this case, when fromMember is used, his credentials should also be informed.

There is a code sample for performing POS payments in a Java client: Web services/POS Payment.

doBulkPayment: Performs several payments, returning a payment status for each input parameter. Has the same input parameter as doPayment(), but in a collection. The result is also a collection, one for each input. It's guaranteed that the size of the result collection is the same as the inputs. Also, if one payment fails, there will be no attempts to perform next payments, they will all have NOT_PERFORMED as status. It is also possible that a payment fails some static validation. If this happens, the payments which fail will have a corresponding status, and the others will be NOT_PERFORMED (even previous ones). So, a possible way to check whether all payments were performed is to check the last status. If it is PROCESSED or PENDING_AUTHORIZATION, it means the bulk was successful.


simulatePayment: Simulates a payment. The input parameters are the same as doPayment(), but the result is only the payment status. No payment is actually performed.


requestPaymentConfirmation: Starts a payment request. The destination member should, using another (or the same) channel, accept this request and a payment is generated.


confirmPayment: Used to confirm a payment request, and should have a matching requestPaymentConfirmation previous invocation.


expireTicket: Then the user will not confirm the payment, a ticket expiration may be sent immediately using this method. Anyway, payment which are not confirmed within 1 hour are expired.


chargeback: Used to chargeback a processed (confirmed) payment a member has received.


doBulkChargeback: Performs several chargebacks, returning a chargeback status for each identifier. Receives a collection of internal identifiers, of payments to be charged back. The result is also a collection, one for each input. It's guaranteed that the size of the result collection is the same as the inputs. Also, if one chargeback fails, there will be no attempts to perform next chargebacks, they will all have NOT_PERFORMED as status. It is also possible that a chargeback fails some static validation. If this happens, failed chargebacks will have a corresponding status, and the others will be NOT_PERFORMED (even previous ones). So, a possible way to check whether all chargebacks were performed is to check the last status. If it is SUCCESS, it means the bulk was successful.


reverse: Used to reverse a payment a member has received but there isn't a confirmation of the payment (if it was processed or not). The third party software that generates the payment can pass a unique number (tracenumber) with the payment. This number can be used to charge back a payment without having to search for the paymentID. The difference is that with a conventional chargeback the third party software needs to get the ID of the payment through a search in Cyclos. This is not necesary with a reverse, as tracenumber is generated by the third party software. The chargeback can be done directly without a search for the transaction.

doBulkReverse: Performs several reverses, returning a chargeback status for each identifier. Receives a collection of internal identifiers, of payments to be reversed. The result is also a collection, one for each input. It's guaranteed that the size of the result collection is the same as the inputs. Also, if one reverse fails, there will be no attempts to perform next reverses, they will all have NOT_PERFORMED as status. It is also possible that a reverse fails some static validation. If this happens, failed reverser will have a corresponding status, and the others will be NOT_PERFORMED (even previous ones). So, a possible way to check whether all reverser were performed is to check the last status. If it is SUCCESS, it means the bulk was successful.


WebShop

External web shops may allow their customers to pay with Cyclos units, and need tickets to do so. The tickets provide a secure mechanism where the web shop can define the transaction data and initiate the payment but does not have access to member authentication data and payment confirmation. In order to do this, both the shop client and the shop itself must have a Cyclos account.

The following flow would be applied for the client member to pay to the web shop member:

  1. The member client selects on the web shop to pay with Cyclos units;
  2. The web shop requests the Cyclos server to create a ticket, passing the transaction information, together with a return url;
  3. The web shop redirects the client into the Cyclos external payment page, passing as parameter the ticket id (<root>/do/webshop/payment?ticket=<ticket id>);
  4. The client types his username and password and confirms the payment;
  5. The Cyclos server validates the payment, and redirects the user back into the specified return url;
  6. The web shops queries Cyclos about that ticket id, and validates the response, and completes the transaction.

It is very important that the web shop validates the ticket, because the client may cancel the payment or do anything, at all.

Normally, each web shop would be registered as a Service Client in Cyclos under Settings > Service Clients. It is a good practice to restrict this client to the member who owns the web shop, so that all payments performed are guaranteed to go to that member.

Available operations:

There is a code sample for performing a WebShop payment in a PHP: Web services/WebShop payment.


Advertisements

Allow searching for advertisements. The organization site might find useful to publish on the institutional web site a list of recent advertisements published on Cyclos, or allow any user to search for advertisements. The advertisements web service allows such operations. The available operations are:

load: Given a numeric identifier named id, returns the details of an advertisement.

fullTextSearch: Searches for advertisements using a full text search technique, which is best suited when the user supplies keywords. The results are ordered by relevance, listing the best results first.

A complete example in PHP of how to search advertisements is available: Web_services/Advertisements search.

search: Searches for advertisements without the full text search technique, and is best suited when the user does not supply a search phrase. Examples would be the last published advertisements, or n random advertisements. The input is an object very similar to the one for fullTextSearch, but has an additional option, randomOrder, which when set to true wull return the advertisements randomly ordered.

A simple example in PHP, listing a few random advertisements is available: Web_services/Random_advertisements.


Members

Allow searching for members, and retrieving data from a given member. Also allows member registration and manipulation of profile fields. The following operations are available:


load: Given a numeric identifier named id, returns a member.


fullTextSearch: Searches for members using a full text search technique, which is best suited when the user supplies keywords. The results are ordered by relevance, listing the best results first.


search: Searches for members, returning a page of members.


registerMember: Registers a new member.


updateMember: Updates fields of an specific member. Fields which are not passed won't be used to update values.


listManagedGroups: Lists the groups managed by the current web service client.


Custom Fields

Since Cyclos allows registering arbitrary fields for members, advertisements and other entities, it also offers this web service to get data about those fields. The following operations are provided:

memberFieldsForMemberSearch: Takes no arguments, and returns an array of member custom fields that may be used to search for members.

memberFieldsForAdSearch: Takes no arguments, and returns an array of member custom fields that may be used to search for advertisements.

memberFields: Takes a group id (optional, defaulting to the first managed group), and returns an array of member custom fields related to that group.

adFieldsForAdSearch: Takes no arguments, and returns an array of advertisement custom fields that may be used to search for advertisements.

possibleValuesForMemberField: Takes an argument named name that is a member custom field internal name, and returns a list of possible values.

possibleValuesForAdField: Takes an argument named name that is an advertisement custom field internal name, and returns a list of possible values.

possibleValuesForAdFieldGivenParent: Takes an argument named name that is an advertisement custom field internal name, and returns a list of possible values for the given parent id.

possibleValuesForMemberFieldGivenParent: Takes an argument named name that is a member custom field internal name, and returns a list of possible values for the given parent id.

paymentFields: Takes a transfer type id and returns an array of member custom fields related to that transfer type.

possibleValuesForPaymentFields: Returns an array of possible values for the given custom field name configured in the given transfer type.

allMemberFields: Takes no arguments and returns an array of all the member custom fields.

allAdFields: Takes no arguments and returns an array of all the advertisement custom fields.


Info texts

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'. It can be used for various channels. For example in the case of SMS users send an SMS to the organization number with a operation command and info text key and Cyclos will return a message with the corresponding respond text. The info text feature also supports a title and rich text. This means it can be used as well by websites to retrieve and publish information that is maintained in Cyclos.

The available operations are:

loadByAlias: Given an alias, returns the matching info text

loadById: Given a numeric identifier, returns the matching info text

search: Searches for info texts according to the given parameters.


Access

It is possible to check via an external channel for pin and channel access data of members. The operations in this service only works for web service clients which are not restricted to a member. Here are the available operations:

checkCredentials: Checks whether the given credentials, associated with the channel this web service client is related, are correct for the given member.


isChannelEnabledForMember: Checks whether the given member allows access to the given channel.


changeCredentials: Changes the credential associated with the web service's channel. Only login password and pin are supported.


Account

This web service allows retrieving information for a member account. When the client is restricted to a member, will only be able to see account information for that member. The available operations are:

getMemberAccounts: Returns which accounts a member have.


searchAccountHistory: Returns both the status (balances, limits...) and account history (credits and debits) for a given member account.


loadTransfer: Returns a single transfer, given it's identifier, or null when not found.


searchTransferTypes: Gets the available transfer types (or payment types) for the given parameters.


POS

New in Cyclos 3.6 is the function to manage POS devices. These devices have an identifier in Cyclos, and can be assigned to members and managed from the main Cyclos interface. The physical POS devices may either be smart enough to access Cyclos directly using this web service or through a gateway, with that gateway communicating with Cyclos with this web service.

Unless returned as status (like on receivePayment and makePayment), operations that uses the POS pin might raise the following fault codes:

Operations might return as status:

The available operations are:

getInitializationData: Should be invoked on POS initialization. Returns several important data and configuration parameters for the POS operation.


receivePayment: The member which is the POS owner receives a payment from another member.

makePayment: The member which is the POS owner performs a payment to another member. May only be used if the POS device is configured to allow making payments.


chargeback: Allows 'undoing' a payment received by the POS owner.

getAccountStatus: Returns an account's status, like balance, reserved amount and available balance.


searchAccountHistory: Returns the account history (credits and debits) for a given member account.


Model data details

Many of the web services operations works with model data. The following elements are available (with their properties):

transfer

accountStatus

accountType

detailedAccountType

transferType

currency

ticket

ad

adCategory

detailedAdCategory

group

member

field

possibleValue

image

page

fieldValue

registrationFieldValue

timePeriod

principalType

infoText